Agent Runs

Agent Runs

One agent run per dialog. Every run is started explicitly by the user and runs a bounded tool-use loop (deterministic ReAct runner) inside budgets and approvals, with step events streamed to the UI as agent-run-event frames.

Lifecycle

• Commands: start, cancel, pause, resume, extend (iteration budget), set-mode, resolve-approval, plus read surfaces (runs, steps, inspect, spend-dashboard, activity-feed, permission rules).
• Run statuses persisted in agent_runs: running, completed, cancelled, budget_exhausted, spend_limit_exceeded, error. Terminal rows carry finished_at and either final content or classified error text.
• Pause/resume/cancel are user controls; extend raises the iteration budget; nothing runs on a schedule and there are no background daemons.

Steps and history

• agent_steps records one row per model-turn marker, tool call, and parked approval decision, ordered by seq, immutable after insertion.
• Each step carries tool name, raw provider JSON args, observation/decision text, outcome (succeeded, failed, denied, cancelled), timing, optional rule provenance (rule_id, group_key, decided_by), and optional token counts.
• A read-only inspector, activity summaries, and run/step history views expose past runs; deleting a run cascades to its steps, and deleting a conversation cascades to its runs.

Tasks (bounded plan → act → verify → report)

• agent_tasks rows (title, status pending/running/completed/failed/cancelled, provider/model, max_steps 1–25 default 25, progress cursor, report, latest run link) with agent_task_steps children (own status, result text, own run link).
• Tasks surface kanban-style commands (create/list/update/delete/start/stop/move) with expiring per-task edit locks (task_locks): at most one lock per task, heartbeat-renewed, stealable after expiry.
• Run links from tasks clear to NULL on run deletion so task history survives.

See also: Autonomy-and-Approvals, Database, Architecture.