# agent

The bounded agent runtime's app integration: durable runs with step state, the approval queue a
person reviews, and the run controls. The run's tool calls go through the organization's tool
registry with the app's scoped deployment credentials (`apps/worker/src/ports.ts` binds
`AGENT_TOOLS`); the platform owns dispatch policy, spend admission and the run ledger.

## Why the module is Postgres-only (no Convex profile yet)

`module.convex.ts` ships a fail-closed Convex binding for a future wiring, but the module is
**not** registered in the Convex profile (`convex/lib/runtime.ts`), and the manifest stays
`profiles: ["postgres"]`. The integration review (2026-10-23) kept it Postgres-only because the
run cannot execute on the Convex runtime today:

1. The `agent.run` **job** leaves the process on every step — the tool registry, the AI gateway,
   and whatever the managed tools call. Convex queries/mutations cannot perform network I/O; the
   Convex binding fails closed (`… must run through the Convex Node action boundary`) and, unlike
   documents' `documentsActions:process`, no composed Node action exists for the run job yet.
2. A run's steps must recheck policy and meter through the platform between actions; that
   orchestration lives in the worker, and a partial registration would let a project start runs
   that always dispatch into the fence.

The read/write procedures (run list/get, cancel, approval review) would technically run in Convex
transactions, but registering the module for metadata alone — while every started run fails — is
a registered-broken feature, not a fail-closed gate. Wiring the profile means composing the run
job's Node action first (mirror `convex/documentsActions.ts`).