Files
template-app/modules/agent

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