docs: agent-node retry contracts (worst-case wall time, at-most-once inbox) + bundled suite fail-closed conventions
1 file changed
+19
+19
@@ -346,6 +346,12 @@ research_topic:
|
||||
(agents that write code or deploy things); a child that authors files
|
||||
(e.g. a probe lane writing test artifacts) is mildly side-effectful,
|
||||
meaning a failed first attempt may leave partial artifacts behind.
|
||||
Two contracts to keep in mind: worst-case node wall time is
|
||||
`max_attempts × timeout` (every attempt gets its own fresh budget), and
|
||||
teammate message delivery is **at-most-once across the retry boundary** —
|
||||
messages a failed attempt already drained are not re-delivered to the
|
||||
retry (same inbox Arc, no replay), and messages the failed attempt SENT
|
||||
remain with its peers.
|
||||
- **`fallback`:** Failure route with the same contract as `llm` nodes: on the
|
||||
final failure (retries exhausted, hard error, or structured-output
|
||||
extraction failure) the node writes `Agent node failed: <error>` as
|
||||
@@ -754,6 +760,19 @@ across attempts. See [agent](#agent) for when re-running a child is safe;
|
||||
structured-output extraction failures are never retried on either node
|
||||
type (they route via `fallback` instead).
|
||||
|
||||
### Fail-closed conventions in the bundled review suite
|
||||
|
||||
The bundled review agents (adversary, review-gauntlet, code-reviewer,
|
||||
finding-verifier, deep-research, step-runner) use `max_attempts` + `fallback`
|
||||
so that **every run emits its machine-readable sentinel** even when a stage
|
||||
dies: stage failures degrade to `PIPELINE-FAULT:`-prefixed markers in state,
|
||||
verdict scripts treat any fault as blocking (a degraded run can never read
|
||||
as CONFORMS / PASS / MERGE-READY), and detection is prefix-anchored so a
|
||||
report merely *quoting* the marker is never misclassified. The adversary
|
||||
additionally records caller-declared `verification_commands` once in a
|
||||
deterministic `run_checks` stage — execution criteria ("tests green") are
|
||||
judged against that recorded run, never re-executed by review branches.
|
||||
|
||||
### Turn cap (`max_iterations`)
|
||||
|
||||
`max_iterations` caps the number of model-call turns in one execution of the
|
||||
|
||||
Reference in new issue
Block a user