@zibby/agent-workflow 2.0.5 → 2.0.7

package/README.md

@@ -167,6 +167,7 @@ If you want to compose Claude Code + Codex + Gemini into one pipeline with struc
 | `Graph` | The DAG. `addNode`, `addEdge`, `addConditionalEdges`, `setEntryPoint`. |
 | Fan-out | Call `addEdge` more than once from the same node and **every** branch runs, each carrying on through its own children. Branches run sequentially in declaration order (depth-first: a branch finishes before the next starts). Where branches converge, the shared node waits for all of them and runs **once** — see [Fan-out](#fan-out) below. |
 | `Node` | One agent invocation. Config: `prompt`, `outputSchema` (Zod), optional `agent`, `retries`, `skills`. |
+| Retries | `retries: N` = N retries on ANY failure (N+1 attempts), no delay — declared per node. **On top of that**, a failure the engine can POSITIVELY identify as a transient provider failure (a dead stream, a 429, an upstream 5xx) buys up to `AGENT_TRANSIENT_RETRIES` extra attempts (default 2) with exponential backoff (`AGENT_TRANSIENT_BACKOFF_MS`, default 5000, 0 = no wait). One loop, one decider — `classifyFailure` in `failure-class.ts`. A failure it cannot positively identify is DETERMINISTIC and is never retried, because retrying a bug is an infinite loop that burns money. |
 | Sub-graph node | `addNode(name, { workflow: 'other-name', ... })` — dispatches another deployed workflow as a child. Sync (poll + merge) or async (`async: true`, fire-and-forget). See [Sub-graphs](#sub-graphs) below. |
 | `AgentStrategy` | Abstract base. Implement `canHandle(ctx)` and `invoke(prompt, opts)`. |
 | `registerStrategy()` | Tells the engine what agents are available. Selected by node `agent` field → `config.agents[name]` → `state.agentType`. |

package/dist/failure-class.d.ts

@@ -0,0 +1,193 @@
+/**
+ * FAILURE CLASSIFICATION — the ONE authority on "is this failure the provider
+ * having a bad second, or is it a real bug?"
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY THIS FILE EXISTS (execution 42b920ae, 2026-08-25, the founder's own box)
+ *
+ * A `frontend-specialist` member had ALREADY built its feature, driven a real
+ * browser at it, and taken the screenshot ("Recently viewed … — newest-first
+ * ✓"). It was writing its handoff file when the provider's stream died:
+ *
+ *     API Error: Stream idle timeout - partial response received
+ *
+ * Sixteen minutes of finished work were thrown away, no PR was pushed, and the
+ * ticket spent one of its two attempts. It later hit the cap and parked — so a
+ * network blip masqueraded as "the fleet cannot do this ticket".
+ *
+ * The stream dying is the provider's SDK and cannot be prevented. What happens
+ * NEXT is entirely ours, and it needs exactly one thing this codebase did not
+ * have: a way to tell a bad second apart from a bug. That is this file.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * TWO RULES THIS FILE KEEPS, BOTH LEARNED THE EXPENSIVE WAY
+ *
+ * 1. **"Retry on anything I can't explain" is an infinite money pump.** A
+ *    deterministic failure — a bad prompt, a schema violation, a missing
+ *    credential, a node returning `{success:false}` — fails identically on
+ *    every attempt, so a catch-all classifier turns one wasted turn into N.
+ *    Therefore the default is DETERMINISTIC: a failure is retried only when
+ *    something POSITIVELY identifies it as transient. Nothing about "I do not
+ *    recognise this" is evidence of transience.
+ *
+ * 2. **The provider's own classification is a KIND, not a MESSAGE — and its
+ *    catch-all is not a verdict.** The Claude Agent SDK stamps an error kind on
+ *    the message (`authentication_failed` … `server_error` | `unknown`), and
+ *    `unknown` is what a dead stream arrives as. Reading `unknown` as "transient"
+ *    would smuggle rule 1's catch-all back in through the provider's front door;
+ *    reading it as "deterministic" would leave the original bug unfixed. So an
+ *    inconclusive kind DECIDES NOTHING and hands over to the text patterns —
+ *    which name real network shapes and nothing else. A kind that IS conclusive
+ *    is final: an `authentication_failed` whose text happens to say "timed out"
+ *    must never be retried.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ONE DECIDER, THREE CALLERS. `classifyFailure` is consulted by:
+ *   • `node.ts` — the ONE retry loop (there is no second one; see the long note
+ *     in node.ts about the graph-level gate that was deleted for being one);
+ *   • the strategies — via `formatProviderError`, so the message a failure
+ *     carries and the classifier that reads it back are the SAME module and can
+ *     never drift (🔗 TWO-PLACES);
+ *   • the fleet's reconcile step — which reads a FINISHED run's `error` STRING
+ *     off the execution record and must reach the same verdict the engine
+ *     reached in-process. Hence: `classifyFailure` accepts an Error OR a string.
+ */
+/** The failure classes. `inconclusive` is a verdict about the EVIDENCE, never about the failure. */
+export type FailureClass = 'transient' | 'deterministic';
+/**
+ * The Claude Agent SDK's own error-kind enum, each mapped to what it PROVES.
+ *
+ * Source of truth for the key set: the SDK's `assistant.error` / `api_retry.error`
+ * schema (one shared enum). Verified against the shipped CLI, 2026-08-25:
+ *   ["authentication_failed","oauth_org_not_allowed","billing_error",
+ *    "rate_limit","invalid_request","server_error","unknown","max_output_tokens"]
+ *
+ * A kind we have never seen is deliberately absent, and an absent kind is
+ * INCONCLUSIVE (never "transient") — a new provider kind must be classified by
+ * a human reading its meaning, not adopted into the retry budget by default.
+ */
+export declare const PROVIDER_ERROR_KIND_CLASS: Readonly<Record<string, FailureClass | 'inconclusive'>>;
+/**
+ * TRANSIENT TEXT SHAPES — an allowlist, not a heuristic.
+ *
+ * Every entry is a wire/stream failure that a second attempt can genuinely
+ * succeed at, and every entry was taken from a real error string (the CLI's own
+ * strings, undici/node network errors, HTTP status lines). Deliberately NOT
+ * here, because they repeat identically: prompt/context-length errors, credit
+ * balance, invalid API key, "No session token", zod validation output, a node
+ * returning `{success:false}`, and the engine's own `API stuck in loop` (a turn
+ * that looped once will loop again, and it is the most expensive thing to redo).
+ */
+export declare const TRANSIENT_MESSAGE_PATTERNS: readonly RegExp[];
+/**
+ * The message a strategy throws when the PROVIDER reported a failure.
+ *
+ * This exists because the alternative shipped, and it read — in the founder's
+ * execution record, as the entire explanation of a 16-minute loss —
+ *
+ *     Node 'develop' failed after 1 attempt(s): unknown
+ *
+ * `unknown` was the SDK's error KIND. The strategy took it for the error
+ * MESSAGE and discarded the assistant text sitting in the same object, which
+ * said `API Error: Stream idle timeout - partial response received`. So this
+ * function keeps ALL THREE facts, and keeps the kind in a bracket so a later
+ * reader (the fleet's reconcile, which only ever sees the persisted string) can
+ * recover it without re-guessing. Formatter and parser in ONE module, on
+ * purpose.
+ */
+export declare function formatProviderError({ kind, status, text }: {
+    kind?: string | null;
+    status?: number | string | null;
+    text?: string | null;
+}): string;
+/** The provider's error kind, from a structured field or from a formatted message. */
+export declare function providerErrorKindOf(x: unknown): string | null;
+/** The provider's HTTP status, from a structured field or from a formatted message. */
+export declare function providerErrorStatusOf(x: unknown): number | null;
+/**
+ * Is this failure worth one more attempt?
+ *
+ * Accepts an Error (in-process, from a strategy) OR a string (out-of-process:
+ * a finished run's `error` field off the execution record). Same verdict either
+ * way — that is the whole point of accepting both.
+ *
+ * ORDER IS THE DESIGN:
+ *   1. cancellation  → deterministic, always, first. Never bill a stop twice.
+ *   2. conclusive provider kind → final. A conclusive kind OUTRANKS the text,
+ *      so an auth failure that mentions a timeout is not retried.
+ *   3. provider HTTP status (429 / 5xx) → transient. Structured, unambiguous.
+ *   4. the text allowlist → transient only on a named network shape.
+ *   5. otherwise → deterministic. "I don't recognise this" is not evidence.
+ */
+export declare function classifyFailure(x: unknown): FailureClass;
+/** Convenience predicate over {@link classifyFailure}. */
+export declare function isTransientFailure(x: unknown): boolean;
+/** Default extra attempts a TRANSIENT failure may buy, on top of a node's declared `retries`. */
+export declare const DEFAULT_TRANSIENT_RETRIES = 2;
+/** Hard ceiling on the knob — a typo in an env var must not multiply the bill without limit. */
+export declare const MAX_TRANSIENT_RETRIES = 5;
+/**
+ * How many extra attempts a transient failure may buy.
+ *
+ * Bounded on purpose: a genuinely broken provider costs at most
+ * (1 + budget) turns per node instead of an unbounded stream of them. Brand
+ * neutral (CLAUDE.md § NEW identifiers) and `0` is a legal, honest "off".
+ */
+export declare function transientRetryBudget(env?: Record<string, any>): number;
+/** First-retry delay, doubling per retry. Overridable; `0` means "no wait". */
+export declare const DEFAULT_TRANSIENT_BACKOFF_MS = 5000;
+/** Ceiling on one wait, so a doubling series can never park a run for minutes. */
+export declare const MAX_TRANSIENT_BACKOFF_MS = 30000;
+/**
+ * Base delay for the backoff series. Brand-neutral knob; `0` disables the wait
+ * entirely (what a test wants, and what an operator on a private endpoint with
+ * no rate limit might legitimately want too).
+ */
+export declare function transientBackoffBaseMs(env?: Record<string, any>): number;
+/**
+ * Backoff before transient attempt `n` (1-based): 5s, 10s, 20s, capped at 30s,
+ * ±20% jitter so a fleet of members that all failed on the same upstream blip
+ * does not come back in lockstep.
+ */
+export declare function transientBackoffMs(n: number, rand?: () => number, baseMs?: number): number;
+/** What the budget says to do after one failed attempt. */
+export interface AttemptDecision {
+    /** Run the node again? */
+    retry: boolean;
+    /** Which budget paid for it — `declared` = the node's own `retries`, `transient` = this file's. */
+    paidBy?: 'declared' | 'transient';
+    /** Sleep this long first (only ever non-zero for a TRANSIENT failure). */
+    delayMs: number;
+    /** The classification that produced this decision. */
+    failureClass: FailureClass;
+    /** 1-based index within `paidBy`'s budget, for the log line. */
+    index?: number;
+    /** Size of `paidBy`'s budget, for the log line. */
+    of?: number;
+}
+/**
+ * THE attempt budget — ONE implementation, shared by both of `node.ts`'s retry
+ * paths (custom-execute and LLM) so they can never drift into two policies.
+ *
+ * TWO budgets, spent in this order, and the order is the back-compat guarantee:
+ *
+ *   1. `retries` — the node's OWN declaration, honoured for ANY failure exactly
+ *      as it always was. A node declaring `retries: 2` still gets 2 retries on a
+ *      schema violation, with no delay. Nothing here changes that.
+ *   2. `transient` — extra attempts, available ONLY when `classifyFailure` says
+ *      transient. This is the new capacity, and it is why a dead stream no
+ *      longer destroys a member's finished work.
+ *
+ * A TRANSIENT failure gets the backoff sleep whichever budget pays for it —
+ * hammering an overloaded upstream three times in 200ms is not a retry policy.
+ */
+export declare function createAttemptBudget(retries: number, { env, rand }?: {
+    env?: Record<string, any>;
+    rand?: () => number;
+}): {
+    readonly attemptsMade: number;
+    readonly transientUsed: number;
+    readonly transientMax: number;
+    /** Record one failure and say whether to run again. */
+    next(failure: unknown): AttemptDecision;
+};

package/dist/failure-class.js

@@ -0,0 +1 @@
+var N=Object.freeze({authentication_failed:"deterministic",oauth_org_not_allowed:"deterministic",billing_error:"deterministic",invalid_request:"deterministic",max_output_tokens:"deterministic",rate_limit:"transient",server_error:"transient",unknown:"inconclusive"}),y=Object.freeze([/stream idle timeout/i,/partial response received/i,/no chunks received/i,/stream ended without receiving any events/i,/stream completed without receiving/i,/socket hang up/i,/premature close/i,/\b(?:ECONNRESET|ECONNABORTED|ECONNREFUSED|EPIPE|ETIMEDOUT|EAI_AGAIN|ENETUNREACH|ENETRESET|EHOSTUNREACH)\b/,/\bfetch failed\b/i,/\bnetwork (?:error|timeout)\b/i,/request timed out/i,/\brequest timeout\b/i,/\boverloaded(?:_error)?\b/i,/\brate[_ ]limit(?:_error|ed)?\b/i,/\b(?:HTTP|http_status|status(?:\s*code)?)[:= ]\s*(?:429|5\d\d)\b/i,/\b(?:429|500|502|503|504|529)\s+(?:too many requests|internal server error|bad gateway|service unavailable|gateway time-?out|overloaded)\b/i]),_=Object.freeze([/\bAbortError\b/,/\bAPIUserAbortError\b/,/\boperation was aborted\b/i,/\bcanceled by parent abort\b/i,/\bstopped by operator\b/i]),m=/provider error \[([a-z_]+)(?:\s+http\s+(\d{3}))?\]/i;function v({kind:t,status:e,text:r}){let n=typeof t=="string"&&t.trim()?t.trim():"unclassified",i=Number(e),s=Number.isInteger(i)&&i>=100&&i<=599?` http ${i}`:"",o=(typeof r=="string"?r.trim():"")||"the provider reported a failure but gave no message";return`provider error [${n}${s}]: ${o}`}function d(t){if(t==null)return"";if(typeof t=="string")return t;if(typeof t!="object")return String(t);let e=t;return[e.message,e.name,e.code,e.providerErrorText,e.cause?.message??(typeof e.cause=="string"?e.cause:void 0),e.cause?.code].filter(n=>typeof n=="string"||typeof n=="number").join(" | ")}function g(t){if(t&&typeof t=="object"){let r=t.providerErrorKind;if(typeof r=="string"&&r.trim())return r.trim()}let e=m.exec(d(t));return e?e[1].toLowerCase():null}function T(t){if(t&&typeof t=="object"){let n=Number(t.providerErrorStatus);if(Number.isInteger(n)&&n>=100&&n<=599)return n}let e=m.exec(d(t)),r=e&&e[2]?Number(e[2]):NaN;return Number.isInteger(r)?r:null}function b(t){let e=d(t);if(!e)return"deterministic";for(let i of _)if(i.test(e))return"deterministic";let r=g(t);if(r){let i=N[r];if(i==="transient"||i==="deterministic")return i}let n=T(t);if(n===429||n>=500&&n<=599)return"transient";for(let i of y)if(i.test(e))return"transient";return"deterministic"}function S(t){return b(t)==="transient"}var l=2,R=5;function A(t=process.env){let e=t?.AGENT_TRANSIENT_RETRIES;if(e==null||String(e).trim()==="")return l;let r=Number(e);return!Number.isFinite(r)||r<0?l:Math.min(R,Math.floor(r))}var c=5e3,p=3e4;function M(t=process.env){let e=t?.AGENT_TRANSIENT_BACKOFF_MS;if(e==null||String(e).trim()==="")return c;let r=Number(e);return!Number.isFinite(r)||r<0?c:Math.min(p,Math.floor(r))}function f(t,e=Math.random,r=c){if(!(r>0))return 0;let n=Math.max(1,Math.floor(Number(t)||1)),i=Math.min(p,r*2**(n-1)),s=1+(e()-.5)*.4;return Math.max(1,Math.round(i*s))}function h(t,{env:e=process.env,rand:r=Math.random}={}){let n=Math.max(0,Math.floor(Number(t)||0)),i=A(e),s=M(e),a=0,o=0;return{get attemptsMade(){return 1+a+o},get transientUsed(){return o},get transientMax(){return i},next(E){let u=b(E);return a<n?(a+=1,{retry:!0,paidBy:"declared",delayMs:u==="transient"?f(a,r,s):0,failureClass:u,index:a,of:n}):u==="transient"&&o<i?(o+=1,{retry:!0,paidBy:"transient",delayMs:f(o,r,s),failureClass:u,index:o,of:i}):{retry:!1,delayMs:0,failureClass:u}}}}export{c as DEFAULT_TRANSIENT_BACKOFF_MS,l as DEFAULT_TRANSIENT_RETRIES,p as MAX_TRANSIENT_BACKOFF_MS,R as MAX_TRANSIENT_RETRIES,N as PROVIDER_ERROR_KIND_CLASS,y as TRANSIENT_MESSAGE_PATTERNS,b as classifyFailure,h as createAttemptBudget,v as formatProviderError,S as isTransientFailure,g as providerErrorKindOf,T as providerErrorStatusOf,M as transientBackoffBaseMs,f as transientBackoffMs,A as transientRetryBudget};