About agent actions and records

Agents in Trovensa prepare, compare, propose and flag. A person reviews and decides. An agent action is therefore never a mutation of an existing record: it is an agent run that ends in new records marked origin = agent, plus an event log a reader can follow, plus a decision that stays with the person.

The problem

Research agents that examine authorised sources, compare findings, draft protocols and reports and run review checks need durable state, an event log, cancellation, redaction of every output and an attribution lint. They must not commit anything, approve anything or rewrite an approved record, and the model they use must never be a literal in code or documentation.

How it works

Kinds: evidence_compare, evidence_gaps, evidence_hypotheses (started from a question with evidence.agents.use), plans_draft_protocol, plans_draft_report (from a plan with plans.agents.use), review_check (from an SOP version and a target with review.agents.use). Phase 2 adds console_turn (one per message in a console thread), progress_propose, review_extract_requirements, review_sop_impact and review_check_batch; the six phase-1 kinds stay callable as canned prompts from the console.
Run record (AgentRunOut): kind, status in queued, running, awaiting_input, succeeded, failed, cancelled, input, result_summary, requested_by, started_at, finished_at, error, last_event_seq, plus thread_id, mode (interactive, background), lane, agent_version_id, plan_hash, usage and trace_id.
Events (AgentEventOut): run_id, seq, ts, kind, level (debug, info, warning, error), message, payload; read under Setup › Agent runs with program.agent_runs.read.
The submit result: {items[], drafts[], review_findings[], lint}. Items are findings, hypotheses or gaps with an assertion_kind and origin: agent; drafts are protocols or reports created in status draft; review findings are filed with decision open. Everything passes redaction and the attribution lint first; a lint hit yields the public error attribution_leak and a null result that is discarded.
Public error codes: runtime_unavailable, session_lost, budget_exhausted, timed_out, cancelled_by_user, attribution_leak, internal_error, and from phase 2 gate_expired, policy_denied, plan_violation, config_mismatch, runtime_updating, rate_limited. A gate that waits for a person is the container state interrupted_input_required, stored as the run status awaiting_input.
Worker rules: claims agent_runs, sync_runs and tool_invocations with FOR UPDATE SKIP LOCKED in two lanes (interactive turns never queue behind background jobs); refreshes locked_at every 60 s and re-queues running rows whose heartbeat is older than 5 minutes; honours SIGTERM with a 120 s grace. Locally the runtime is a fake (AGENT_RUNTIME_URL empty) that returns canned, illustrative results. The model id comes only from AGENT_MODEL_ID and is verified at run start against the recorded model configuration.

What a person decides

Agent output	Arrives as	The person’s decision	Permission
Finding	`origin = agent`, kind printed	edit or keep; cite in a hypothesis	`evidence.findings.manage`
Hypothesis	status `proposed`	`accepted` or `rejected`, with rationale	`evidence.hypotheses.approve`
Gap	status `open`	`addressed` or `dismissed`	`evidence.gaps.manage`
Protocol or report draft	status `draft`	transition to `review`, then `/approve`	`plans.protocols.`, `plans.reports.`
Review finding	decision `open`	`accepted`, `dismissed` or `resolved`, with note	`review.findings.approve`
Console proposal (any write)	`tool_calls` row `proposed` with `proposal_hash`	approve, edit then approve, or decline with a reason	the write’s own permission, recorded as `permission_exercised`
Any run	`queued` or `running`	cancel	`program.agent_runs.manage`

Why this design

New records instead of edits: the trail from a decision back to the run that proposed it stays intact, and an approved record is never changed by software.
A separate runtime with durable sessions instead of calling a model from the API worker: interrupt and resume, a separate execution role, and redaction on both sides of the wire (ADR 0008).
No git actions: the reference runtime’s push, run_tests and squash were removed; the research agent has nothing to commit.
In the console the same rule becomes plan-first: every run starts with a plan artifact, every write is a proposal a person approves with the write’s own permission, and agents hold no approve, sign or notify tools (About the console).

Consequences and limits

Agent runs are only as useful as the sources the program authorised; a run over an empty question returns an empty result.
The fake runtime proves the protocol, not the science; every result it returns is labelled illustrative.
A failed run leaves its events and error code; nothing is written to the product tables.