popagent

public

Latest change 55527c0e19ee3bca43283d82535483ba49374b59 - Resolve reviewed terminal tasks inline by Ólafur Búi Ólafsson

# 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 the ignored `workspace/**` agent checkouts from test
discovery and application typechecking. 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.
- `./deploy.sh publish` is the only publication path. 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` is the only deployment path. From Midget it 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 agent and skill configuration, workspace documentation, tasks—including evidence-backed terminal resolution—schedules, and settings; `popagent api` remains the raw fallback. Keep the CLI and the built-in `popagent-cli` agent skill synchronized whenever an API or operator workflow gains, changes, or removes an agent-usable operation. Commands must finish in one invocation, emit machine-readable API output unchanged, accept credentials only from environment variables, and never print them.

## 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.