popagent

Latest change b6d33c15415ad98991d8aaafd44b4b993d19db65 - Add popagent settings-patch and document agent step-budget mechanics by AkurAI Build

# Repository rules

## Run

- `bun run dev` (watch) / `bun run start` serves UI and API on `PORT`
  (default 3000).
- The Bun process requires `DATABASE_URL` and the isolated
  `OBSERVABILITY_DATABASE_URL`. Secret-tool operations additionally require
  `POPAGENT_SECRET_KEY`; `POSTGRES_PASSWORD` and
  `OBSERVABILITY_POSTGRES_PASSWORD` bootstrap the Compose databases. 9Router,
  SearXNG, retention, environment, and managed-hook settings are documented in
  `.env.example`.
- Development is test-driven for every observable behavior change. Before
  implementation, add or update the narrowest automated contract that fails for
  the missing behavior or regression. Confirm that the failure is relevant,
  then implement until it passes. A behavior-preserving refactor may begin from
  green characterization tests, but must not reduce coverage.
- `bun test <file>` is the preferred inner loop for the changed contract.
  `bun test` runs the full suite before handoff; `bunfig.toml` and
  `tsconfig.json` exclude ignored `workspace/**` agent checkouts from test
  discovery and application typechecking. Managed autonomous checkouts under
  `data/self-update/**` are excluded for the same reason: they are runtime data,
  not a second source tree. Run isolated protocol/UI-helper tests, TypeScript
  checks, and other deterministic toolchain checks locally for fast feedback.
  Use disposable local PostgreSQL when a storage test needs it.
- Match tests to the changed boundary: stores need persistence and migration
  contracts; routes need status, validation, authentication, and response-shape
  contracts; event streams need connect, event, disconnect, and reconnect
  contracts; React changes need runtime coverage for mount, update, navigation,
  and unmount behavior. A TypeScript check is never a runtime-test substitute.
- Tests must remove every database row, Mastra thread, filesystem artifact, and
  runtime session they create, and restore singleton settings and environment
  variables even when an assertion fails. Use `finally`, `afterEach`, or a tracked
  `afterAll` fallback rather than relying on disposable infrastructure alone.
- Tests that call live 9Router models or shared services run on Titan. Start
  narrow, expand to the affected suite after green, and run the full suite once
  at the end; do not repeatedly pay for project-wide verification while editing.
- Domain files name contract owners and environment-specific exceptions only;
  keep this test sequence canonical instead of repeating it per subsystem.
- Do not report behavior as fixed, complete, working, or verified until all
  required checks have run after the final relevant edit. Report exact commands
  and results, distinguish narrow checks from the full suite, and disclose every
  skipped, unavailable, flaky, or environment-dependent check. For a reported
  regression, reproduce it first and add an automated regression contract before
  changing implementation whenever technically possible.
- UI changes require desktop and mobile browser verification after the final UI
  edit. At minimum exercise initial load, applicable loading/empty/error states,
  the changed interaction, route navigation, and component unmount/remount, then
  inspect console errors and failed requests. Streaming UI must additionally
  verify connection, event delivery, cancellation, route-away cleanup, reconnect,
  and polling fallback. Helper tests alone do not satisfy this browser gate.
- The running instance is `http://192.168.1.10:5180` on Titan. PostgreSQL
  container `popagent-postgres` binds only `127.0.0.1:5433`; durable data is in
  volume `popagent-postgres`. Observability PostgreSQL container
  `popagent-observability-postgres` binds only `127.0.0.1:5435` with durable
  state in volume `popagent-observability-postgres`. The `omniroute` container provides 9Router on
  `127.0.0.1:20128` with durable state in volume `omniroute-data`. SearXNG
  container `popagent-searxng` binds only `127.0.0.1:8889` and provides the
  agents' JSON web-search API.

## Source and deployment workflow

- The public AkurAI Build repository at `https://akurai-build.olibuijr.com/git/popagent.git` is the Git synchronization boundary. Keep it free of credentials and runtime data. Commit locally; never copy or rsync source between Midget and Titan.
- `.akurai.yml` is the managed CI/CD entrypoint. Its native verification job
  installs the locked Bun dependencies, runs TypeScript and the isolated full
  suite, then exposes a protected production deployment that invokes the trusted
  Titan checkout's `deploy.sh deploy`; AkurAI Build promotion is the only
  production trigger.
- `./deploy.sh publish` is the only publication path; agents may run it directly to push a clean, tested `main` to the AkurAI Build Git boundary. It requires a clean `main`, runs built-in privacy checks plus Gitleaks when installed, and accepts optional Git credentials only through transient `POPAGENT_GIT_USERNAME`/`POPAGENT_GIT_TOKEN` environment variables.
- `./deploy.sh deploy` performs the actual restart-and-verify sequence, but an agent must NEVER invoke it directly. The only way to trigger it is the `.akurai.yml` `deploy` job's protected `production` environment, approved through `akurai_run_promote`. That job runs this exact command over the trusted Titan checkout. From Midget the script verifies that HEAD is published, then triggers Titan over SSH; on Titan it refuses dirty/divergent work, fast-forwards from public `main`, and locks concurrent deployment. If the fast-forward changes `deploy.sh`, it explicitly unlocks before re-executing the updated script. Changes limited to `src/ui/**` and `AGENTS_UI.md` stop after the fast-forward because Bun serves those assets directly; they do not install dependencies, provision test databases, run the full suite, or restart the service.
- Deployments containing non-UI changes start required local Compose dependencies, install packages only when `package.json` or `bun.lock` changed, provision disposable test databases, run TypeScript and the full suite, validate a candidate on a temporary port, briefly restart systemd, monitor protected `/api/health`, and roll back a failed release. Dependency health probes are silent during retries and emit errors only on the final failed attempt. SQL changes trigger mode-restricted application and observability dumps from the unique running containers publishing the configured local database ports under `POPAGENT_DATA_DIR/backups`; the newest ten are retained. Migrations must remain backward-compatible across the candidate and previous release.
- Deployment prefers a user systemd service and installs a system service only when run as root. Do not manually restart `popagent.service`, mutate the deployed checkout, or bypass the applicable gate. Deployment logs and the current backend release marker live under `POPAGENT_DATA_DIR/deploy`.
- Credentials belong in the ignored mode-0600 `.env`; application-managed secrets belong in PostgreSQL through the secret tools. Do not create or use `.secrets/`. Missing deployment configuration is an error, never a reason to generate or restore credentials.
- Every behavior, architecture, configuration, or operating-rule change must update the relevant `AGENTS*.md` domain file in the same change. Remove stale facts instead of preserving historical guidance or duplicating another domain.
- `./popagent help` is the canonical one-shot command index for AI agents. Named commands cover agents, skills, workspaces, deterministic repository briefs, local code context/symbol/impact inspection, documentation, tasks—including bounded `workflow-tasks [workspace]`, exact `task <id>` evidence lookup, `tasks-attention [workspace]` for the Needs attention bucket (`failed`/`cancelled`/`dead-letter`), `task-requeue <task-id> [model]` to resubmit a terminal task's original workspace/prompt as a fresh queued task once its cause is fixed, and evidence-backed terminal resolution—automation status/run/reconciliation, evolution signals, schedules, and settings; `popagent api` remains the raw fallback. Settings routes validate a whole section and reject unknown keys, so `settings-update <section> <json>` replaces the section and `settings-patch <section> <json>` is the way to change individual fields: it reads the current section, drops the server-owned `updatedAt`, merges the given fields, and PATCHes the result. `automation-reconcile` creates missing system schedule defaults without overwriting operator timing. Schedule updates may change only operator timing and enablement for system rows.
- Automatic remediation-task creation only fires on a settled `failed` transition (`createRemediationTask` in `src/tasks.ts`); a `cancelled` task never receives an automatic remediation task and stays in Needs attention until an operator runs `task-requeue`.
- Popagent Docs is the canonical project-documentation store. Repository registration, first commit, architecture, and deployment-state changes update the affected repository's Project Index through the named `doc-search`, `doc-read`, and `doc-save` commands. Never create or update AkurAI Notes; it is retained only as a legacy import source.
- `package.json` owns the user-visible `x.x.x` application version. `./deploy.sh
  version` reads it and `./deploy.sh version <x.x.x>` updates it; the browser
  imports the same value at bundle time and renders it below the Popagent sidebar
  brand. Every deployment must increase this version relative to the recorded
  production release.
- Every deployment must include a meaningful `CHANGELOG.md` update relative to
  the recorded production release. `deploy.sh deploy` enforces both release
  gates before UI-only or backend deployment paths can proceed.
- Idle Build maintenance uses the persisted `source='build-maintenance'` task
  and schedule lineage for the writable AkurAI-Build workspace. A process-local
  autonomous lease and the database active-work gate both prevent overlap with
  interactive or other autonomous work. It may queue CI and publish reviewed
  branch/run/issue evidence, but it must never select Release Manager, promote a
  protected environment, deploy, restart services, or call production promotion
  tools. Managed deployment reuses CI verification only when the exact release
  revision and UTC timestamp evidence (`YYYYMMDDTHHMMSSZ`) are supplied.

## Documentation layout

- `AGENTS.md` is an index only. Put operating rules and durable domain facts in
  the linked domain files.
- `.agents/skills/` contains task-triggered, repeatable workflows. Skills must
  reference the canonical domain files instead of copying architecture or
  policy into their instructions.
- Keep safety boundaries and facts required for every related change in the
  domain files; do not hide them exclusively in a skill whose loading is
  conditional.
- Keep each `AGENTS*.md` file at or below 500 lines. Split any file that exceeds
  500 lines into focused `AGENTS_$DOMAIN.md` files and add each new file to the
  index.

## Style

Ponytail: use the smallest solution that works; prefer native or installed
capabilities over new code; avoid speculative abstractions. The TDD and
verification gates above apply even when the implementation appears trivial.