ADR 0008: Research-agent action protocol (no git actions)

Status: Accepted
Date: 2026-09-13
Deciders: Founder, product team

Context

The reference agent runtime drives a coding agent: its action protocol is bootstrap, start, status, push, run_tests, cancel, artifact, squash, it clones a repository, commits with the human author and publishes through a lint. Trovensa’s agents examine authorised sources, compare findings, draft protocols and reports and run review checks; they never touch a git repository. The runtime skill’s durable state, event log, seq rule, job states, redaction and attribution lint remain exactly what the platform needs.

Decision

Keep the envelope, error codes (busy, run_mismatch, not_bootstrapped, bad_request, internal), job states (idle, running, succeeded, failed, interrupted with owner adoption), the seq rule, StateStore, EventLog, JobManager, redaction of every output and the attribution lint. Replace the git-centric actions: bootstrap binds a run to a program and receives the task, the authorised sources, the records and optionally an SOP; start runs one bounded phase in compare | gaps | hypotheses | draft_protocol | draft_report | review_check; status, cancel and artifact (kinds plan, summary, result, events, task) are unchanged in shape; submit returns the structured result (items[] with assertion_kind and origin: agent, drafts[], review_findings[]) after redaction and the attribution lint, failing with attribution_leak when the lint hits. push, run_tests, squash, the askpass helper and git operations are removed. The model id comes only from AGENT_MODEL_ID. The env prefix is TROVENSA_, the state directory .trovensa/. The fake agent and the container contract tests cover every action.

Consequences

The platform worker writes agent results as new records with origin = agent (ADR 0004); nothing is committed anywhere.
The runtime IAM role needs model invocation, logs and one image; no repository or secret-store access.
The contract tests assert that no source excerpt or secret appears unredacted in state or events.

Alternatives considered

Keep the coding-agent protocol and ignore the git actions: dead code and misleading tests; rejected.
Call the model directly from the API worker: no durable session state, no interrupt/resume, no separate execution role; rejected.

Follow-ups

Extend infra/scripts/release.sh with the --agent function (infra writer) and pin the runtime ARN in the overlay at the first real release.