@sema-ai/core 1.275.1

package/dist/brain/degrading.js

@@ -0,0 +1,249 @@
+/**
+ * Error/budget-aware **degradation cascade** (1.39, design/21, design/17 §5C).
+ *
+ * Unlike failover (a *peer* backup whose goal is "same quality, a gateway that's actually up"),
+ * degradation **deliberately downgrades** to a cheaper / different-provider model to KEEP SERVING when
+ * the primary is rate-limited or its circuit breaker is open — accepting some quality loss instead of
+ * failing the task. Opt-in; the served turn is tagged so the Runner can surface `TaskResult.degraded`.
+ *
+ * v1 (this file) handles the two **reactive** triggers visible at the brain layer — `rate_limit` and
+ * `breaker_open`. The proactive **near-budget** trigger needs the task budget (only the Runner sees it)
+ * and is deferred to v2 (council O1); `"budget"` is reserved in `DegradeReason` for it.
+ *
+ * Detection is **structural**, not literal string-matching: the breaker-open signal is
+ * `CIRCUIT_OPEN_MARKER` (exported from circuit-breaker.ts) and the code comes from the shared
+ * `extractErrorCode`. Degradation must be the **outermost** brain in a stack (so it sees the inner
+ * failover/breaker/timeout outcomes and can downgrade on them):
+ *   `createDegradingBrain({ primary: failover(breaker(timeout(brain))), fallback, fallbackModel })`.
+ */
+import { createAssistantMessageEventStream, } from "../internal/llm.js";
+import { ZERO_USAGE, extractErrorCode } from "./errors.js";
+import { CIRCUIT_OPEN_MARKER } from "./circuit-breaker.js";
+/** Diagnostic `type` the decorator stamps on a degraded turn's message; the Runner reads it back. */
+export const DEGRADED_DIAGNOSTIC_TYPE = "degraded";
+const VALID_REASONS = new Set([
+    "breaker_open",
+    "rate_limit",
+    "budget",
+    "server_error",
+    "last_resort",
+]);
+/** CC `Kjd` parity (198 :146840): a fallback chain is capped at 3 entries. */
+const MAX_CHAIN = 3;
+/** Pull a degradation marker off a served message (used by the Runner to fill `TaskResult.degraded`). */
+export function readDegradation(msg) {
+    const d = msg?.diagnostics?.find((x) => x.type === DEGRADED_DIAGNOSTIC_TYPE);
+    const det = d?.details;
+    // Strict on every field — `readDegradation` parses an externally-shaped diagnostic, so a corrupt
+    // `details` must not leak a non-string into the public `DegradeReason` union (council bug #2).
+    if (det &&
+        typeof det.from === "string" &&
+        typeof det.to === "string" &&
+        typeof det.reason === "string" &&
+        VALID_REASONS.has(det.reason)) {
+        // `chain` (design/126) is optional and equally strictly parsed: anything but an all-string array
+        // is dropped (the marker may come from a pre-chain version or a corrupt writer).
+        const chain = Array.isArray(det.chain) && det.chain.every((c) => typeof c === "string") ? det.chain : undefined;
+        return { from: det.from, to: det.to, reason: det.reason, ...(chain && { chain }) };
+    }
+    return undefined;
+}
+/** Classify a primary failure into a downgrade reason (structural, not literal — council #1).
+ *  design/126: `server` (5xx/529/408/409, post-retry-budget) → `server_error`; `http` (404 and other
+ *  odd statuses) → `last_resort`. `auth`/`invalid_request`/`network` deliberately map to NOTHING
+ *  (fail loud / not this layer's job — design/126 D2). */
+function degradeReasonOf(msg) {
+    if (msg.stopReason !== "error")
+        return undefined;
+    const code = extractErrorCode(msg.errorMessage);
+    // Breaker detection is gated on the code FIRST (codex 126 审 M1): the breaker emits `[network] <marker>…`,
+    // so only a network-coded error may be a breaker trip. A marker STRING appearing inside some other
+    // error's body (e.g. an upstream echoing our own marker text back in a 401 payload) must not convert a
+    // fail-loud auth/invalid_request into a degrade.
+    if (code === "network" && (msg.errorMessage ?? "").includes(CIRCUIT_OPEN_MARKER))
+        return "breaker_open";
+    if (code === "rate_limit")
+        return "rate_limit";
+    if (code === "server")
+        return "server_error";
+    if (code === "http")
+        return "last_resort";
+    return undefined;
+}
+function tagDegraded(msg, info) {
+    const diag = {
+        type: DEGRADED_DIAGNOSTIC_TYPE,
+        timestamp: Date.now(),
+        details: { from: info.from, to: info.to, reason: info.reason, ...(info.chain && { chain: info.chain }) },
+    };
+    // REPLACE any existing degraded marker rather than append (codex 126 审 M4): when a hop's brain is
+    // itself a degrading stack, `readDegradation`'s first-match would surface the INNER hop-local marker
+    // and lose the outer primary→chain record — the outermost decorator owns the authoritative marker.
+    msg.diagnostics = [...(msg.diagnostics ?? []).filter((d) => d.type !== DEGRADED_DIAGNOSTIC_TYPE), diag];
+}
+function errorMessageOf(model, e, aborted) {
+    return {
+        role: "assistant",
+        content: [{ type: "text", text: "" }],
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        stopReason: aborted ? "aborted" : "error",
+        errorMessage: e instanceof Error ? e.message : String(e),
+        usage: ZERO_USAGE,
+        timestamp: Date.now(),
+    };
+}
+function terminalOf(message) {
+    return message.stopReason === "error"
+        ? { type: "error", reason: "error", error: message }
+        : { type: "done", reason: message.stopReason, message };
+}
+/**
+ * Consume one brain stream, **holding the leading `start`** until the first real content event (like
+ * failover) so an error-before-content can be swallowed and replaced without a duplicated `start`.
+ * Forwards live content to `sink`. Shared by the primary and fallback passes (council: avoid drift).
+ */
+async function forward(stream, sink) {
+    let sawContent = false;
+    let heldStart;
+    let terminal;
+    for await (const ev of stream) {
+        if (ev.type === "done" || ev.type === "error") {
+            terminal = ev;
+            break;
+        }
+        if (ev.type === "start" && !sawContent) {
+            heldStart = ev;
+            continue;
+        }
+        if (!sawContent) {
+            sawContent = true;
+            if (heldStart)
+                sink.push(heldStart);
+        }
+        sink.push(ev);
+    }
+    const message = await stream.result();
+    return { message, sawContent, heldStart, terminal };
+}
+/**
+ * design/131 (codex 131 审 A) — resilience-standdown pass-through: forward one brain's stream
+ * verbatim, but keep the decorator discipline that a REJECTING inner brain (throw instead of an
+ * error event) still leaves a terminal on the returned stream — otherwise `result()` never
+ * resolves and the harness hangs (the same class as the degradation-brain blocker).
+ */
+export function passthroughStream(brain, model, context, options) {
+    const out = createAssistantMessageEventStream();
+    void (async () => {
+        try {
+            const inner = await brain.stream(model, context, options);
+            for await (const ev of inner)
+                out.push(ev);
+        }
+        catch (e) {
+            const aborted = options?.signal?.aborted === true ||
+                (e instanceof Error && (e.name === "AbortError" || e.name === "TimeoutError"));
+            out.push({ type: "error", reason: "error", error: errorMessageOf(model, e, aborted) });
+        }
+    })();
+    return out;
+}
+export function createDegradingBrain(opts) {
+    // Form-dependent trigger default (codex 126 审 M3): new chain form → full four-class CC gate; legacy
+    // pair → the pre-126 two-trigger gate (no silent behavior change for existing deployments).
+    const triggers = new Set(opts.downgradeOn ?? (opts.fallbacks ? ["rate_limit", "breaker_open", "server_error", "last_resort"] : ["rate_limit", "breaker_open"]));
+    // Normalize the chain ONCE at construction: `fallbacks` wins; the legacy pair is the chain-of-one
+    // sugar. Dedupe by model.id + cap at 3 (CC Kjd parity). Same-as-failed-model skipping is per-call
+    // (the requested model is only known then).
+    const rawHops = opts.fallbacks ?? (opts.fallback && opts.fallbackModel ? [{ brain: opts.fallback, model: opts.fallbackModel }] : []);
+    const seenIds = new Set();
+    const hops = rawHops.filter((h) => (seenIds.has(h.model.id) ? false : (seenIds.add(h.model.id), true))).slice(0, MAX_CHAIN);
+    if (hops.length === 0) {
+        throw new Error("createDegradingBrain: provide `fallbacks` (design/126 chain) or the legacy `fallback`+`fallbackModel` pair");
+    }
+    const stream = (model, context, options) => {
+        // design/131 (service [404]): per-task "fail rather than degrade" intent — pass the primary
+        // through untouched (its failure surfaces as-is; no fallback chain, no marker). Absent ⇒ today.
+        // codex 131 审 A: the pass-through still wraps a REJECTING primary into an error terminal (the
+        // "never leave `out` terminal-less" discipline every path in this file holds) — only the
+        // degrade/failover semantics stand aside, not the stream-protocol normalization.
+        if (options?.resilience?.allowDegrade === false) {
+            return passthroughStream(opts.primary, model, context, options);
+        }
+        const out = createAssistantMessageEventStream();
+        void (async () => {
+            // Track whether we entered the degrade path so a LATE throw still surfaces the marker (council #3),
+            // and so the whole body can be wrapped in try/catch — a brain that rejects (rather than emitting an
+            // error event) must NOT leave `out` terminal-less, or `result()` never resolves and the harness
+            // hangs forever (council blocker; matches createCircuitBreakerBrain's discipline).
+            let degradeInfo;
+            let lastAttempted = model; // the model actually being served when a throw escapes (codex 126 审 MIN2)
+            try {
+                // Clear the primary's per-call auth + identity for every hop so each fallback uses its OWN
+                // config creds and doesn't leak the primary's metadata to another provider (council #5).
+                // Caller hooks (onPayload/onResponse) are kept so the caller still sees the calls.
+                const fbOptions = options
+                    ? { ...options, apiKey: undefined, headers: undefined, metadata: undefined }
+                    : undefined;
+                // design/126 chain walk: primary first, then each eligible hop. A hop is taken only on a
+                // ZERO-CONTENT failure whose reason is in the trigger set (same predicate as the classic single
+                // hop); entries whose model id equals the model that just failed are skipped (CC :473458 skip
+                // discipline — without CC's collapse re-dispatch, see design/126 D3).
+                let current = await forward(await opts.primary.stream(model, context, options), out);
+                let failedModelId = model.id;
+                const chainPath = [];
+                for (const hop of hops) {
+                    const reason = degradeReasonOf(current.message);
+                    const eligible = !current.sawContent && options?.signal?.aborted !== true && reason !== undefined && triggers.has(reason);
+                    if (!eligible)
+                        break;
+                    if (hop.model.id === failedModelId)
+                        continue; // same model as the one that just failed — skip
+                    chainPath.push(hop.model.id);
+                    degradeInfo = {
+                        from: model.id,
+                        to: hop.model.id,
+                        reason: degradeInfo?.reason ?? reason, // FIRST trigger is the recorded reason
+                        chain: [...chainPath],
+                    };
+                    failedModelId = hop.model.id;
+                    lastAttempted = hop.model;
+                    current = await forward(await hop.brain.stream(hop.model, context, fbOptions), out);
+                }
+                if (!degradeInfo) {
+                    // Never degraded (healthy primary, non-trigger failure, or content already streamed) →
+                    // propagate the primary unchanged.
+                    if (!current.sawContent && current.heldStart)
+                        out.push(current.heldStart);
+                    out.push(current.terminal ?? terminalOf(current.message));
+                    return;
+                }
+                // Tag the ACTUAL message the terminal carries (so the Runner sees it in message_end). Set it
+                // whether the last hop succeeded OR also failed (council #3) — callers always learn it degraded.
+                const fbFinal = current.terminal?.type === "done"
+                    ? current.terminal.message
+                    : current.terminal?.type === "error"
+                        ? current.terminal.error
+                        : current.message;
+                tagDegraded(fbFinal, degradeInfo);
+                if (!current.sawContent && current.heldStart)
+                    out.push(current.heldStart);
+                out.push(current.terminal ?? terminalOf(current.message));
+            }
+            catch (e) {
+                // A brain rejected or the loop threw — emit a terminal so result() resolves (no hang). Preserve
+                // the degradation marker if we'd already committed to degrading.
+                const aborted = options?.signal?.aborted === true ||
+                    (e instanceof Error && (e.name === "AbortError" || e.name === "TimeoutError"));
+                const errMsg = errorMessageOf(lastAttempted, e, aborted);
+                if (degradeInfo)
+                    tagDegraded(errMsg, degradeInfo);
+                out.push({ type: "error", reason: aborted ? "aborted" : "error", error: errMsg });
+            }
+        })();
+        return out;
+    };
+    return { stream };
+}
+//# sourceMappingURL=degrading.js.map

package/dist/brain/degrading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"degrading.js","sourceRoot":"","sources":["../../src/brain/degrading.ts"],"names":[],"mappings":"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"}

package/dist/brain/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Structured brain error so the *kind* of failure is machine-distinguishable end-to-end (the message
+ * is prefixed `[code]`, which the Runner lifts into `TaskResult.errorCode`). This lets an external
+ * caller react correctly without string-matching: `auth` → the API key is wrong, **stop and fix it**
+ * (it's not retried, so the caller gets a fast failure); `rate_limit` → back off; `network`/`server`
+ * → a transient outage worth retrying. Only `network`/`server`/`rate_limit` are retried by the brains.
+ */
+import type { Usage } from "../internal/llm.js";
+/** A zeroed `Usage` for synthetic error/short-circuit assistant messages (no tokens spent). Shared by
+ *  the circuit-breaker, degradation, and routing brains so the empty-usage shape lives in one place. */
+export declare const ZERO_USAGE: Usage;
+/** The single source of truth for brain error codes — the type, the `[code]` parser, and the prefix
+ *  stripper all derive from this one list, so adding a code can't silently diverge across call sites. */
+declare const BRAIN_ERROR_CODES: readonly ["auth", "rate_limit", "invalid_request", "server", "network", "http"];
+export type BrainErrorCode = (typeof BRAIN_ERROR_CODES)[number];
+export declare class BrainError extends Error {
+    readonly code: BrainErrorCode;
+    readonly status?: number;
+    constructor(code: BrainErrorCode, detail: string, status?: number);
+}
+/** Map an HTTP status to an error class. 401/403 = auth (don't retry); 429 = rate limit; 5xx = server. */
+export declare function classifyHttp(status: number): BrainErrorCode;
+/** Lift the machine-readable code back out of a `[code] …` prefixed `errorMessage` (the single shared
+ *  parser — circuit breaker, degradation, and the Runner all read the prefix this way, council #7). */
+export declare function extractErrorCode(errorMessage: string | undefined): BrainErrorCode | undefined;
+/** Strip a leading `[code] ` prefix (including the trailing space) from an `errorMessage`, leaving the
+ *  human text. Pairs with {@link extractErrorCode} so a caller can lift the code and clean the message
+ *  without re-hardcoding the code list (the Runner does both when assembling `TaskResult`). */
+export declare function stripErrorCodePrefix(errorMessage: string): string;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/brain/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/brain/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD;wGACwG;AACxG,eAAO,MAAM,UAAU,EAAE,KAOxB,CAAC;AAEF;yGACyG;AACzG,QAAA,MAAM,iBAAiB,iFAAkF,CAAC;AAC1G,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBACb,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAMlE;AAED,0GAA0G;AAC1G,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAY3D;AAKD;uGACuG;AACvG,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAG7F;AAED;;+FAE+F;AAC/F,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEjE"}

package/dist/brain/errors.js

@@ -0,0 +1,58 @@
+/** A zeroed `Usage` for synthetic error/short-circuit assistant messages (no tokens spent). Shared by
+ *  the circuit-breaker, degradation, and routing brains so the empty-usage shape lives in one place. */
+export const ZERO_USAGE = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+/** The single source of truth for brain error codes — the type, the `[code]` parser, and the prefix
+ *  stripper all derive from this one list, so adding a code can't silently diverge across call sites. */
+const BRAIN_ERROR_CODES = ["auth", "rate_limit", "invalid_request", "server", "network", "http"];
+export class BrainError extends Error {
+    code;
+    status;
+    constructor(code, detail, status) {
+        super(`[${code}] ${detail}`);
+        this.name = "BrainError";
+        this.code = code;
+        this.status = status;
+    }
+}
+/** Map an HTTP status to an error class. 401/403 = auth (don't retry); 429 = rate limit; 5xx = server. */
+export function classifyHttp(status) {
+    if (status === 401 || status === 403)
+        return "auth";
+    if (status === 429)
+        return "rate_limit";
+    if (status === 400 || status === 422)
+        return "invalid_request";
+    // CC-parity round-3: 408 (request timeout) and 409 (lock/conflict timeout) are TRANSIENT gateway blips, not
+    // terminal — CC's withRetry retries both (claude.ts withRetry: `status===408 || status===409 → retry`). As
+    // plain "http" they were excluded from the circuit-breaker count + degrade triggers + the connect-retry loop,
+    // so a single 408/409 from an LLM gateway killed a whole unattended task. Bucket them with "server" (counted,
+    // degrade-eligible, retried — see the stream-engine connect-retry predicate).
+    if (status === 408 || status === 409)
+        return "server";
+    if (status >= 500)
+        return "server";
+    return "http";
+}
+const CODE_ALTERNATION = BRAIN_ERROR_CODES.join("|");
+const CODE_RE = new RegExp(`^\\[(${CODE_ALTERNATION})\\]`);
+const CODE_PREFIX_RE = new RegExp(`^\\[(?:${CODE_ALTERNATION})\\]\\s*`);
+/** Lift the machine-readable code back out of a `[code] …` prefixed `errorMessage` (the single shared
+ *  parser — circuit breaker, degradation, and the Runner all read the prefix this way, council #7). */
+export function extractErrorCode(errorMessage) {
+    const m = errorMessage ? CODE_RE.exec(errorMessage) : null;
+    return m ? m[1] : undefined;
+}
+/** Strip a leading `[code] ` prefix (including the trailing space) from an `errorMessage`, leaving the
+ *  human text. Pairs with {@link extractErrorCode} so a caller can lift the code and clean the message
+ *  without re-hardcoding the code list (the Runner does both when assembling `TaskResult`). */
+export function stripErrorCodePrefix(errorMessage) {
+    return errorMessage.replace(CODE_PREFIX_RE, "");
+}
+//# sourceMappingURL=errors.js.map

package/dist/brain/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/brain/errors.ts"],"names":[],"mappings":"AASA;wGACwG;AACxG,MAAM,CAAC,MAAM,UAAU,GAAU;IAC/B,KAAK,EAAE,CAAC;IACR,MAAM,EAAE,CAAC;IACT,SAAS,EAAE,CAAC;IACZ,UAAU,EAAE,CAAC;IACb,WAAW,EAAE,CAAC;IACd,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE;CACrE,CAAC;AAEF;yGACyG;AACzG,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,iBAAiB,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAU,CAAC;AAG1G,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,IAAI,CAAiB;IACrB,MAAM,CAAU;IACzB,YAAY,IAAoB,EAAE,MAAc,EAAE,MAAe;QAC/D,KAAK,CAAC,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,0GAA0G;AAC1G,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,MAAM,CAAC;IACpD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,YAAY,CAAC;IACxC,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,iBAAiB,CAAC;IAC/D,4GAA4G;IAC5G,2GAA2G;IAC3G,8GAA8G;IAC9G,8GAA8G;IAC9G,8EAA8E;IAC9E,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,QAAQ,CAAC;IACtD,IAAI,MAAM,IAAI,GAAG;QAAE,OAAO,QAAQ,CAAC;IACnC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,gBAAgB,GAAG,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACrD,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,QAAQ,gBAAgB,MAAM,CAAC,CAAC;AAC3D,MAAM,cAAc,GAAG,IAAI,MAAM,CAAC,UAAU,gBAAgB,UAAU,CAAC,CAAC;AACxE;uGACuG;AACvG,MAAM,UAAU,gBAAgB,CAAC,YAAgC;IAC/D,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3D,OAAO,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAoB,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAED;;+FAE+F;AAC/F,MAAM,UAAU,oBAAoB,CAAC,YAAoB;IACvD,OAAO,YAAY,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;AAClD,CAAC"}

package/dist/brain/failover.d.ts

@@ -0,0 +1,18 @@
+import type { Brain } from "../core/types.js";
+/**
+ * Compose several brains into one with ordered failover (primary → fallbacks).
+ *
+ * The happy path streams live from the first brain. A brain is only failed over to the next when it
+ * fails **before emitting any content** (e.g. the gateway is down / connection refused, OR a
+ * first-token timeout that fires after the stream opened but before any delta) — a clean upfront
+ * failure. The leading `start` event is **held back** until the first real content event, so an
+ * error between `start` and the first delta can still fail over without ever having forwarded a
+ * (then-duplicated) `start`. Once real content (text/thinking/tool) has streamed, the outcome
+ * (including a mid-stream error or abort) is propagated rather than restarted, so the consumer never
+ * sees duplicate `start`/text events. The last brain's result is always final.
+ *
+ * Each underlying brain keeps its own retry policy (e.g. `createOpenAIBrain({ maxRetries })`);
+ * failover is the cross-gateway layer on top.
+ */
+export declare function createFailoverBrain(brains: Brain[]): Brain;
+//# sourceMappingURL=failover.d.ts.map

package/dist/brain/failover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failover.d.ts","sourceRoot":"","sources":["../../src/brain/failover.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAK9C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CA0G1D"}

package/dist/brain/failover.js

@@ -0,0 +1,118 @@
+import { createAssistantMessageEventStream, } from "../internal/llm.js";
+import { extractErrorCode } from "./errors.js";
+import { emitBrainTelemetry } from "./status-sink.js";
+import { passthroughStream } from "./degrading.js";
+/**
+ * Compose several brains into one with ordered failover (primary → fallbacks).
+ *
+ * The happy path streams live from the first brain. A brain is only failed over to the next when it
+ * fails **before emitting any content** (e.g. the gateway is down / connection refused, OR a
+ * first-token timeout that fires after the stream opened but before any delta) — a clean upfront
+ * failure. The leading `start` event is **held back** until the first real content event, so an
+ * error between `start` and the first delta can still fail over without ever having forwarded a
+ * (then-duplicated) `start`. Once real content (text/thinking/tool) has streamed, the outcome
+ * (including a mid-stream error or abort) is propagated rather than restarted, so the consumer never
+ * sees duplicate `start`/text events. The last brain's result is always final.
+ *
+ * Each underlying brain keeps its own retry policy (e.g. `createOpenAIBrain({ maxRetries })`);
+ * failover is the cross-gateway layer on top.
+ */
+export function createFailoverBrain(brains) {
+    if (brains.length === 0) {
+        throw new Error("createFailoverBrain: need at least one brain");
+    }
+    const stream = (model, context, options) => {
+        // design/131 (service [404]): per-task "fail rather than fail over" intent — only the primary is
+        // tried; a clean upfront failure surfaces as-is (no gateway swap polluting benchmark attribution).
+        // codex 131 审 A: pass-through keeps the reject→error-terminal normalization (shared helper).
+        if (options?.resilience?.allowFailover === false) {
+            return passthroughStream(brains[0], model, context, options);
+        }
+        const out = createAssistantMessageEventStream();
+        void (async () => {
+            // try/catch so a brain that REJECTS (rather than emitting an error event) still leaves a terminal
+            // on `out` — otherwise `result()` never resolves and the harness hangs (same class as the
+            // degradation-brain blocker; matches createCircuitBreakerBrain's discipline).
+            let lastFailedCode; // service [398] C1: why the previous hop was abandoned
+            try {
+                for (let i = 0; i < brains.length; i++) {
+                    const isLast = i === brains.length - 1;
+                    const inner = await brains[i].stream(model, context, options);
+                    let sawContent = false;
+                    let heldStart;
+                    let terminal;
+                    for await (const ev of inner) {
+                        if (ev.type === "done" || ev.type === "error") {
+                            terminal = ev;
+                            break;
+                        }
+                        if (ev.type === "start" && !sawContent) {
+                            heldStart = ev; // hold the leading start; only forward it once real content arrives
+                            continue;
+                        }
+                        if (!sawContent) {
+                            sawContent = true;
+                            if (heldStart)
+                                out.push(heldStart); // flush the held start right before the first content
+                        }
+                        out.push(ev); // forward live
+                    }
+                    const message = await inner.result();
+                    // design/118 follow-up (codex review): a MODEL-OUTPUT failure is not a gateway failure. A
+                    // `length_empty` cut (max_tokens exhausted with no answer text — possible with zero forwarded
+                    // deltas when reasoning happens server-side) would otherwise look like a clean upfront failure
+                    // and burn the whole fallback chain per attempt, even though every fallback gets the same
+                    // budget and dies the same way. Return it to the caller's recovery logic (compaction budget
+                    // escalation) instead.
+                    const cleanUpfrontFailure = message.stopReason === "error" &&
+                        options?.signal?.aborted !== true &&
+                        !sawContent &&
+                        message.errorKind !== "length_empty";
+                    if (cleanUpfrontFailure && !isLast) {
+                        // service [398] C1: remember WHY this hop was abandoned — the eventual telemetry frame
+                        // carries the last failed hop's canonical code (the reason the switch happened).
+                        lastFailedCode = extractErrorCode(message.errorMessage);
+                        continue; // try the next brain; nothing was forwarded yet
+                    }
+                    // service [398] C1 (clay 点名): a call served from a FALLBACK hop was previously invisible —
+                    // same-model gateway swaps leave `brain.call`'s model field unchanged. Fire-and-forget to the
+                    // Runner's telemetry sink (no-op standalone); emitted whether the hop succeeded or is the
+                    // last hop's own failure (either way the chain LEFT the primary — that's the signal).
+                    if (i > 0) {
+                        emitBrainTelemetry({
+                            kind: "failover",
+                            servedIndex: i,
+                            total: brains.length,
+                            ...(lastFailedCode !== undefined ? { errorCode: lastFailedCode } : {}),
+                        });
+                    }
+                    out.push(terminal ?? {
+                        type: "done",
+                        reason: message.stopReason,
+                        message,
+                    });
+                    return;
+                }
+            }
+            catch (e) {
+                const aborted = options?.signal?.aborted === true ||
+                    (e instanceof Error && (e.name === "AbortError" || e.name === "TimeoutError"));
+                const errorMsg = {
+                    role: "assistant",
+                    content: [{ type: "text", text: "" }],
+                    api: model.api,
+                    provider: model.provider,
+                    model: model.id,
+                    stopReason: aborted ? "aborted" : "error",
+                    errorMessage: e instanceof Error ? e.message : String(e),
+                    usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+                    timestamp: Date.now(),
+                };
+                out.push({ type: "error", reason: aborted ? "aborted" : "error", error: errorMsg });
+            }
+        })();
+        return out;
+    };
+    return { stream };
+}
+//# sourceMappingURL=failover.js.map

package/dist/brain/failover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failover.js","sourceRoot":"","sources":["../../src/brain/failover.ts"],"names":[],"mappings":"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"}

package/dist/brain/model-presets.d.ts

@@ -0,0 +1,36 @@
+/**
+ * First-party model presets (design/119, CC 2.1.198 rebaseline).
+ *
+ * sema stays caller-injects-`Model` by design (no baked catalog — the CC catalog/alias/family layer
+ * is a product surface we deliberately don't carry). What IS worth shipping is the per-model
+ * CAPABILITY facts a caller can't guess from the docs page: the Fable-5-class wire contract
+ * (adaptive thinking form, effort tiers, temperature rejection) that a wrong guess turns into a
+ * hard 400. These presets are DATA, not mechanism — every field can be overridden by the caller.
+ *
+ * Pricing is deliberately NOT baked (CC 198 doesn't bake it either): `cost` defaults to zeros and a
+ * deployment that wants cost accounting fills in the current official per-MTok rates.
+ */
+import type { AnthropicMessagesCompat, Model } from "../internal/llm.js";
+/**
+ * The Fable-5-class Anthropic wire contract (CC 2.1.198 capability bits, design/119 P0):
+ * - `thinkingMode: "adaptive"` — `thinking: { type: "adaptive" }`, NO budget_tokens (400 on budget).
+ * - `effortLevels` — the full five-tier `output_config.effort` range (fable-5 has `xhigh_effort` +
+ *   `max_effort`; a model without those bits should declare a shorter list and higher requests clamp).
+ * - `supportsTemperature: false` — CC never sends temperature to this class, thinking on OR off.
+ */
+export declare const FABLE_5_COMPAT: AnthropicMessagesCompat;
+/**
+ * Fable-5 behavioral guidance (CC 2.1.198 `fable_5_mitigations` — Anthropic's own runtime patches
+ * for this model class's known behavior pitfalls, adapted; design/119 S3). Carried on the Model as
+ * `promptGuidance` DATA — the injection mechanism (`Model.promptGuidance` → system-prompt tail) is
+ * generic and model-name-free.
+ */
+export declare const FABLE_5_PROMPT_GUIDANCE: string[];
+/**
+ * A ready-to-use `claude-fable-5` {@link Model} (CC 2.1.198 registry facts: 1M-token native context
+ * window, 64k default max output — the 128k tier is opt-in via `maxTokens` override, knowledge
+ * cutoff Jan 2026, `default_effort: "high"`). Override anything per deployment; set `cost` for
+ * accounting (not baked — see module note).
+ */
+export declare function fable5Model(overrides?: Partial<Model>): Model;
+//# sourceMappingURL=model-presets.d.ts.map

package/dist/brain/model-presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-presets.d.ts","sourceRoot":"","sources":["../../src/brain/model-presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,uBAAuB,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,uBAI5B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,EAO3C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,SAAS,GAAE,OAAO,CAAC,KAAK,CAAM,GAAG,KAAK,CAoBjE"}

package/dist/brain/model-presets.js

@@ -0,0 +1,54 @@
+/**
+ * The Fable-5-class Anthropic wire contract (CC 2.1.198 capability bits, design/119 P0):
+ * - `thinkingMode: "adaptive"` — `thinking: { type: "adaptive" }`, NO budget_tokens (400 on budget).
+ * - `effortLevels` — the full five-tier `output_config.effort` range (fable-5 has `xhigh_effort` +
+ *   `max_effort`; a model without those bits should declare a shorter list and higher requests clamp).
+ * - `supportsTemperature: false` — CC never sends temperature to this class, thinking on OR off.
+ */
+export const FABLE_5_COMPAT = {
+    thinkingMode: "adaptive",
+    effortLevels: ["low", "medium", "high", "xhigh", "max"],
+    supportsTemperature: false,
+};
+/**
+ * Fable-5 behavioral guidance (CC 2.1.198 `fable_5_mitigations` — Anthropic's own runtime patches
+ * for this model class's known behavior pitfalls, adapted; design/119 S3). Carried on the Model as
+ * `promptGuidance` DATA — the injection mechanism (`Model.promptGuidance` → system-prompt tail) is
+ * generic and model-name-free.
+ */
+export const FABLE_5_PROMPT_GUIDANCE = [
+    // CC Wmf: the final message carries everything / lead with outcome.
+    "Your final message of a turn is the only text the caller is guaranteed to read. Put every conclusion, answer, and deliverable in it — lead with the outcome, then supporting detail. Never leave a result only in an intermediate message or in your reasoning.",
+    // CC Xmf: autonomous operation — end-turn self-check, review before state-changing actions.
+    "When operating autonomously: before ending your turn, check that the task is actually complete (not just planned); before any state-changing action, re-verify that the evidence supports that specific action rather than pattern-matching a familiar case.",
+    // CC zmf: tool parameters take exactly one JSON value each.
+    "When calling tools, provide exactly ONE complete JSON value per parameter — never concatenate multiple values, never truncate, never wrap a value in commentary.",
+];
+/**
+ * A ready-to-use `claude-fable-5` {@link Model} (CC 2.1.198 registry facts: 1M-token native context
+ * window, 64k default max output — the 128k tier is opt-in via `maxTokens` override, knowledge
+ * cutoff Jan 2026, `default_effort: "high"`). Override anything per deployment; set `cost` for
+ * accounting (not baked — see module note).
+ */
+export function fable5Model(overrides = {}) {
+    return {
+        id: "claude-fable-5",
+        name: "Claude Fable 5",
+        api: "anthropic-messages",
+        provider: "anthropic",
+        baseUrl: "https://api.anthropic.com",
+        reasoning: true,
+        defaultThinking: "high",
+        input: ["text", "image"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 1_000_000,
+        maxTokens: 64_000,
+        // design/123 D2: CC 198's structural coefficient for the NEWER model families (its lb table:
+        // claude-3.x / opus·sonnet-4-x / haiku-4-5 → chars/4; sonnet-5/fable-5 class → chars/3).
+        charsPerToken: 3,
+        compat: { ...FABLE_5_COMPAT },
+        promptGuidance: [...FABLE_5_PROMPT_GUIDANCE],
+        ...overrides,
+    };
+}
+//# sourceMappingURL=model-presets.js.map

package/dist/brain/model-presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-presets.js","sourceRoot":"","sources":["../../src/brain/model-presets.ts"],"names":[],"mappings":"AAcA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAA4B;IACrD,YAAY,EAAE,UAAU;IACxB,YAAY,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC;IACvD,mBAAmB,EAAE,KAAK;CAC3B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAa;IAC/C,oEAAoE;IACpE,iQAAiQ;IACjQ,4FAA4F;IAC5F,8PAA8P;IAC9P,4DAA4D;IAC5D,kKAAkK;CACnK,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,YAA4B,EAAE;IACxD,OAAO;QACL,EAAE,EAAE,gBAAgB;QACpB,IAAI,EAAE,gBAAgB;QACtB,GAAG,EAAE,oBAAoB;QACzB,QAAQ,EAAE,WAAW;QACrB,OAAO,EAAE,2BAA2B;QACpC,SAAS,EAAE,IAAI;QACf,eAAe,EAAE,MAAM;QACvB,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;QACxB,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE;QAC1D,aAAa,EAAE,SAAS;QACxB,SAAS,EAAE,MAAM;QACjB,6FAA6F;QAC7F,yFAAyF;QACzF,aAAa,EAAE,CAAC;QAChB,MAAM,EAAE,EAAE,GAAG,cAAc,EAAE;QAC7B,cAAc,EAAE,CAAC,GAAG,uBAAuB,CAAC;QAC5C,GAAG,SAAS;KACb,CAAC;AACJ,CAAC"}