@sema-agent/core 5.12.0 → 5.14.0

package/dist/brain/open-responses.js

@@ -5,7 +5,7 @@ import { createRepetitionPoll, parseStreamedToolArgs } from "./stream-shared.js"
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { RESPONSES_RESERVED, applyExtraBody, stripAuthHeaders } from "./request-params.js";
+import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, stripAuthHeaders } from "./request-params.js";
 import { DEFAULT_EFFORT_LEVELS, isThinkingLevel, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 const DEGENERATE_POLL_CHARS = 64;
@@ -222,6 +222,8 @@ export function createOpenResponsesBrain(config = {}) {
         let sentMaxTokens;
         let sentMaxTokensLane = "unset";
         let sentEffort;
+        let builtMaxTokens;
+        let builtMaxTokensLane = "unset";
         return runStreamingBrain({
             model,
             doFetch,
@@ -229,7 +231,7 @@ export function createOpenResponsesBrain(config = {}) {
             config,
             httpLabel: "responses",
             stallTimeouts: options?.stallTimeouts,
-            buildRequest: () => {
+            buildRequest: (overrides) => {
                 const apiKey = options?.apiKey ?? config.apiKey;
                 const root = (model.baseUrl || config.baseUrl || "").replace(/\/+$/, "");
                 if (!root) {
@@ -239,9 +241,8 @@ export function createOpenResponsesBrain(config = {}) {
                     throw new Error("createOpenResponsesBrain: options.stop is not expressible in the Open Responses request (the wire form has no stop-sequence field); " +
                         "remove it, or serve this model through the chat-completions lane, which does support it");
                 }
-                const requestedMaxTokens = options?.maxTokens ?? model.maxTokens;
+                const requestedMaxTokens = overrides?.maxOutputTokens ?? options?.maxTokens ?? model.maxTokens;
                 const effort = resolveWireEffort(model, options?.reasoning);
-                sentEffort = effort;
                 const body = {
                     model: model.id,
                     input: toResponsesInput(context, model, config.replayReasoning !== false),
@@ -257,12 +258,13 @@ export function createOpenResponsesBrain(config = {}) {
                 if (requestedMaxTokens !== undefined) {
                     const capped = Math.max(1, requestedMaxTokens);
                     body.max_output_tokens = capped;
-                    sentMaxTokens = capped;
-                    sentMaxTokensLane = options?.maxTokens !== undefined ? "options" : "model";
+                    builtMaxTokens = capped;
+                    builtMaxTokensLane =
+                        overrides?.maxOutputTokens !== undefined ? "engine" : options?.maxTokens !== undefined ? "options" : "model";
                 }
                 else {
-                    sentMaxTokens = undefined;
-                    sentMaxTokensLane = "unset";
+                    builtMaxTokens = undefined;
+                    builtMaxTokensLane = "unset";
                 }
                 if (effort !== undefined)
                     body.reasoning = { effort };
@@ -276,10 +278,18 @@ export function createOpenResponsesBrain(config = {}) {
                 headers["content-type"] = "application/json";
                 if (apiKey)
                     headers["authorization"] = `Bearer ${apiKey}`;
+                const wire = applyExtraBody(body, model.extraBody, RESPONSES_RESERVED);
                 return {
                     url: `${root}/responses`,
                     headers,
-                    body: JSON.stringify(applyExtraBody(body, model.extraBody, RESPONSES_RESERVED)),
+                    body: JSON.stringify(wire),
+                    outputCapTokens: effectiveOutputCap(wire, OUTPUT_CAP_KEYS.responses),
+                    capDerivedPaths: OUTPUT_CAP_KEYS.responses,
+                    onCommitted: () => {
+                        sentMaxTokens = builtMaxTokens;
+                        sentMaxTokensLane = builtMaxTokensLane;
+                        sentEffort = effort;
+                    },
                 };
             },
             makeParser: (ctrl) => {
@@ -671,7 +681,11 @@ export function createOpenResponsesBrain(config = {}) {
                         const refused = accumRefusal.trim().length > 0;
                         const emptyNoFinish = noUsableContent && terminalStatus === undefined && !degenerate;
                         const maxTokensNote = sentMaxTokens !== undefined
-                            ? `effective max_output_tokens=${sentMaxTokens} (from ${sentMaxTokensLane === "options" ? "options.maxTokens" : "model.maxTokens"})`
+                            ? `effective max_output_tokens=${sentMaxTokens} (from ${sentMaxTokensLane === "options"
+                                ? "options.maxTokens"
+                                : sentMaxTokensLane === "engine"
+                                    ? "the engine's context-overflow recovery"
+                                    : "model.maxTokens"})`
                             : "max_output_tokens not set (neither options.maxTokens nor model.maxTokens — the endpoint's default cap applied)";
                         const errorMessage = degenerate
                             ? DEGENERATE_MESSAGE

package/dist/brain/openai.js

@@ -5,7 +5,7 @@ import { createRepetitionPoll, parseStreamedToolArgs } from "./stream-shared.js"
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { OPENAI_RESERVED, applyExtraBody, stripAuthHeaders } from "./request-params.js";
+import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, stripAuthHeaders } from "./request-params.js";
 import { DEFAULT_EFFORT_LEVELS, isThinkingLevel, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 function closeToolCallAccum(acc) {
@@ -268,6 +268,8 @@ export function createOpenAIBrain(config = {}) {
     const stream = (model, context, options) => {
         let sentMaxTokens;
         let sentMaxTokensLane = "unset";
+        let builtMaxTokens;
+        let builtMaxTokensLane = "unset";
         return runStreamingBrain({
             model,
             doFetch,
@@ -275,7 +277,7 @@ export function createOpenAIBrain(config = {}) {
             config,
             httpLabel: "gateway",
             stallTimeouts: options?.stallTimeouts,
-            buildRequest: () => {
+            buildRequest: (overrides) => {
                 const apiKey = options?.apiKey ?? config.apiKey;
                 const root = (model.baseUrl || config.baseUrl || "").replace(/\/+$/, "");
                 if (!root) {
@@ -292,18 +294,19 @@ export function createOpenAIBrain(config = {}) {
                     body.tools = tools;
                 if (options?.temperature !== undefined)
                     body.temperature = options.temperature;
-                const requestedMaxTokens = options?.maxTokens ?? model.maxTokens;
+                const requestedMaxTokens = overrides?.maxOutputTokens ?? options?.maxTokens ?? model.maxTokens;
+                const declared = (model.compat ?? {}).maxTokensField;
+                const mtField = declared ?? inferMaxTokensField(model.id);
                 if (requestedMaxTokens !== undefined) {
-                    const declared = (model.compat ?? {}).maxTokensField;
-                    const mtField = declared ?? inferMaxTokensField(model.id);
                     const capped = Math.max(1, requestedMaxTokens);
                     body[mtField] = capped;
-                    sentMaxTokens = capped;
-                    sentMaxTokensLane = options?.maxTokens !== undefined ? "options" : "model";
+                    builtMaxTokens = capped;
+                    builtMaxTokensLane =
+                        overrides?.maxOutputTokens !== undefined ? "engine" : options?.maxTokens !== undefined ? "options" : "model";
                 }
                 else {
-                    sentMaxTokens = undefined;
-                    sentMaxTokensLane = "unset";
+                    builtMaxTokens = undefined;
+                    builtMaxTokensLane = "unset";
                 }
                 if (options?.stop)
                     body.stop = options.stop;
@@ -318,7 +321,18 @@ export function createOpenAIBrain(config = {}) {
                 headers["content-type"] = "application/json";
                 if (apiKey)
                     headers["authorization"] = `Bearer ${apiKey}`;
-                return { url: `${root}/chat/completions`, headers, body: JSON.stringify(applyExtraBody(body, model.extraBody, OPENAI_RESERVED)) };
+                const wire = applyExtraBody(body, model.extraBody, OPENAI_RESERVED);
+                return {
+                    url: `${root}/chat/completions`,
+                    headers,
+                    body: JSON.stringify(wire),
+                    outputCapTokens: effectiveOutputCap(wire, OUTPUT_CAP_KEYS.openai),
+                    capDerivedPaths: [mtField],
+                    onCommitted: () => {
+                        sentMaxTokens = builtMaxTokens;
+                        sentMaxTokensLane = builtMaxTokensLane;
+                    },
+                };
             },
             makeParser: (ctrl) => {
                 const { out, partial } = ctrl;
@@ -557,7 +571,11 @@ export function createOpenAIBrain(config = {}) {
                         const refused = accumRefusal.trim().length > 0;
                         const emptyNoFinish = noUsableContent && finishReason == null && !degenerate;
                         const maxTokensNote = sentMaxTokens !== undefined
-                            ? `effective max_tokens=${sentMaxTokens} (from ${sentMaxTokensLane === "options" ? "options.maxTokens" : "model.maxTokens"})`
+                            ? `effective max_tokens=${sentMaxTokens} (from ${sentMaxTokensLane === "options"
+                                ? "options.maxTokens"
+                                : sentMaxTokensLane === "engine"
+                                    ? "the engine's context-overflow recovery"
+                                    : "model.maxTokens"})`
                             : "max_tokens not set (neither options.maxTokens nor model.maxTokens — the provider's default cap applied)";
                         const errorMessage = degenerate
                             ? DEGENERATE_MESSAGE

package/dist/brain/request-params.d.ts

@@ -4,4 +4,6 @@ export declare const RESPONSES_RESERVED: ReadonlySet<string>;
 export declare function reservedFor(api: string): ReadonlySet<string>;
 export declare function applyExtraBody(body: Record<string, unknown>, extraBody: Record<string, unknown> | undefined, reserved: ReadonlySet<string>): Record<string, unknown>;
 export declare function stripAuthHeaders(headers: Record<string, string>): void;
+export declare const OUTPUT_CAP_KEYS: Readonly<Record<"openai" | "anthropic" | "responses", readonly string[]>>;
+export declare function effectiveOutputCap(body: Record<string, unknown>, keys: readonly string[]): number | undefined;
 export declare function reservedCollisions(extraBody: Record<string, unknown> | undefined, reserved: ReadonlySet<string>): string[];

package/dist/brain/request-params.js

@@ -61,6 +61,22 @@ export function stripAuthHeaders(headers) {
             delete headers[k];
     }
 }
+export const OUTPUT_CAP_KEYS = {
+    openai: ["max_tokens", "max_completion_tokens"],
+    anthropic: ["max_tokens"],
+    responses: ["max_output_tokens"],
+};
+export function effectiveOutputCap(body, keys) {
+    let smallest;
+    for (const key of keys) {
+        const raw = body[key];
+        if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0)
+            continue;
+        if (smallest === undefined || raw < smallest)
+            smallest = raw;
+    }
+    return smallest;
+}
 export function reservedCollisions(extraBody, reserved) {
     return extraBody ? Object.keys(extraBody).filter((k) => reserved.has(k)) : [];
 }

package/dist/brain/stream-engine.d.ts

@@ -5,10 +5,18 @@ export interface StreamEngineConfig extends BrainTimeoutConfig {
     retryDelayMs?: number;
 }
 export declare function resolveMaxRetries(configured: number | undefined): number;
+export declare function sameRequestModuloCap(original: SSERequest, rebuilt: SSERequest, imposedCap: number): boolean;
+export declare function shouldRetryHeaderVerdict(res: Response | undefined): boolean | undefined;
 export interface SSERequest {
     url: string;
     headers: Record<string, string>;
     body: string;
+    outputCapTokens?: number;
+    capDerivedPaths?: readonly string[];
+    onCommitted?: () => void;
+}
+export interface BuildRequestOverrides {
+    maxOutputTokens?: number;
 }
 export interface StreamControls {
     out: ReturnType<typeof createAssistantMessageEventStream>;
@@ -32,7 +40,7 @@ export declare function runStreamingBrain(args: {
     signal?: AbortSignal;
     config: StreamEngineConfig;
     httpLabel: string;
-    buildRequest: () => SSERequest;
+    buildRequest: (overrides?: BuildRequestOverrides) => SSERequest;
     makeParser: (ctrl: StreamControls) => StreamParser;
     stallTimeouts?: {
         connectMs?: number;

package/dist/brain/stream-engine.js

@@ -1,4 +1,5 @@
 import { createAssistantMessageEventStream, } from "../internal/llm.js";
+import { FLOOR_OUTPUT_TOKENS, parseContextOverflow, planOutputCapAdjustment } from "./context-overflow.js";
 import { BrainError, classifyHttp, describeNetworkError } from "./errors.js";
 import { retryBackoffMs } from "./retry.js";
 import { emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
@@ -17,6 +18,169 @@ export function resolveMaxRetries(configured) {
     }
     return DEFAULT_MAX_RETRIES;
 }
+const SHOULD_RETRY_HEADER = "x-should-retry";
+function sameHeaders(a, b) {
+    const aKeys = Object.keys(a);
+    if (aKeys.length !== Object.keys(b).length)
+        return false;
+    return aKeys.every((k) => Object.prototype.hasOwnProperty.call(b, k) && a[k] === b[k]);
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (typeof value === "object" && value !== null) {
+        const rec = value;
+        return `{${Object.keys(rec)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${canonicalJson(rec[k])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function leafHolder(root, path) {
+    const parts = path.split(".");
+    const leaf = parts.pop();
+    if (leaf === undefined)
+        return undefined;
+    let cur = root;
+    for (const part of parts) {
+        if (typeof cur !== "object" || cur === null || Array.isArray(cur))
+            return undefined;
+        cur = cur[part];
+    }
+    if (typeof cur !== "object" || cur === null || Array.isArray(cur))
+        return undefined;
+    return { holder: cur, leaf };
+}
+export function sameRequestModuloCap(original, rebuilt, imposedCap) {
+    if (rebuilt.url !== original.url || !sameHeaders(rebuilt.headers, original.headers))
+        return false;
+    if (rebuilt.outputCapTokens !== imposedCap)
+        return false;
+    if (rebuilt.body === original.body)
+        return true;
+    const parse = (raw) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    };
+    const a = parse(original.body);
+    const b = parse(rebuilt.body);
+    if (a === undefined || b === undefined)
+        return false;
+    for (const path of new Set([...(original.capDerivedPaths ?? []), ...(rebuilt.capDerivedPaths ?? [])])) {
+        const from = leafHolder(a, path);
+        const to = leafHolder(b, path);
+        const before = from === undefined ? undefined : from.holder[from.leaf];
+        const after = to === undefined ? undefined : to.holder[to.leaf];
+        if (before !== undefined) {
+            if (typeof before !== "number" || typeof after !== "number")
+                return false;
+            if (after > before)
+                return false;
+        }
+        if (from !== undefined)
+            delete from.holder[from.leaf];
+        if (to !== undefined)
+            delete to.holder[to.leaf];
+    }
+    return canonicalJson(a) === canonicalJson(b);
+}
+const ERROR_BODY_BYTE_CAP = 64 * 1024;
+const ERROR_BODY_READ_TIMEOUT_MS = 5_000;
+async function readErrorBody(res, signal) {
+    const body = res.body;
+    if (body === null)
+        return { text: "", endedNormally: true };
+    let reader;
+    try {
+        reader = body.getReader();
+    }
+    catch {
+        return { text: "", endedNormally: false };
+    }
+    const decoder = new TextDecoder();
+    let stopped = false;
+    const stop = () => {
+        stopped = true;
+        void reader.cancel().catch(() => undefined);
+    };
+    let timer;
+    let out = "";
+    let endedNormally = false;
+    try {
+        timer = setTimeout(stop, ERROR_BODY_READ_TIMEOUT_MS);
+        signal?.addEventListener("abort", stop, { once: true });
+        if (signal?.aborted === true)
+            stop();
+        let bytes = 0;
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done) {
+                endedNormally = !stopped;
+                break;
+            }
+            const value = chunk.value;
+            if (value === undefined)
+                continue;
+            const room = ERROR_BODY_BYTE_CAP - bytes;
+            const usable = value.byteLength <= room ? value : value.subarray(0, room);
+            bytes += usable.byteLength;
+            out += decoder.decode(usable, { stream: true });
+            if (bytes >= ERROR_BODY_BYTE_CAP) {
+                stop();
+                break;
+            }
+        }
+        out += decoder.decode();
+    }
+    catch {
+        endedNormally = false;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        signal?.removeEventListener("abort", stop);
+        stop();
+    }
+    return { text: out, endedNormally };
+}
+function discardResponseBody(res) {
+    const body = res?.body;
+    if (body === undefined || body === null || body.locked)
+        return;
+    try {
+        void body.cancel().catch(() => undefined);
+    }
+    catch {
+    }
+}
+export function shouldRetryHeaderVerdict(res) {
+    if (res === undefined)
+        return undefined;
+    let raw = null;
+    try {
+        const headers = res.headers;
+        if (headers === undefined || headers === null || typeof headers.get !== "function")
+            return undefined;
+        raw = res.headers.get(SHOULD_RETRY_HEADER);
+    }
+    catch {
+        return undefined;
+    }
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    return undefined;
+}
 const RETRY_STATUS_SLICE_MS = 30_000;
 const THINKING_RETRY_BUDGET = 2;
 const EMPTY_USAGE = {
@@ -103,7 +267,9 @@ export function runStreamingBrain(args) {
     });
     return out;
     async function run() {
-        const req = buildRequest();
+        let req = buildRequest();
+        req.onCommitted?.();
+        let maxOutputTokensOverride;
         const maxRetries = resolveMaxRetries(config.maxRetries);
         const baseDelay = config.retryDelayMs ?? 500;
         const firstTokenTimeoutMs = resolveStallTimeoutMs(config.firstTokenTimeoutMs ?? stallTimeouts?.firstTokenMs, "firstTokenTimeoutMs");
@@ -146,33 +312,96 @@ export function runStreamingBrain(args) {
                     res = r;
                     break;
                 }
-                cc.dispose();
-                const retryable = netErr !== undefined ||
-                    (r !== undefined && (r.status >= 500 || r.status === 429 || r.status === 408 || r.status === 409));
-                if (retryable && attempt < maxRetries) {
-                    const delayMs = retryBackoffMs(baseDelay, attempt, r);
-                    const statusPhase = r?.status === 429 ? "rate_limited" : netErr !== undefined ? "reconnecting" : "retrying";
-                    emitBrainTelemetry({ kind: "retry", attempt: attempt + 1, phase: "connect" });
-                    announcedRetry = true;
-                    await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
-                        phase: statusPhase,
-                        detail: statusPhase === "rate_limited"
-                            ? "rate limited, backing off"
-                            : statusPhase === "reconnecting"
-                                ? "connection lost, reconnecting"
-                                : "transient error, retrying",
-                        retryInSec: Math.ceil(remainingMs / 1000),
-                        retryInMs: remainingMs,
-                        attempt: attempt + 1,
-                        maxRetries,
-                    }));
-                    continue;
+                cc.clearTimer();
+                try {
+                    let overflowBody;
+                    let overflowDeclineNote = "";
+                    if (r !== undefined && r.status === 400) {
+                        const read = await readErrorBody(r, signal);
+                        overflowBody = read.text;
+                        const report = read.endedNormally ? parseContextOverflow(r.status, read.text) : undefined;
+                        if (report !== undefined) {
+                            const plan = planOutputCapAdjustment(report, [maxOutputTokensOverride, req.outputCapTokens]);
+                            if (plan.outcome === "adjust" && attempt < maxRetries) {
+                                let rebuilt;
+                                try {
+                                    rebuilt = buildRequest({ maxOutputTokens: plan.maxOutputTokens });
+                                }
+                                catch {
+                                    rebuilt = undefined;
+                                }
+                                let acceptable = false;
+                                try {
+                                    acceptable = rebuilt !== undefined && sameRequestModuloCap(req, rebuilt, plan.maxOutputTokens);
+                                }
+                                catch {
+                                    acceptable = false;
+                                }
+                                if (acceptable && rebuilt !== undefined) {
+                                    const previousCap = plan.current;
+                                    maxOutputTokensOverride = plan.maxOutputTokens;
+                                    req = rebuilt;
+                                    req.onCommitted?.();
+                                    emitBrainTelemetry({ kind: "retry", attempt: attempt + 1, phase: "connect" });
+                                    announcedRetry = true;
+                                    emitBrainStatus({
+                                        phase: "retrying",
+                                        detail: `output limit lowered from ${previousCap} to ${plan.maxOutputTokens} tokens, retrying`,
+                                        attempt: attempt + 1,
+                                        maxRetries,
+                                    });
+                                    continue;
+                                }
+                                overflowDeclineNote =
+                                    rebuilt === undefined
+                                        ? ` — output-cap recovery declined: the request could not be rebuilt with a smaller cap`
+                                        : ` — output-cap recovery declined: rebuilding the request changed more than the output cap (its destination, headers, or some other body field moved), so this would no longer be the same request with a smaller cap`;
+                            }
+                            else {
+                                overflowDeclineNote =
+                                    plan.outcome === "below_floor"
+                                        ? ` — output-cap recovery declined: only ${plan.available} tokens are available under the context limit, below the ${FLOOR_OUTPUT_TOKENS}-token floor; the input itself must shrink`
+                                        : plan.outcome === "no_progress"
+                                            ? ` — output-cap recovery declined: the recomputed cap (${plan.available}) is not below the ${plan.current} already in effect, so re-sending cannot help`
+                                            : ` — output-cap recovery declined: the retry budget (${maxRetries}) is exhausted`;
+                            }
+                        }
+                    }
+                    const retryableByStatus = netErr !== undefined ||
+                        (r !== undefined && (r.status >= 500 || r.status === 429 || r.status === 408 || r.status === 409));
+                    const retryable = shouldRetryHeaderVerdict(r) ?? retryableByStatus;
+                    if (retryable && attempt < maxRetries) {
+                        const delayMs = retryBackoffMs(baseDelay, attempt, r);
+                        const statusPhase = r?.status === 429 ? "rate_limited" : netErr !== undefined ? "reconnecting" : "retrying";
+                        emitBrainTelemetry({ kind: "retry", attempt: attempt + 1, phase: "connect" });
+                        announcedRetry = true;
+                        discardResponseBody(r);
+                        cc.abort();
+                        cc.dispose();
+                        await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
+                            phase: statusPhase,
+                            detail: statusPhase === "rate_limited"
+                                ? "rate limited, backing off"
+                                : statusPhase === "reconnecting"
+                                    ? "connection lost, reconnecting"
+                                    : "transient error, retrying",
+                            retryInSec: Math.ceil(remainingMs / 1000),
+                            retryInMs: remainingMs,
+                            attempt: attempt + 1,
+                            maxRetries,
+                        }));
+                        continue;
+                    }
+                    if (netErr)
+                        throw new BrainError("network", describeNetworkError(netErr));
+                    const detail = overflowBody ?? (r ? (await readErrorBody(r, signal)).text : "");
+                    const status = r?.status ?? 0;
+                    throw new BrainError(classifyHttp(status), `${httpLabel} HTTP ${status || "ERR"}: ${detail.slice(0, 500)}${overflowDeclineNote}`, status);
+                }
+                finally {
+                    cc.abort();
+                    cc.dispose();
                 }
-                if (netErr)
-                    throw new BrainError("network", describeNetworkError(netErr));
-                const detail = r ? await r.text().catch(() => "") : "";
-                const status = r?.status ?? 0;
-                throw new BrainError(classifyHttp(status), `${httpLabel} HTTP ${status || "ERR"}: ${detail.slice(0, 500)}`, status);
             }
             const partial = emptyAssistant(model);
             if (!startEmitted) {

package/dist/brain/timeout.d.ts

@@ -12,6 +12,7 @@ export declare function createConnectController(connectTimeoutMs: number | undef
     signal: AbortSignal;
     timedOut: () => boolean;
     clearTimer: () => void;
+    abort: () => void;
     dispose: () => void;
 };
 export declare const BRAIN_CALL_GUARDRAIL_DEFAULT_MS = 3600000;

package/dist/brain/timeout.js

@@ -37,6 +37,7 @@ export function createConnectController(connectTimeoutMs, outerSignal) {
         signal: ac.signal,
         timedOut: () => timedOut,
         clearTimer,
+        abort: () => ac.abort(),
         dispose: () => {
             clearTimer();
             if (outerSignal)

package/dist/core/a2a.d.ts

@@ -3,8 +3,8 @@ import type { A2aServerSpec, ToolEffect } from "./types.js";
 export declare const A2A_SKILL_DESCRIPTION_MAX_CHARS = 2048;
 export interface A2aToolAxis {
     name: string;
-    irreversibility?: "always";
-    egress?: true;
+    irreversibility?: "always" | "never";
+    egress?: boolean;
     effect?: ToolEffect;
 }
 export interface A2aPeerStatus {

package/dist/core/a2a.js

@@ -325,9 +325,9 @@ function a2aAxisFor(name, override) {
     if (override.effect !== undefined)
         axis.effect = override.effect;
     if (override.egress === false)
-        delete axis.egress;
-    if (override.irreversibility === "always")
-        axis.irreversibility = "always";
+        axis.egress = false;
+    if (override.irreversibility !== undefined)
+        axis.irreversibility = override.irreversibility;
     return axis;
 }
 function renderParts(parts) {

package/dist/core/ask-question.d.ts

@@ -17,6 +17,8 @@ export interface AskQuestionRequest {
     questions: AskQuestion[];
     readonly principal?: string;
     readonly sourceTaskId?: string;
+    readonly boundInputHash?: string;
+    readonly deliveryId?: string;
 }
 export interface QuestionAnswerItem {
     header: string;
@@ -26,10 +28,53 @@ export interface QuestionAnswerItem {
 export interface QuestionAnswer {
     answers: QuestionAnswerItem[];
 }
-export type OnQuestion = (req: AskQuestionRequest, signal?: AbortSignal) => Promise<QuestionAnswer>;
+export interface QuestionUnavailable {
+    readonly kind: "unavailable";
+}
+export type OnQuestionOutcome = QuestionAnswer | QuestionUnavailable;
+export type QuestionOutcomeReading = {
+    readonly shape: "answered";
+    readonly answer: QuestionAnswer;
+} | {
+    readonly shape: "unavailable";
+} | {
+    readonly shape: "contradictory";
+};
+export declare function classifyQuestionOutcome(outcome: OnQuestionOutcome): QuestionOutcomeReading;
+export declare function canonicalizeCapturedPlainData(node: unknown, seen?: WeakSet<object>): boolean;
+export declare function isQuestionUnavailable(outcome: OnQuestionOutcome): outcome is QuestionUnavailable;
+export type OnQuestion = (req: AskQuestionRequest, signal?: AbortSignal) => Promise<OnQuestionOutcome>;
+export type SyntheticContinuationReason = "seam_absent" | "callback_failed" | "declined_unavailable";
+export type AskAnswerContinuationSource = "human_response" | "synthetic_self_answer_instruction";
+export type AskQuestionCardDetails = {
+    type: "ask-question";
+    questionId: string;
+    continuationSource: AskAnswerContinuationSource;
+    runContinues: true;
+    reason?: SyntheticContinuationReason;
+} | {
+    type: "ask-question";
+    questionId: string;
+    code: "question.human_channel_failed" | "question.human_unavailable";
+    reason: "callback_failed" | "declined_unavailable";
+};
+export declare function askQuestionContinuationCard(questionId: string, continuationSource: AskAnswerContinuationSource, reason?: SyntheticContinuationReason): AskQuestionCardDetails;
+export declare function validateAskQuestions(questions: unknown): string | undefined;
+export interface AskUserQuestionToolOptions {
+    posture?: "interactive" | "headless";
+    interactiveFallback?: boolean;
+    onSyntheticContinuation?: (info: {
+        questionId: string;
+        reason: SyntheticContinuationReason;
+    }) => void;
+    redeemedApprovalCallId?: string;
+    redeemedApprovalQuestionsHash?: string;
+}
 export declare function createDurableQuestionPolicy(): ToolPolicy;
 export declare const QUESTION_AWAITS_RESUME: OnQuestion;
+export declare function markBoundOnlyQuestionFace<F extends OnQuestion>(face: F): F;
+export declare function isLiveQuestionFace(face: unknown): face is OnQuestion;
 export declare function createAskUserQuestionTool(onQuestion?: OnQuestion, source?: {
     principal?: string;
     sourceTaskId?: string;
-}): AgentTool;
+}, opts?: AskUserQuestionToolOptions): AgentTool;