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
|
(agents that write code or deploy things); a child that authors files
|
||||||
(e.g. a probe lane writing test artifacts) is mildly side-effectful,
|
(e.g. a probe lane writing test artifacts) is mildly side-effectful,
|
||||||
meaning a failed first attempt may leave partial artifacts behind.
|
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
|
- **`fallback`:** Failure route with the same contract as `llm` nodes: on the
|
||||||
final failure (retries exhausted, hard error, or structured-output
|
final failure (retries exhausted, hard error, or structured-output
|
||||||
extraction failure) the node writes `Agent node failed: <error>` as
|
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
|
structured-output extraction failures are never retried on either node
|
||||||
type (they route via `fallback` instead).
|
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`)
|
### Turn cap (`max_iterations`)
|
||||||
|
|
||||||
`max_iterations` caps the number of model-call turns in one execution of the
|
`max_iterations` caps the number of model-call turns in one execution of the
|
||||||
|
|||||||
Reference in new issue
Block a user