@sema-agent/core 7.32.1 → 7.33.0

package/dist/brain/timeout.d.ts

@@ -1,14 +1,20 @@
 import type { StreamFn } from "../internal/llm.js";
 /**
- * Tiered timeouts (1.38.1, design/17 §5B). The task-level `timeoutSec` only bounds the *whole* run;
- * it can't tell apart a gateway that never accepts the connection from one that accepts it, opens the
- * SSE stream, then hangs forever without emitting a token (the most common gateway-stall symptom).
- * Two finer levels close that gap, each retryable as a transient `network` failure:
+ * Tiered timeouts (design/17 §5B; re-cut along the segments of a call in 7.33.0). The task-level
+ * `timeoutSec` only bounds the *whole* run; it cannot tell apart a gateway that never completes the
+ * handshake, one that accepts the request and then holds the response headers while it works, one
+ * that opens the stream and never emits a token, and one that goes quiet mid-answer. Four clocks,
+ * one per segment, each named for the segment it bounds:
  *
- * - **connect**: `fetch` hasn't returned response headers in time.
- * - **first-token**: the SSE stream is open but no content delta has arrived (see brain read loops).
+ * - **connect**: TCP + TLS establishment inside `fetch` — the transport's own clock (undici's 10s by
+ *   default), tuned on the process dispatcher the host installs; not a knob here (`transport.ts`).
+ * - **first-byte**: the `fetch()` call → response headers. A stall here is this process cancelling
+ *   its own request at a deadline it chose, and is announced as such.
+ * - **first-token**: headers → the first content delta (a thinking delta counts).
+ * - **idle**: silence between deltas once output has started.
  *
- * Both default to `undefined` (disabled) so existing behavior is unchanged.
+ * Every field resolves through the same chain: construction config (an explicit `0` is OFF) >
+ * per-call advisory (`StreamOptions.stallTimeouts`) > the engine default constant below.
  */
 /**
  * The largest delay a host timer can actually wait for. Past this `setTimeout` does not schedule far in
@@ -28,55 +34,107 @@ export declare const MAX_TIMER_DELAY_MS = 2147483647;
  */
 export declare function resolveStallTimeoutMs(value: number | undefined, knob: string): number | undefined;
 /**
- * The engine's ADVISORY per-call stall watchdog values (`StreamOptions.stallTimeouts`), supplied on
- * every provider call. They are a GUARDRAIL, not part of any budget lane: `BrainTimeoutConfig` defaults
- * every watchdog to OFF, so without these an in-flight call that goes silent is bounded by nothing
- * finer than the hour-scale {@link BRAIN_CALL_GUARDRAIL_DEFAULT_MS} (a measured production frame sat
- * 680s with ZERO deltas). A silent stream is never worth more than these bounds, whether or not the
- * task declared a time limit. All three surface as the brain's existing retryable `network` stall
- * class (design/124 tier C retries a zero-content cut, so a transient gateway hang still recovers). 量纲:
- *   - connect 30s: bounds the fetch→response-HEADERS wait — the one segment every post-headers
- *     watchdog is blind to. On a streaming API the model's time is spent AFTER headers, so 30s with
- *     none at all is a hung gateway, not a slow model.
+ * The engine's DEFAULT watchdog values, one per segment of a model call — the third and last level of
+ * the chain every brain reads (`BrainTimeoutConfig` field > per-call advisory `StreamOptions.stallTimeouts`
+ * > these). The Runner supplies these same numbers as the advisory on every call, so a Brain supplied by
+ * the deployment (BYOM) is told what the engine would arm; a first-party brain arms them itself when
+ * neither a config field nor an advisory names the segment. A silent call is therefore always bounded by
+ * something finer than the hour-scale {@link BRAIN_CALL_GUARDRAIL_DEFAULT_MS} (a measured production
+ * frame once sat 680s with ZERO deltas) unless a deployment switched the watchdog for that segment off
+ * by name — an explicit `0` is the only spelling of OFF. The TCP + TLS connect has no row here: it is
+ * the transport's own clock (`transport.ts`), not a segment the engine can observe. 量纲:
+ *   - first-byte 300s: the `fetch()` call → response headers. A self-hosted gateway that runs its
+ *     prefill BEFORE writing headers is silent here for minutes and healthy; the 30s "connect" clock
+ *     this replaces cut that prefill and re-sent the same body ten times. 300s is the reference
+ *     implementation's window for a non-first-party route; the window grows with the request body
+ *     ({@link firstByteWindow}) and the one retry is widened ({@link FIRST_BYTE_RETRY_WINDOW_FACTOR}).
  *   - first-token 600s: bounds the headers→first-delta wait, NOT the model's thought (the first
- *     THINKING delta already counts as the first token, design/17 O5 — see
- *     {@link BrainTimeoutConfig.firstTokenTimeoutMs}), so a slow reasoner is safe. A minutes-scale
- *     bound would be FALSE for a real class of backend: a self-hosted server working through a long
- *     prefill emits nothing at all for 2–3 minutes, and cancelling it burns the prefill and re-sends
- *     a request that burns it again — a guardrail whose reason is false for healthy traffic is not a
- *     guardrail. 600s is the same order of magnitude as the reference implementation's own request
- *     timeout, and the shapes this bound exists for (a gateway that accepted the request and then
- *     died) are still caught, just later; the task's own hard abort remains the outer bound.
- *     HONEST CEILING (measured): this watchdog is not the only clock over a
- *     byte-silent stream, so 600s is the bound this engine ASKS FOR, not the silence a deployment is
- *     necessarily granted. On Node's own `fetch` — the default transport for both adapters, and the
- *     one a deployment gets by supplying no `fetchImpl` — undici destroys a body that has produced no
- *     bytes for 300s (`bodyTimeout`, default `300e3`), so byte-silence past 300s ends the attempt
- *     there and arrives as a read rejection reported `transport`. That report is CORRECT (the
- *     transport really did cut it) and the seat to change it exists: `fetchImpl` on both brain configs
- *     takes any `fetch`, so a deployment needing the full 600s passes one built on an undici
- *     `Agent`/`Dispatcher` with its own `bodyTimeout`. Named here so the next reader who measures ~300s
- *     of tolerance does not conclude this number is a lie.
- *     {@link import("../orchestration/workflow.js").WORKFLOW_AGENT_STALL_MS} is DERIVED from
- *     {@link STALL_CONNECT_MS} + this value, so the coarse agent-restart cannot sit UNDER a single
- *     silent provider call. Move this number and that one follows. It is a floor, not
- *     a guarantee of ordering — see that constant's own comment for the cases that still invert.
- *   - idle 90s: mid-stream silence after output started — a healthy stream emits steadily
- *     (comfortably above any provider keep-alive cadence).
+ *     THINKING delta already counts as the first token, design/17 O5), so a slow reasoner is safe. A
+ *     minutes-scale bound is FALSE for a self-hosted server working through a long prefill AFTER
+ *     headers: it emits nothing for 2–3 minutes while healthy, and cancelling it burns the prefill and
+ *     re-sends a request that burns it again. The default transport keeps NO clock over this segment
+ *     (the request carries `bodyTimeout: 0`), so this number is the bound actually granted.
+ *     {@link import("../orchestration/workflow.js").WORKFLOW_AGENT_STALL_MS} is DERIVED from the
+ *     first-byte lane at {@link STALL_FIRST_BYTE_MS} ({@link firstByteLaneKnobMs}) + this value, so the coarse agent-restart cannot sit UNDER a single
+ *     silent provider call (a floor, not a guarantee of ordering — see that constant's comment).
+ *   - idle 300s: mid-stream silence after output started — the reference implementation's idle floor
+ *     (a self-hosted server can stall for minutes between deltas while a server-side tool runs; a provider
+ *     keep-alive comment is not a delta and does not count).
  * ADVISORY: a brain whose construction-time {@link BrainTimeoutConfig} sets the corresponding field
  * keeps it (deployment sovereignty; see the `StreamOptions.stallTimeouts` priority chain).
  */
-export declare const STALL_CONNECT_MS = 30000;
+export declare const STALL_FIRST_BYTE_MS = 300000;
 export declare const STALL_FIRST_TOKEN_MS = 600000;
-export declare const STALL_IDLE_MS = 90000;
+export declare const STALL_IDLE_MS = 300000;
+/**
+ * The retired names of the header-wait bound, each with the name that replaced it: the construction key and
+ * the per-call advisory key. The type face no longer has them, but a type only refuses a LITERAL — a
+ * spread object (`{ ...timeouts }`) or a JS caller still delivers the key, and a knob that arrives and is
+ * then ignored is a deployment setting silently doing nothing. So their arrival is refused, naming the
+ * replacement: a tripwire, not a second spelling (nothing reads the value).
+ */
+export declare const RETIRED_TIMEOUT_KNOBS: {
+    readonly construction: {
+        readonly connectTimeoutMs: "firstByteTimeoutMs";
+    };
+    readonly advisory: {
+        readonly connectMs: "firstByteMs";
+    };
+};
+/** Refuse a retired timeout key present on `holder` (see {@link RETIRED_TIMEOUT_KNOBS}); `where` names the
+ *  object in the message (`"createOpenAIBrain config"`, `"StreamOptions.stallTimeouts"`). */
+export declare function refuseRetiredTimeoutKnobs(holder: object | undefined, level: keyof typeof RETIRED_TIMEOUT_KNOBS, where: string): void;
+/** The first-byte window grows with the request body: one second per this many bytes, rounded up (the
+ *  reference implementation's allowance) — a large context on a slow uplink is still UPLOADING when a
+ *  fixed window would call the gateway silent. */
+export declare const FIRST_BYTE_UPLOAD_BYTES_PER_SECOND = 32768;
+/** A first-byte stall is re-sent at most this many times, out of its OWN budget rather than
+ *  `maxRetries` (the reference implementation: "normally one retry, not the session budget"); the shared
+ *  ladder counts transport failures, and this is not one. */
+export declare const FIRST_BYTE_RETRY_BUDGET = 1;
+/** The retry's knob is the first times this — the reference implementation widens its retry to a second
+ *  knob's default (599s against a 300s first window); one knob here keeps that ratio instead. */
+export declare const FIRST_BYTE_RETRY_WINDOW_FACTOR = 2;
+/** The ONE resolution every watchdog knob reads: construction config (an explicit `0` is OFF) > per-call
+ *  advisory > the engine default. A bad number at either level is refused ({@link resolveStallTimeoutMs});
+ *  only an ABSENT value falls through. */
+export declare function resolveWatchdogMs(configured: number | undefined, advisory: number | undefined, engineDefault: number, knob: string): number;
+/** One armed first-byte window, with the two numbers its announcement quotes. */
+export interface FirstByteWindow {
+    /** The knob's value for THIS attempt (the configured value, widened on the retry). */
+    knobMs: number;
+    /** The upload allowance added for the request body, ms (0 for an empty body). */
+    allowanceMs: number;
+    /** What is actually armed: `knobMs + allowanceMs`, capped at {@link MAX_TIMER_DELAY_MS}. `0` = off. */
+    windowMs: number;
+}
+/** The first-byte window for one attempt; `retryIndex` = first-byte stalls already suffered (0 first),
+ *  each widening the knob by {@link FIRST_BYTE_RETRY_WINDOW_FACTOR}. A knob of `0` (OFF) stays off. */
+export declare function firstByteWindow(knobMs: number | undefined, bodyBytes: number, retryIndex: number): FirstByteWindow;
+/**
+ * The most a first-byte lane armed at `knobMs` waits on the gateway in total before it gives up: the probe
+ * window and every widened retry its budget allows ({@link FIRST_BYTE_RETRY_BUDGET},
+ * {@link FIRST_BYTE_RETRY_WINDOW_FACTOR}) — read off {@link firstByteWindow}, the same function that arms
+ * each attempt, so the sum cannot drift from what is armed. The knob part only: the upload allowance
+ * depends on the request body and the backoff between attempts is not a wait on the gateway, so the lane's
+ * real wall time is this plus both — a LOWER bound.
+ */
+export declare function firstByteLaneKnobMs(knobMs: number): number;
 export interface BrainTimeoutConfig {
-    /** Abort the request if `fetch` doesn't return response headers within this many ms. Retryable. */
-    connectTimeoutMs?: number;
+    /**
+     * `fetch()` call → response headers, ms: the window a gateway has to START answering (until 7.33.0 a
+     * knob named `connectTimeoutMs` bounded this wait; it is gone — the connect clock is the transport's). Absent ⇒
+     * {@link STALL_FIRST_BYTE_MS}; the armed window grows with the request body ({@link firstByteWindow});
+     * a stall earns ONE retry at a widened window out of its own budget, then fails naming this knob.
+     * Fires as a `stall` (this process cancelled its own request), never as a transport fault. `0` ⇒ off.
+     */
+    firstByteTimeoutMs?: number;
     /**
      * After the stream opens, cancel it if no content delta (text / thinking / tool input) arrives
      * within this many ms → `BrainError("network", "first-token timeout")`. For reasoning models the
      * **first thinking delta also counts** as the first token, so a long-thinking model isn't killed
-     * for being slow to its first *visible* word (design/17 O5).
+     * for being slow to its first *visible* word (design/17 O5). Absent ⇒ {@link STALL_FIRST_TOKEN_MS};
+     * `0` ⇒ off.
      */
     firstTokenTimeoutMs?: number;
     /**
@@ -84,18 +142,19 @@ export interface BrainTimeoutConfig {
      * After the first delta, re-armed on every delta; if the stream then goes silent for this many ms
      * (a gateway that hung mid-output) → `reader.cancel()` + `BrainError("network", "stream idle timeout")`.
      * Complements `firstTokenTimeoutMs`: that one tolerates a long *first* token (reasoning), this one
-     * catches a stall *after* output has started, where a healthy stream emits steadily. Default off.
+     * catches a stall *after* output has started, where a healthy stream emits steadily. Absent ⇒
+     * {@link STALL_IDLE_MS}; `0` ⇒ off.
      */
     idleTimeoutMs?: number;
 }
 /**
- * A per-fetch-attempt abort controller that fires on a connect timeout while still forwarding an
+ * A per-attempt abort controller that fires at the first-byte deadline while still forwarding an
  * outer (task) abort. The returned `signal` governs the **whole** request including the streamed body
- * — so once headers arrive, call `clearTimer()` (NOT `dispose()`) to stop the connect timer while
- * keeping the outer-abort link alive for the body read; call `dispose()` only when the request is
- * fully done or being discarded.
+ * — so once headers arrive, call `clearTimer()` (NOT `dispose()`) to stop the deadline while keeping
+ * the outer-abort link alive for the body read; call `dispose()` only when the request is fully done
+ * or being discarded.
  */
-export declare function createConnectController(connectTimeoutMs: number | undefined, outerSignal: AbortSignal | undefined): {
+export declare function createAttemptController(firstByteWindowMs: number | undefined, outerSignal: AbortSignal | undefined): {
     signal: AbortSignal;
     timedOut: () => boolean;
     clearTimer: () => void;
@@ -110,7 +169,7 @@ export declare function createConnectController(connectTimeoutMs: number | undef
  * Default ceiling on how long the ENGINE waits for a single brain call (ruled 2026-08-03: one hour).
  * Deliberately far above any legitimate call: this is a wedged-run backstop, not a latency policy —
  * a deployment that wants a tight per-call bound sets the fine tier above ({@link BrainTimeoutConfig},
- * or the advisory {@link STALL_CONNECT_MS} family the engine supplies by default). All of these clocks
+ * or the advisory {@link STALL_FIRST_BYTE_MS} family the engine supplies by default). All of these clocks
  * run in parallel with the task's own `limits.timeoutSec`; whichever expires first owns the run.
  */
 export declare const BRAIN_CALL_GUARDRAIL_DEFAULT_MS = 3600000;

package/dist/brain/timeout.js

@@ -14,10 +14,44 @@ export function resolveStallTimeoutMs(value, knob) {
     }
     return value;
 }
-export const STALL_CONNECT_MS = 30_000;
+export const STALL_FIRST_BYTE_MS = 300_000;
 export const STALL_FIRST_TOKEN_MS = 600_000;
-export const STALL_IDLE_MS = 90_000;
-export function createConnectController(connectTimeoutMs, outerSignal) {
+export const STALL_IDLE_MS = 300_000;
+export const RETIRED_TIMEOUT_KNOBS = {
+    construction: { connectTimeoutMs: "firstByteTimeoutMs" },
+    advisory: { connectMs: "firstByteMs" },
+};
+export function refuseRetiredTimeoutKnobs(holder, level, where) {
+    if (holder === undefined || holder === null)
+        return;
+    for (const [retired, replacement] of Object.entries(RETIRED_TIMEOUT_KNOBS[level])) {
+        if (!(retired in holder))
+            continue;
+        const e = new Error(`${where}: \`${retired}\` was removed in 7.33.0 and is refused rather than ignored — the fetch()→response-headers wait it bounded is \`${replacement}\` (0 = off); the TCP + TLS connect is the transport's own clock, tuned on the process dispatcher (setGlobalDispatcher(new Agent({ connect: { timeout } })))`);
+        e.code = "config.stall_timeout_retired";
+        throw e;
+    }
+}
+export const FIRST_BYTE_UPLOAD_BYTES_PER_SECOND = 32_768;
+export const FIRST_BYTE_RETRY_BUDGET = 1;
+export const FIRST_BYTE_RETRY_WINDOW_FACTOR = 2;
+export function resolveWatchdogMs(configured, advisory, engineDefault, knob) {
+    return resolveStallTimeoutMs(configured ?? advisory, knob) ?? engineDefault;
+}
+export function firstByteWindow(knobMs, bodyBytes, retryIndex) {
+    if (knobMs === undefined || knobMs <= 0)
+        return { knobMs: 0, allowanceMs: 0, windowMs: 0 };
+    const widened = knobMs * FIRST_BYTE_RETRY_WINDOW_FACTOR ** Math.max(0, retryIndex);
+    const allowanceMs = Math.ceil(Math.max(0, bodyBytes) / FIRST_BYTE_UPLOAD_BYTES_PER_SECOND) * 1000;
+    return { knobMs: widened, allowanceMs, windowMs: Math.min(widened + allowanceMs, MAX_TIMER_DELAY_MS) };
+}
+export function firstByteLaneKnobMs(knobMs) {
+    let total = 0;
+    for (let retryIndex = 0; retryIndex <= FIRST_BYTE_RETRY_BUDGET; retryIndex++)
+        total += firstByteWindow(knobMs, 0, retryIndex).knobMs;
+    return total;
+}
+export function createAttemptController(firstByteWindowMs, outerSignal) {
     const ac = new AbortController();
     let timedOut = false;
     const onAbort = () => ac.abort(outerSignal?.reason);
@@ -28,11 +62,11 @@ export function createConnectController(connectTimeoutMs, outerSignal) {
             outerSignal.addEventListener("abort", onAbort, { once: true });
     }
     let timer;
-    if (connectTimeoutMs && connectTimeoutMs > 0) {
+    if (firstByteWindowMs && firstByteWindowMs > 0) {
         timer = setTimeout(() => {
             timedOut = true;
             ac.abort();
-        }, connectTimeoutMs);
+        }, firstByteWindowMs);
     }
     const clearTimer = () => {
         if (timer)

package/dist/brain/transport.d.ts

@@ -0,0 +1,13 @@
+import { Dispatcher } from "undici";
+/**
+ * The one dispatcher every first-party brain hands its fetch: the sending members are the engine's
+ * ({@link SENDING_MEMBERS}); every other member — state, lifecycle, events — is the host's, read when
+ * accessed ({@link hostMember}), so nothing a fetch starts reading has to be added to a list here.
+ * Stateless; owns no sockets.
+ */
+export declare const ENGINE_DISPATCHER: Dispatcher;
+/** The `fetch` a brain sends its requests through: the caller's `fetchImpl` (else Node's `fetch`), each
+ *  request carrying {@link ENGINE_DISPATCHER} in its init. */
+export declare function resolveFetch(config: {
+    fetchImpl?: typeof fetch;
+}): typeof fetch;

package/dist/brain/transport.js

@@ -0,0 +1,62 @@
+import { Dispatcher, getGlobalDispatcher } from "undici";
+import UnwrapHandler from "undici/lib/handler/unwrap-handler.js";
+import WrapHandler from "undici/lib/handler/wrap-handler.js";
+function handlerApi(handler) {
+    return typeof handler.onRequestStart === "function" ? 2 : 1;
+}
+function inSlotApi(api, handler) {
+    return api === 1 ? UnwrapHandler.unwrap(handler) : WrapHandler.wrap(handler);
+}
+function slot(version) {
+    const held = Reflect.get(globalThis, Symbol.for(`undici.globalDispatcher.${String(version)}`));
+    return isDispatcher(held) ? held : undefined;
+}
+function isDispatcher(value) {
+    return typeof value === "object" && value !== null && typeof Reflect.get(value, "dispatch") === "function";
+}
+function hostDispatcher(callerApi) {
+    const own = callerApi === 2 ? slot(2) : undefined;
+    return own !== undefined ? { dispatcher: own, api: 2 } : { dispatcher: slot(1) ?? getGlobalDispatcher(), api: 1 };
+}
+function hostDispatchers() {
+    const out = [];
+    for (const d of [slot(2), slot(1), getGlobalDispatcher()])
+        if (d !== undefined && !out.includes(d))
+            out.push(d);
+    return out;
+}
+function hostMember(key) {
+    const hosts = hostDispatchers();
+    for (const host of hosts) {
+        const value = Reflect.get(host, key, host);
+        if (value)
+            return typeof value === "function" ? value.bind(host) : value;
+    }
+    const newest = hosts[0];
+    return newest === undefined ? undefined : Reflect.get(newest, key, newest);
+}
+const CALLER_API = Symbol("engine.callerDispatcherApi");
+class EngineDispatcher extends Dispatcher {
+    dispatch(options, handler) {
+        const { [CALLER_API]: callerApi, ...rest } = options;
+        const host = hostDispatcher(callerApi ?? handlerApi(handler));
+        return host.dispatcher.dispatch({ ...rest, headersTimeout: 0, bodyTimeout: 0 }, inSlotApi(host.api, handler));
+    }
+    compose(...interceptors) {
+        const composed = super.compose(...interceptors);
+        const chain = composed.dispatch;
+        const enter = (options, handler) => {
+            const stamped = { ...options, [CALLER_API]: options[CALLER_API] ?? handlerApi(handler) };
+            return chain(stamped, handler);
+        };
+        return new Proxy(composed, { get: (target, key, receiver) => (key === "dispatch" ? enter : Reflect.get(target, key, receiver)) });
+    }
+}
+const SENDING_MEMBERS = new Set(Reflect.ownKeys(Dispatcher.prototype).filter((key) => key !== "constructor" && key !== "close" && key !== "destroy"));
+export const ENGINE_DISPATCHER = new Proxy(new EngineDispatcher(), {
+    get: (engine, key, standIn) => (SENDING_MEMBERS.has(key) ? Reflect.get(engine, key, standIn) : hostMember(key)),
+});
+export function resolveFetch(config) {
+    const inner = config.fetchImpl ?? fetch;
+    return (input, init) => inner(input, { ...init, dispatcher: ENGINE_DISPATCHER });
+}

package/dist/core/runner/prepare-task.js

@@ -13,7 +13,7 @@ import { isValidReminderMark, mintReminderMark } from "../reminder-mint.js";
 import { refuseInvalidApproverPosture } from "../auto-mode-directive.js";
 import { emitTrace } from "../trace.js";
 import { reservedCollisions, reservedFor } from "../../brain/request-params.js";
-import { STALL_CONNECT_MS, STALL_FIRST_TOKEN_MS, STALL_IDLE_MS, withBrainCallGuardrail } from "../../brain/timeout.js";
+import { STALL_FIRST_BYTE_MS, STALL_FIRST_TOKEN_MS, STALL_IDLE_MS, withBrainCallGuardrail } from "../../brain/timeout.js";
 import { OFFLOAD_TOOL_NAME } from "../tool-result-store.js";
 import { OUTPUT_TOOL_NAME, createOutputTool } from "./synthetic-tools.js";
 import { compileOutputSchema } from "./strict-output-schema.js";
@@ -649,7 +649,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 : {}),
             stallTimeoutsPerCall: () => {
                 callIssuedAtRef.current = Date.now();
-                return { connectMs: STALL_CONNECT_MS, firstTokenMs: STALL_FIRST_TOKEN_MS, idleMs: STALL_IDLE_MS };
+                return { firstByteMs: STALL_FIRST_BYTE_MS, firstTokenMs: STALL_FIRST_TOKEN_MS, idleMs: STALL_IDLE_MS };
             },
             ...(spec.resilience !== undefined ? { resilience: spec.resilience } : {}),
             loopTrace: (step) => {

package/dist/core/task-event.d.ts

@@ -141,12 +141,14 @@ export interface BrainStatus {
      * approximate across a clock adjustment — {@link retryInMs} stays the authoritative RELATIVE quantity.
      */
     retryAtMs?: number;
-    /** On a `waiting_first_token` frame: how long the first token has been awaited, ms, at the
-     *  moment the frame is emitted (the emitting process's clock; approximate across a hop). Absent on
-     *  every other phase. */
+    /** On a `waiting_first_token` frame: how long the current wait has lasted, ms, at the moment the
+     *  frame is emitted (the emitting process's clock; approximate across a hop). The wait is one
+     *  segment's: the response-header wait before headers arrive, the first-token wait after — each
+     *  starts its own count. Absent on every other phase. */
     elapsedMs?: number;
-    /** On a `waiting_first_token` frame: the armed first-token watchdog, ms — the wait's ceiling,
-     *  so a consumer can render "45s of 120s". Absent on every other phase. */
+    /** On a `waiting_first_token` frame: the ceiling of the segment being waited on, ms — the armed
+     *  first-byte window before headers, the armed first-token watchdog after — so a consumer can render
+     *  "45s of 300s". Absent on every other phase. */
     timeoutMs?: number;
     /** 1-based index of the attempt that just failed (the wait precedes attempt `attempt + 1`);
      *  same numbering as the `brain.retry` telemetry frame. Absent on frames that are not a retry wait. */

package/dist/core/task-registry.d.ts

@@ -386,8 +386,7 @@ export declare class TaskRegistry {
     /** Background output-file read exemption: true iff `canonicalPath` is EXACTLY the registered output
      *  file of a background bash row that (a) the caller can access (same owner/scope/session visibility as
      *  a TaskOutput poll — {@link canAccess}) and (b) was registered on the caller's OWN execution env —
-     *  `env` identity is part of the match, same discipline as {@link retainedShellIds} /
-     *  {@link runningShellIds}. A canonical path only names a file within ONE env's filesystem
+     *  `env` identity is part of the match, same discipline as {@link runningShellIds}. A canonical path only names a file within ONE env's filesystem
      *  namespace: on a shared registry, a row minted on env A must never exempt a same-named outside-root
      *  file in env B's namespace (same session or not), so instance equality — never a string proxy — is
      *  required. The output file is minted by the ENGINE itself (createTempFile
@@ -610,11 +609,6 @@ export declare class TaskRegistry {
      *  completion notification at the terminal state. `unref()`d — a watcher never keeps the process alive.
      *  Stops itself on terminal, on a vanished shell (env disposed), or when the handle is evicted. */
     private startBashWatcher;
-    /** RETAINED shells (THE retain predicate) still running on THIS env, any owner. Env identity is part of the
-     *  match (a shared registry never exempts another env's ids). No caller in src since the park-only parks
-     *  moved to the run-boundary dispose (which spares every running row: {@link runningShellIds}); removal
-     *  scheduled for the next minor. */
-    retainedShellIds(env: unknown): BackgroundShellId[];
     /** Every shell-lane row still RUNNING on this env, any owner — the run-boundary dispose's except-list (the
      *  run teardown and the park-only parks: `sweepRunBoundaryBackgroundShells`).
      *  A run's teardown disposes only shells it can attribute to itself: its settle sweep has already killed

package/dist/core/task-registry.js

@@ -835,15 +835,6 @@ export class TaskRegistry {
         handle.watcher = setInterval(() => void tick(), 1_000);
         handle.watcher.unref?.();
     }
-    retainedShellIds(env) {
-        const out = [];
-        for (const handle of this.handles.values()) {
-            if ((handle.type === "background_bash" || handle.type === "monitor") && handle.status === "running" && shellRowRetained(handle) && handle.env === env) {
-                out.push(handle.shellId);
-            }
-        }
-        return out;
-    }
     runningShellIds(env) {
         const out = [];
         for (const handle of this.handles.values()) {

package/dist/engine/llm/types.d.ts

@@ -39,12 +39,12 @@ export interface ResilienceOptions {
      *  exists to protect the provider; circumvention only where true failure shape matters (benchmarks). */
     bypassBreaker?: boolean;
 }
-/** 1.296 件A — per-call advisory stall-watchdog values (see {@link StreamOptions.stallTimeouts}). */
+/** 1.296 件A — per-call advisory stall-watchdog values (see {@link StreamOptions.stallTimeouts}); the
+ *  connect clock is the transport's, fixed at brain construction, so it is not among them. */
 export interface StallTimeouts {
-    /** Advisory connect watchdog (ms) — bounds the fetch→response-headers wait (件1a: a gateway that
-     *  never returns headers is invisible to every post-headers watchdog, including the absolute
-     *  deadline timer). Fires as the brain's existing retryable `network` connect timeout. */
-    connectMs?: number;
+    /** Advisory first-byte watchdog (ms) — bounds the fetch→response-headers wait; fires as a retryable
+     *  `stall` out of its own small budget. */
+    firstByteMs?: number;
     /** Advisory first-token watchdog (ms) — first thinking delta counts as the first token. */
     firstTokenMs?: number;
     /** Advisory mid-stream idle watchdog (ms) — re-armed on every delta after the first. */

package/dist/orchestration/workflow.d.ts

@@ -588,8 +588,8 @@ export declare const MAX_WORKFLOW_ITEMS = 4096;
  * own. This watchdog does not re-send a model call — it aborts the attempt and restarts the whole agent
  * on a FRESH session, so tool effects from before the stall can be repeated. The engine, one layer down,
  * already answers a silent provider call the cheap way: it re-sends that ONE call. So the floor here is
- * what a single provider call may legitimately occupy while producing NOTHING — the connect wait plus the
- * first-token wait ({@link STALL_CONNECT_MS} + {@link STALL_FIRST_TOKEN_MS}). It was a hand-written
+ * what a single provider call may legitimately occupy while producing NOTHING — the whole first-byte lane at the default knob
+ * ({@link firstByteLaneKnobMs}) plus the first-token wait; a floor (upload allowance and backoff between attempts not counted). It was a hand-written
  * 180_000 and CC-same until the first-token bound rose to 600s past it (measured: the same silent call
  * then produced two agent runs on two sessions instead of one run with a re-sent call), which is the
  * systematic inversion a derived value cannot re-open: raise or lower the engine's bound and this follows.
@@ -599,8 +599,8 @@ export declare const MAX_WORKFLOW_ITEMS = 4096;
  * this timer starts before the Runner prepares the attempt (an execution-env factory, a hook, a store
  * read all run inside this window and outside the engine's), and the first-token timer only starts once
  * headers arrive — so the margin by which the inner deadline can land AFTER this one is preparation plus
- * the connect time actually spent, less the {@link STALL_CONNECT_MS} this window already budgets for it
- * (40s of preparation and instant headers puts the first inner deadline 10s past this timer). An engine retry does not re-arm this timer either, so two silent provider attempts
+ * the header wait actually spent, less the {@link STALL_FIRST_BYTE_MS} this window already budgets for it
+ * (instant headers and more than 300s of preparation put the first inner deadline past this timer). An engine retry does not re-arm this timer either, so two silent provider attempts
  * exceed it by construction. The derivation removes the case that was guaranteed to invert; it does not
  * make inversion impossible. A deployment that wants the old aggression passes `stallMs` explicitly, and
  * a deployment that wants a real guarantee must set it from its own preparation budget.

package/dist/orchestration/workflow.js

@@ -22,7 +22,7 @@ import { OUTPUT_TOOL_NAME } from "../core/runner/synthetic-tools.js";
 import { compileOutputSchema } from "../core/runner/strict-output-schema.js";
 import { WorkflowBudgetExceededError, WorkflowNestingError, WorkflowAgentBlockedError, WorkflowAgentParkedError, WorkflowAgentSchemaError, WorkflowAgentStalledError, WorkflowMaxAgentsError, WORKFLOW_SPAWN_BLOCKED_ERROR_CODE } from "./workflow-types.js";
 import { WorkflowScriptError } from "./workflow-meta.js";
-import { STALL_CONNECT_MS, STALL_FIRST_TOKEN_MS } from "../brain/timeout.js";
+import { firstByteLaneKnobMs, STALL_FIRST_BYTE_MS, STALL_FIRST_TOKEN_MS } from "../brain/timeout.js";
 import { asThrownError, isErrorLike, readMember, thrownIs, thrownName, thrownText } from "../core/thrown-value.js";
 export * from "./workflow-types.js";
 const MAX_TRANSCRIPT_CHARS = 4000;
@@ -310,7 +310,7 @@ function assertFanOutOptionsShape(v, position) {
             `Nothing was run.`);
     }
 }
-export const WORKFLOW_AGENT_STALL_MS = STALL_CONNECT_MS + STALL_FIRST_TOKEN_MS;
+export const WORKFLOW_AGENT_STALL_MS = firstByteLaneKnobMs(STALL_FIRST_BYTE_MS) + STALL_FIRST_TOKEN_MS;
 export const WORKFLOW_THROTTLE_SLOW_MS = 90_000;
 export const WORKFLOW_AGENT_MAX_RETRIES = 5;
 export const WORKFLOW_AGENT_THROTTLE_BACKOFF_MS = 45_000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.32.1",
+  "version": "7.33.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -44,7 +44,7 @@
     "wire-changes/"
   ],
   "engines": {
-    "node": ">=20.3.0"
+    "node": ">=20.18.1"
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.build.json --emitDeclarationOnly --removeComments false",
@@ -95,7 +95,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
-    "typebox": "1.1.39"
+    "typebox": "1.1.39",
+    "undici": "7.30.0"
   },
   "optionalDependencies": {
     "sharp": "^0.35.0"
@@ -107,6 +108,8 @@
     "pg-mem": "^3.0.14",
     "tsx": "4.19.2",
     "typescript": "5.7.2",
+    "undici6": "npm:undici@^6.29.0",
+    "undici8": "npm:undici@^8.11.2",
     "vitest": "^2.1.8"
   }
 }