@sema-agent/core 7.32.0 → 7.33.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 7.33.0 — 2026-09-26
+
+### Model-call timeouts re-cut by segment: the header wait gets its own `firstByteTimeoutMs`, and every request carries the engine's dispatcher with the transport's header/body clocks off (#1121 #1122; behaviour: a pre-headers stall is a `stall` with its own one-retry lane, not a `transport` failure re-sent ten times; every watchdog defaults ON; +1 optional key `BrainTimeoutConfig.firstByteTimeoutMs`; **`BrainTimeoutConfig.connectTimeoutMs` REMOVED**; `StallTimeouts.connectMs` → `firstByteMs` (type-face breaking, see below); `WORKFLOW_AGENT_STALL_MS` 630 s → 1 500 s (derived); +1 dependency `undici@7.30.0`; `engines.node` `>=20.18.1`) (@server @cli @client-core)
+
+- **Before.** Two shapes, both reported against a self-hosted gateway. (1) The knob named `connectTimeoutMs` (advisory 30 s) actually bounded the `fetch()` call → response headers. A gateway that runs its prefill BEFORE writing headers was cut at 30 s, the cut was announced as `errClass: "transport"` / "connection lost, reconnecting" (nothing about the link was observed — this process cancelled its own request), and the identical body was re-sent through the transient ladder up to `maxRetries` (10) times: ~8.5 minutes of burned prefill ending in "connect timeout after 30000ms". (2) `config.fetchImpl ?? fetch` handed the request to Node's global `fetch`, whose undici transport keeps a 300 s headers clock and a 300 s body-silence clock that nothing here set or named; they sat UNDER `firstTokenTimeoutMs` (600 s) and `idleTimeoutMs`, so a value above 300 s was never granted, the cut arrived as a read rejection reported `transport`, and raising the knob changed nothing, silently.
+- **Three engine clocks, one per segment the engine can see, one definition (`src/brain/timeout.ts`).** The TCP + TLS connect is the transport's own clock (undici's 10 s by default, tuned on the process dispatcher the host installs); it is not a knob here.
+
+  | segment | key (`BrainTimeoutConfig`, all optional) | default | enforced by | on expiry |
+  |---|---|---|---|---|
+  | `fetch()` call → response headers | `firstByteTimeoutMs` — **new** | `STALL_FIRST_BYTE_MS` 300 s, plus 1 s per 32 KiB of request body (rounded up); the one retry runs at 2× the knob | the engine (per-attempt abort controller) | `stall`: retry frame `first-byte watchdog fired after <window>ms (firstByteTimeoutMs[ <knob> + <n> upload allowance]), retrying`, `maxRetries: 1`; terminal `[network] first-byte timeout: no response headers within <w1>ms, then <w2>ms on the retry (firstByteTimeoutMs) — if a proxy or gateway holds responses until they complete, raise firstByteTimeoutMs to wait longer` |
+  | headers → first content delta | `firstTokenTimeoutMs` | `STALL_FIRST_TOKEN_MS` 600 s | the engine | unchanged (`first-token watchdog fired …`) |
+  | delta → delta | `idleTimeoutMs` | `STALL_IDLE_MS` **300 s** (was 90 s; the reference implementation's idle floor — ruled to follow) | the engine | unchanged (`stream idle watchdog fired …`) |
+
+- **One resolution chain for every knob** (`resolveWatchdogMs`): construction config (an explicit `0` is OFF) > per-call advisory `StreamOptions.stallTimeouts` (the Runner sends the same defaults on every call; a BYOM brain reads them as its hint) > the engine default constant. The old third level "both absent ⇒ off" is retired: a brain built with no timeout config and used outside the Runner used to have NO engine watchdog at all and rode on the transport's accidental 300 s. **Who is hurt.** A deployment that constructed a first-party brain with no timeout fields and relied on it having none: it now arms 300 / 600 / 300 s (first byte / first token / idle). The idle default is the reference implementation's 300 s floor (ruled to follow), so a call that carried no advisory keeps the same 300 s of tolerated mid-stream silence the transport's body clock used to give it — now as the engine's own watchdog with a `stall` announcement instead of a transport failure; an Anthropic `ping` is still not a content delta, so a server-side tool that keeps the stream silent past 300 s is cut and, with text already streamed, committed by tier A (unchanged bound, new announcer). The number is not changed here; it is in #1125's candidate material. **Compensation.** `0` on the field it wants off (deployment sovereignty, unchanged), or a larger `idleTimeoutMs`.
+- **The first-byte lane** has its OWN budget (`FIRST_BYTE_RETRY_BUDGET` = 1, independent of `maxRetries`, like the thinking-only tier's), widens the knob ×2 on the retry (`FIRST_BYTE_RETRY_WINDOW_FACTOR`), re-sends the same body exactly once, and never claims the link dropped. The retry frame and the operator telemetry read one mapping (`retryAnnouncement`), the same one the post-headers watchdogs already used — a phase has no dialect of its own. The **wait disclosure** (`waiting_first_token`, first frame at 30 s then every 30 s) now runs during the header wait too, reporting the first-byte window as `timeoutMs`; before, a 5-minute header hold showed nothing until the wrong "reconnecting".
+- **The transport seat** (`src/brain/transport.ts`, one `resolveFetch` for all three brains): every request goes to the caller's `fetchImpl` (else Node's global `fetch`) with ONE addition to its init — `ENGINE_DISPATCHER`, a transparent stand-in for the PROCESS's dispatcher that differs from it in one place: each request it dispatches carries `headersTimeout: 0, bodyTimeout: 0`. The sending members undici's Dispatcher base builds on `dispatch` (`request`, `compose`, …, read off the base class, not listed) stay the engine's, so a `fetchImpl` that composes interceptors over `init.dispatcher` still sends with the clocks off, keeps every interceptor and reaches its own fetch's slot; every other member (`isMockActive`, `close`, events, …) is read off the host's dispatcher when accessed — nothing is listed, so a host `MockAgent` sees the request body and intercepts as it does for the host's own requests. Which host dispatcher: the one the CALLING fetch would resolve on its own — undici keeps one process slot per Dispatcher-API version (`undici.globalDispatcher.1` for every undici ≤ 7 including Node's built-in fetch, `.2` for undici 8), and the handler the fetch passes says which (undici's own test: `onRequestStart` ⇒ v2); resolved per request. Proxies, CA trust, mTLS, mocks and the connect clock stay whatever the host installed with `setGlobalDispatcher`. Consequence: `firstTokenTimeoutMs` / `idleTimeoutMs` above 300 s are now actually granted, on Node's fetch and on any `fetchImpl` that forwards `init` to a fetch. On an undici 8 host a v1 caller (Node's built-in fetch) goes through undici 8's slot-1 translation, which forces HTTP/1.1 and leaves a `MockAgent`'s interceptors — for the host's own plain requests too; a `fetchImpl` that is undici 8's `fetch` reaches the real dispatcher (KL-1121h). **The slot is the API**: slot 1 (`…globalDispatcher.1`) is always handed a v1 handler and slot 2 a v2 one, through undici's own converters (`lib/handler/unwrap-handler.js` / `wrap-handler.js`), so a composed chain whose interceptor rewraps the handler to v2 (undici 7's `interceptors.retry()`) still reaches an undici 6 host in slot 1 (before this rule: `UND_ERR_INVALID_ARG invalid onError method` and a retry loop).
+- **`fetchImpl` contract.** It receives `init.dispatcher = ENGINE_DISPATCHER` beside the method / headers / body / signal it always received. A wrapper that forwards `init` to Node's `fetch` gets the seat for free; a fetch that ignores `init.dispatcher` (another HTTP stack, a fetch that rebuilds its init) keeps its own transport's clocks under the engine's — the engine cannot see or lift them (KL-1121a): with undici's defaults its 300 s header clock fires before the engine's first-byte window (≥ 301 s: 300 s + at least 1 s of upload allowance), so the one-retry first-byte lane is never reached — the cut is reported `transport`, re-sent through the shared ladder, and a dead gateway reaches the terminal after about 11 × 300 s. The engine's three watchdogs arm regardless; a first-byte cut still requires the fetch to honour `init.signal`.
+- **`connectTimeoutMs` removed — who is hurt / compensation.** The knob bounded the header wait, which is now `firstByteTimeoutMs`; the TCP + TLS connect it was named for is the transport's own clock, tuned on the process dispatcher (`setGlobalDispatcher(new Agent({ connect: { timeout } }))`) — the engine has no honest home for a connect number, so the key is gone rather than kept with a changed meaning or a silent no-op. A host passing it fails loudly at upgrade — a literal does not compile, and a spread (`{ ...timeouts }`) or a JS caller, which the compiler cannot see, is refused by the brain factory (`config.stall_timeout_retired`, naming `firstByteTimeoutMs`) rather than ignored — and moves the number to `firstByteTimeoutMs` (a host that wants the old 30 s header cut spells it `firstByteTimeoutMs: 30_000`). **@server** `MODEL_CONNECT_TIMEOUT_MS` fed this key through a spread (`src/brain.ts` `timeouts`) — that shape compiles, and `createBrain` throws at construction until the key is dropped; it maps to `firstByteTimeoutMs` now (the env's own doc, "连接超时 … 0=关", described the header wait), and `0` there still means off. **@cli / @client-core** the retry frame for a pre-headers cut now carries `errClass: "stall"` with a detail that names `firstByteTimeoutMs`; a renderer that special-cased "connection lost" for that case sees a stall.
+- **Hard breaking (type face).** ① `BrainTimeoutConfig.connectTimeoutMs` is removed: a literal passing it fails to compile; a spread or a JS caller passing it is refused at run time by all three brain factories (`config.stall_timeout_retired`, the message names `firstByteTimeoutMs`) — the key's presence is refused even with an `undefined` value; the header wait it bounded is `firstByteTimeoutMs`. ② `StallTimeouts.connectMs` is removed and `firstByteMs` added: a literal with `connectMs` fails to compile; a spread or a JS caller that still sends it gets the CALL refused (stop reason `error`, the message names `firstByteMs`, nothing sent); a reader sees `firstByteMs`. ③ `WORKFLOW_AGENT_STALL_MS` is now `firstByteLaneKnobMs(STALL_FIRST_BYTE_MS) + STALL_FIRST_TOKEN_MS` = 1 500 000 (was 630 000): the floor is what one call may legitimately spend producing nothing — the first-byte probe and every widened retry the lane's budget allows (`FIRST_BYTE_RETRY_BUDGET`, `FIRST_BYTE_RETRY_WINDOW_FACTOR`), then the first-token wait — so a workflow's per-agent progress watchdog waits longer before restarting a silent agent (the derivation's whole point: an outer, coarser clock must not fire before the engine's own; the body-dependent upload allowance and the backoff between attempts are not counted, so it is a lower bound). ④ `engines.node` rises from `>=20.3.0` to `>=20.18.1`, the floor `undici@7.30.0` states; Node 20.18.1 is on the same LTS line.
+- **Dependency decision — `undici@7.30.0` (exact) enters `dependencies`.** Node exposes neither its dispatcher classes nor `getGlobalDispatcher`; the npm package does, and it shares the process-wide dispatcher slot with Node's own `fetch` (the documented `setGlobalDispatcher` contract), which is what lets the engine forward to whatever the host installed. undici 6 would have kept `>=18.17` but is the previous major. Stated side effect of the import (KL-1121c): if slot 1 is still empty, undici writes its default `Agent` (the same defaults as Node's own) into both process slots — measured on Node 20.18.1 at import of the package entry (the host's plain `fetch` then uses it too); on Node 24 it depends on load order. Anchored on the reference implementation's shape: an independent first-byte window with its own knob and a one-retry cap, a request-body upload allowance, a widened retry, and the gateway hint — its default for a non-first-party route (300 s) is the default here.
+- **Unchanged here, stated.** A model call whose watchdog is `0` has no bound on that segment at all now (the transport's clocks are 0 too); under the Runner the hour-scale guardrail remains, and the calls outside it (compaction, side-query, memory consolidation, the classifier, prompt suggestions) are listed with their own bounds in `docs/TIMEOUTS.md`. The memory distiller's model call is not on the seat yet (#1127).
+- Pins: `test/backlog1121-model-timeouts.test.ts` (window arithmetic; the chain; the engine dispatcher forwarding to the process dispatcher with the clocks off — pure and on the real transport with a spied host `Agent`; the slot chosen by the handler's Dispatcher-API version — Node's built-in fetch and npm undici 7's fetch reach slot 1 past a v2-only dispatcher in slot 2, a v2 handler reaches slot 2; every other member read off the host while `compose` / `request` keep the clocks off; a host `MockAgent` with a string body matcher in either slot, net connect disabled and enabled, and end to end through a brain — matched, 0 real requests; `isMockActive` true against a real dispatcher delivers the body intact; the retired keys refused by all three factories and per call; a deadline between the transport's headers and `doFetch` returning taken as a stall; the `fetchImpl` init carrying the seat; three fake-gateway arms against a local HTTP server — headers held, headers never, first data held — plus a contrast arm with an undici body clock; the first-byte and idle defaults pinned at the call site; the header-wait disclosure and the truthful closing frame under fake timers). Re-pinned: `test/walltime-stall-watchdog.test.ts`, `test/resilience.test.ts`, `test/backlog682-stall-retry-announcement.test.ts`, `test/stream-options-forwarding.test.ts`, `test/brain-resilience-coverage.test.ts`. Wire sheet: `docs/wire-consumption/unreleased-1121.md`. The timeout table: `docs/TIMEOUTS.md`.
+
+### Type surface — `TaskRegistry.retainedShellIds` removed (#1120 follow-up; +0 wire keys)
+
+- **Removed (type surface).** `TaskRegistry.retainedShellIds(env)` is gone. Since 7.32.1 nothing in `src` calls it (the park-only parks share the run-boundary dispose, whose keep-list is `runningShellIds(env)`). No caller was found in the server / cli / client-core trees. Read `runningShellIds(env)` with `list(access)` rows' `retained` instead.
+
+## 7.32.1 — 2026-09-25
+
+### Fix — a park that does not pause the env no longer stops the session's background shells (#1120; behavior; +0 exports, +0 wire keys) (@cli @server)
+
+- **Before.** A durable park on a park-only target (a remote env with `capabilities.suspendable: false`, whose workspace persists on the target: a tool ask under `durableApproval`, a plan-review park, a resource-slice park) swept the env keeping only rows already retained. The run's teardown keeps every registered shell row still running on the env. One question, two rules: a session's `run_in_background` loop outlived every turn, yet was stopped the moment the run parked — for example while a plan-approval card was on screen — and its row read `running` until the next watcher poll, then `failed` (measured: the process was already gone at the checkpoint commit). A parked run also stopped the non-retained loops of other sessions sharing the same env.
+- **Now.** One function answers both boundaries: a declared retain lane (the env's or the task's) sweeps nothing; otherwise every registered shell row still running on the env is spared, any owner, and unregistered env shells are disposed. The run's teardown that follows the park still collects the run's own rows that end with it (a session-less direct mount's rows: stop source `parent` where the park's sweep used to mark `env_sweep`). A park that pauses the env (`suspendVM`) still disposes every background process first. The teardown's gate now reads the env's retain declaration too: for an env that honours its own declaration nothing changes (its dispose was already a no-op); an adapter that declares retain on its capability face but disposes anyway now keeps its unregistered shells at a run's end as well.
+- **Who needs it.** A host that declared `TaskSpec.retainBackgroundProcesses` on every turn only to keep a session's loop across an approval card, and any session waiting on a park-only approval.
+- **Who is hurt / compensation.** A deployment that relied on a park to stop a session's non-retained shells — none expected. The session terminal (`reapSessionBackground`) and the exit hard face (`killAllBackgroundShellsNow`) end them as before; a teardown on an isolated env destroyed with the run still spares nothing.
+- **Known limit.** A park-only park resumed in ANOTHER process: the session's loop still runs on the target, but the resuming process does not track it, and the resume's orphan notice lists it as stopped (KL-1120a, #1126; retained rows had this before).
+- Pins: `test/backlog1120-park-sweep-rule.test.ts` (three park lanes × task lane absent / declared on real processes, an unregistered shell as the negative control, a second session sharing the env, a failed park commit, a persistent Monitor, a same-process resume, the parking run's own run-scoped row, the env lane read by the engine's gate, five teardown controls). Contract: `docs/background-process-lifetime.md`. Wire sheet: `docs/wire-consumption/unreleased-1120.md`.
+
 ## 7.32.0 — 2026-09-25
 
 ### The ask names WHICH mandate it stands on — `AskRequest.mandate` + `PendingAction.tool_approval.mandate` + `CheckpointSummary.mandate` (#1092; additive; +3 exports `PERSISTED_RULE_MANDATES` / `PersistedRuleMandate` / `isPersistedRuleMandate`; +4 optional type keys (`AskRequest`, the `PermissionResult` ask arm, the park row, the summary); no checkpoint-version bump) (@cli @client-core @server)

package/dist/brain/anthropic.d.ts

@@ -9,7 +9,7 @@ export interface AnthropicBrainConfig extends StreamEngineConfig {
     version?: string;
     /** Extra headers merged into every request (e.g. `anthropic-beta`). */
     headers?: Record<string, string>;
-    /** Custom fetch (tests / proxies). Defaults to global fetch. */
+    /** Custom fetch (tests / proxies); absent ⇒ the engine's default transport — see `resolveFetch`. */
     fetchImpl?: typeof fetch;
     /** `max_tokens` when the call/model doesn't specify one (Anthropic requires it). Default 4096. */
     defaultMaxTokens?: number;

package/dist/brain/anthropic.js

@@ -10,6 +10,8 @@ import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap
 import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRoot, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { MIN_THINKING_TOKENS, budgetCapSkipsThinking, declaredEffortLevels, reasoningBudgetShare, reasoningRequestCarried, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
+import { refuseRetiredTimeoutKnobs } from "./timeout.js";
+import { resolveFetch } from "./transport.js";
 function thinkingBudget(maxTokens, share, fixed, hardCap = false) {
     const max = hardCap ? maxTokens : Math.max(maxTokens, MIN_THINKING_TOKENS * 2);
     const want = fixed ?? Math.floor(max * share);
@@ -225,7 +227,8 @@ function closeToolUseBlock(acc) {
 }
 export function createAnthropicBrain(config = {}) {
     assertServableRequestRoot(config.baseUrl, "config.baseUrl");
-    const doFetch = config.fetchImpl ?? fetch;
+    refuseRetiredTimeoutKnobs(config, "construction", "createAnthropicBrain config");
+    const doFetch = resolveFetch(config);
     const cacheBreakpoints = config.cacheBreakpoints !== false;
     const stream = (model, context, options) => {
         let thinkingRequested = false;

package/dist/brain/open-responses.d.ts

@@ -7,7 +7,8 @@ export interface OpenResponsesBrainConfig extends StreamEngineConfig {
     apiKey?: string;
     /** Extra headers merged into every request (auth + content-type are hard-locked after the merge). */
     headers?: Record<string, string>;
-    /** Inject a custom fetch (tests / proxies). Defaults to global fetch. */
+    /** Inject a custom fetch (tests / proxies); the default transport and the `fetchImpl` seat are
+     *  `resolveFetch` (transport.ts). */
     fetchImpl?: typeof fetch;
     /**
      * Replay prior assistant reasoning items back to the endpoint on the turns that carry tool calls

package/dist/brain/open-responses.js

@@ -9,6 +9,8 @@ import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap
 import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRoot, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
+import { refuseRetiredTimeoutKnobs } from "./timeout.js";
+import { resolveFetch } from "./transport.js";
 const DEGENERATE_POLL_CHARS = 64;
 const MALFORMED_SAMPLE_CHARS = 160;
 const MALFORMED_ARGS_CHARS = 200;
@@ -218,7 +220,8 @@ function mapTerminalStopReason(incompleteReason, hadToolCalls) {
 }
 export function createOpenResponsesBrain(config = {}) {
     assertServableRequestRoot(config.baseUrl, "config.baseUrl");
-    const doFetch = config.fetchImpl ?? fetch;
+    refuseRetiredTimeoutKnobs(config, "construction", "createOpenResponsesBrain config");
+    const doFetch = resolveFetch(config);
     const stream = (model, context, options) => {
         let sentMaxTokens;
         let sentMaxTokensLane = "unset";

package/dist/brain/openai.d.ts

@@ -7,7 +7,8 @@ export interface OpenAIBrainConfig extends StreamEngineConfig {
     apiKey?: string;
     /** Extra headers merged into every request. */
     headers?: Record<string, string>;
-    /** Inject a custom fetch (tests / proxies). Defaults to global fetch. */
+    /** Inject a custom fetch (tests / proxies). Absent ⇒ the engine's default transport; the contract for
+     *  both cases is `resolveFetch` (transport.ts). */
     fetchImpl?: typeof fetch;
     /**
      * For weaker models that emit tool calls as TEXT (`<tool_call>{...}</tool_call>` / fenced json)

package/dist/brain/openai.js

@@ -10,6 +10,8 @@ import { BrainError } from "./errors.js";
 import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRoot, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
+import { refuseRetiredTimeoutKnobs } from "./timeout.js";
+import { resolveFetch } from "./transport.js";
 function closeToolCallAccum(acc) {
     if (acc.closedTc)
         return acc.closedTc;
@@ -282,7 +284,8 @@ export function inferMaxTokensField(modelId) {
 }
 export function createOpenAIBrain(config = {}) {
     assertServableRequestRoot(config.baseUrl, "config.baseUrl");
-    const doFetch = config.fetchImpl ?? fetch;
+    refuseRetiredTimeoutKnobs(config, "construction", "createOpenAIBrain config");
+    const doFetch = resolveFetch(config);
     const stream = (model, context, options) => {
         let sentMaxTokens;
         let sentMaxTokensLane = "unset";

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

@@ -4,7 +4,7 @@ import { type BrainTimeoutConfig } from "./timeout.js";
  * Shared streaming engine for the OpenAI- and Anthropic-shaped brains (design/32, consolidation).
  *
  * It owns the **bug-prone machinery that was duplicated verbatim** across `openai.ts` and
- * `anthropic.ts` — the connect-timeout + retry loop, the three-tier timer logic (first-token + idle
+ * `anthropic.ts` — the first-byte window + retry loop, the three-tier timer logic (first-token + idle
  * watchdog) with their flag resets, the SSE read loop + line framing, the one-shot cleanup, and the
  * `.catch/.finally` error wrapping. Centralizing the timer logic is the point: the same first-token /
  * idle reset bug was fixed twice (1.38.2 / 1.40.2) precisely because this lived in two copies.
@@ -231,14 +231,15 @@ export declare function runStreamingBrain(args: {
     makeParser: (ctrl: StreamControls) => StreamParser;
     /**
      * 1.296 件A — per-call ADVISORY stall watchdogs (`StreamOptions.stallTimeouts`). Priority chain:
-     * brain construction-time config (`BrainTimeoutConfig.connectTimeoutMs`/`firstTokenTimeoutMs`/
-     * `idleTimeoutMs`) wins whenever PRESENT — including an explicit 0/negative, which means
-     * "deliberately disabled" — and only an ABSENT (undefined) field adopts the advisory value; both
-     * absent ⇒ off. `connectMs` bounds the fetch→response-headers wait: the engine's post-headers
-     * timers can't see a gateway that never returns headers.
+     * brain construction-time config (`BrainTimeoutConfig.firstByteTimeoutMs`/`firstTokenTimeoutMs`/
+     * `idleTimeoutMs`) wins whenever PRESENT — including an explicit 0, which means "deliberately
+     * disabled" — and only an ABSENT (undefined) field adopts the advisory value; both absent ⇒ the
+     * engine default constant for that segment (`timeout.ts`). `firstByteMs` bounds the
+     * fetch→response-headers wait: the engine's post-headers timers can't see a gateway that never
+     * returns headers. The connect clock is not per-call: it is the process dispatcher's (`transport.ts`).
      */
     stallTimeouts?: {
-        connectMs?: number;
+        firstByteMs?: number;
         firstTokenMs?: number;
         idleMs?: number;
     };

package/dist/brain/stream-engine.js

@@ -6,7 +6,7 @@ import { stripUrlCredentials } from "./route-adjudicator.js";
 import { classifyInputTooLong } from "./input-too-long.js";
 import { FAST_MAX_BACKOFF_MS, providerWaitHint, retryBackoffMs } from "./retry.js";
 import { bindBrainStatusEmitter, emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
-import { createConnectController, resolveStallTimeoutMs } from "./timeout.js";
+import { createAttemptController, FIRST_BYTE_RETRY_BUDGET, firstByteWindow, refuseRetiredTimeoutKnobs, resolveWatchdogMs, STALL_FIRST_BYTE_MS, STALL_FIRST_TOKEN_MS, STALL_IDLE_MS, } from "./timeout.js";
 import { readMember, thrownText } from "../core/thrown-value.js";
 import { redactSecrets } from "../core/untrusted-egress.js";
 const DEFAULT_MAX_RETRIES = 10;
@@ -250,10 +250,18 @@ async function sleepAnnouncingRetry(totalMs, signal, frame) {
             return;
     }
 }
-function midstreamRetryAnnouncement(failure) {
-    return failure.kind === "stalled"
-        ? { errClass: "stall", detail: `${failure.watchdog} watchdog fired after ${failure.timeoutMs}ms (${failure.knob}), retrying` }
-        : { errClass: "transport", detail: "connection lost, reconnecting" };
+function retryAnnouncement(failure) {
+    if (failure.kind !== "stalled")
+        return { errClass: "transport", detail: "connection lost, reconnecting" };
+    const knob = failure.allowanceMs !== undefined && failure.allowanceMs > 0
+        ? `${failure.knob} ${failure.timeoutMs - failure.allowanceMs} + ${failure.allowanceMs} upload allowance`
+        : failure.knob;
+    return { errClass: "stall", detail: `${failure.watchdog} watchdog fired after ${failure.timeoutMs}ms (${knob}), retrying` };
+}
+function firstByteTimeoutMessage(windowsMs) {
+    const [first, ...retries] = windowsMs;
+    const waited = retries.length === 0 ? `within ${first ?? 0}ms` : `within ${first ?? 0}ms, then ${retries.map((w) => `${w}ms`).join(", then ")} on the retry`;
+    return `first-byte timeout: no response headers ${waited} (firstByteTimeoutMs) — if a proxy or gateway holds responses until they complete, raise firstByteTimeoutMs to wait longer`;
 }
 export function runStreamingBrain(args) {
     const { model, doFetch, signal, config, httpLabel, buildRequest, makeParser, stallTimeouts } = args;
@@ -262,6 +270,7 @@ export function runStreamingBrain(args) {
     let announcedRetry = false;
     let announcedWait = false;
     let terminalWaitDetail = "first token arrived";
+    let firstTokenArrived = false;
     let terminalRetryPhase = "recovered";
     let terminalRetryDetail = "recovered after retrying";
     let requestIdSeen;
@@ -271,7 +280,13 @@ export function runStreamingBrain(args) {
         const aborted = signal?.aborted === true || isAbortError(err);
         terminalRetryPhase = "gave_up";
         terminalRetryDetail = aborted ? "cancelled while retrying" : "retries exhausted";
-        terminalWaitDetail = aborted ? "cancelled while waiting for the first token" : "the first-token wait ended in failure";
+        terminalWaitDetail = firstTokenArrived
+            ? aborted
+                ? "cancelled after the first token arrived"
+                : "the call failed after the first token arrived"
+            : aborted
+                ? "cancelled while waiting for the first token"
+                : "the first-token wait ended in failure";
         const errorMsg = emptyAssistant(model);
         errorMsg.stopReason = aborted ? "aborted" : "error";
         errorMsg.errorMessage = thrownText(err);
@@ -315,33 +330,83 @@ export function runStreamingBrain(args) {
         const baseDelay = config.retryDelayMs ?? 500;
         const deterministicConnectBudget = Math.min(resolveDeterministicConnectRetries(config.deterministicConnectRetries), maxRetries);
         const deterministicLaneActive = deterministicConnectBudget < maxRetries;
-        const firstTokenTimeoutMs = resolveStallTimeoutMs(config.firstTokenTimeoutMs ?? stallTimeouts?.firstTokenMs, "firstTokenTimeoutMs");
-        const idleTimeoutMs = resolveStallTimeoutMs(config.idleTimeoutMs ?? stallTimeouts?.idleMs, "idleTimeoutMs");
-        const connectTimeoutMs = resolveStallTimeoutMs(config.connectTimeoutMs ?? stallTimeouts?.connectMs, "connectTimeoutMs");
+        refuseRetiredTimeoutKnobs(stallTimeouts, "advisory", "StreamOptions.stallTimeouts");
+        const firstByteTimeoutMs = resolveWatchdogMs(config.firstByteTimeoutMs, stallTimeouts?.firstByteMs, STALL_FIRST_BYTE_MS, "firstByteTimeoutMs");
+        const firstTokenTimeoutMs = resolveWatchdogMs(config.firstTokenTimeoutMs, stallTimeouts?.firstTokenMs, STALL_FIRST_TOKEN_MS, "firstTokenTimeoutMs");
+        const idleTimeoutMs = resolveWatchdogMs(config.idleTimeoutMs, stallTimeouts?.idleMs, STALL_IDLE_MS, "idleTimeoutMs");
+        const armWaitDisclosure = (ceilingMs) => {
+            if (!(ceilingMs > WAITING_FIRST_TOKEN_AFTER_MS))
+                return { stop: () => undefined };
+            const startedAt = Date.now();
+            const emitWaitFrame = bindBrainStatusEmitter();
+            let timer;
+            let stopped = false;
+            const schedule = (delayMs) => {
+                timer = setTimeout(() => {
+                    timer = undefined;
+                    if (stopped || Date.now() - startedAt >= ceilingMs)
+                        return;
+                    announcedWait = true;
+                    emitWaitFrame({ phase: "waiting_first_token", detail: "waiting for the first token", elapsedMs: Date.now() - startedAt, timeoutMs: ceilingMs });
+                    schedule(WAITING_FIRST_TOKEN_EVERY_MS);
+                }, delayMs);
+            };
+            schedule(WAITING_FIRST_TOKEN_AFTER_MS);
+            return {
+                stop: () => {
+                    stopped = true;
+                    if (timer)
+                        clearTimeout(timer);
+                    timer = undefined;
+                },
+            };
+        };
         let attempt = 0;
         let thinkingRetries = 0;
+        let firstByteStalls = 0;
+        const firstByteWindowsWaited = [];
         let startEmitted = false;
         for (;;) {
             let res;
             let connect;
-            for (;; attempt++) {
+            for (;;) {
                 if (signal?.aborted) {
                     const e = new Error("aborted");
                     e.name = "AbortError";
                     throw e;
                 }
-                const cc = createConnectController(connectTimeoutMs, signal);
+                const window = firstByteWindow(firstByteTimeoutMs, Buffer.byteLength(req.body), firstByteStalls);
+                const cc = createAttemptController(window.windowMs, signal);
                 let r;
                 let netErr;
+                let firstByteStall;
                 requestIdSeen = undefined;
                 attemptPartial = undefined;
+                const headerWait = armWaitDisclosure(window.windowMs);
+                const stalledAtFirstByte = () => {
+                    firstByteWindowsWaited.push(window.windowMs);
+                    return {
+                        kind: "stalled",
+                        watchdog: "first-byte",
+                        knob: "firstByteTimeoutMs",
+                        timeoutMs: window.windowMs,
+                        allowanceMs: window.allowanceMs,
+                        err: new BrainError("network", firstByteTimeoutMessage(firstByteWindowsWaited), undefined, { apiError: true }),
+                    };
+                };
                 try {
                     r = await doFetch(req.url, { method: "POST", headers: req.headers, body: req.body, signal: cc.signal });
                     requestIdSeen = readProviderRequestId(r);
+                    if (cc.timedOut()) {
+                        discardResponseBody(r);
+                        r = undefined;
+                        requestIdSeen = undefined;
+                        firstByteStall = stalledAtFirstByte();
+                    }
                 }
                 catch (e) {
                     if (cc.timedOut()) {
-                        netErr = new Error(`connect timeout after ${connectTimeoutMs}ms`);
+                        firstByteStall = stalledAtFirstByte();
                     }
                     else if (isAbortError(e) || signal?.aborted) {
                         cc.dispose();
@@ -355,6 +420,9 @@ export function runStreamingBrain(args) {
                         netErr = e;
                     }
                 }
+                finally {
+                    headerWait.stop();
+                }
                 if (r && r.ok && r.body) {
                     cc.clearTimer();
                     connect = cc;
@@ -364,6 +432,27 @@ export function runStreamingBrain(args) {
                 }
                 cc.clearTimer();
                 try {
+                    if (firstByteStall !== undefined) {
+                        if (firstByteStalls >= FIRST_BYTE_RETRY_BUDGET)
+                            throw firstByteStall.err;
+                        firstByteStalls++;
+                        const announcement = retryAnnouncement(firstByteStall);
+                        const delayMs = retryBackoffMs(baseDelay, firstByteStalls - 1);
+                        emitBrainTelemetry({ kind: "retry", attempt: firstByteStalls, phase: "connect", errClass: announcement.errClass, nextDelayMs: delayMs });
+                        announcedRetry = true;
+                        cc.abort();
+                        cc.dispose();
+                        await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
+                            phase: "reconnecting",
+                            detail: announcement.detail,
+                            retryInSec: Math.ceil(remainingMs / 1000),
+                            retryInMs: remainingMs,
+                            attempt: firstByteStalls,
+                            maxRetries: FIRST_BYTE_RETRY_BUDGET,
+                            errClass: announcement.errClass,
+                        }));
+                        continue;
+                    }
                     let overflowBody;
                     let overflowDeclineNote = "";
                     if (r !== undefined && r.status === 400) {
@@ -402,6 +491,7 @@ export function runStreamingBrain(args) {
                                         errClass: "output_cap",
                                         ...(namesTheFailure(r?.status) ? { errorStatus: r.status } : {}),
                                     });
+                                    attempt++;
                                     continue;
                                 }
                                 overflowDeclineNote =
@@ -468,6 +558,7 @@ export function runStreamingBrain(args) {
                             errClass,
                             ...(retryStatus !== undefined ? { errorStatus: retryStatus } : {}),
                         }));
+                        attempt++;
                         continue;
                     }
                     if (netErr)
@@ -494,39 +585,14 @@ export function runStreamingBrain(args) {
             let firstTokenSeen = false;
             let firedFirstTokenDeadlineMs;
             let ftTimer;
-            let waitTimer;
-            const clearWaitTimer = () => {
-                if (waitTimer) {
-                    clearTimeout(waitTimer);
-                    waitTimer = undefined;
-                }
-            };
+            let firstTokenWait = { stop: () => undefined };
             if (firstTokenTimeoutMs && firstTokenTimeoutMs > 0) {
                 ftTimer = setTimeout(() => {
                     firedFirstTokenDeadlineMs = firstTokenTimeoutMs;
-                    clearWaitTimer();
+                    firstTokenWait.stop();
                     void reader.cancel().catch(() => undefined);
                 }, firstTokenTimeoutMs);
-                if (firstTokenTimeoutMs > WAITING_FIRST_TOKEN_AFTER_MS) {
-                    const waitStartedAt = Date.now();
-                    const emitWaitFrame = bindBrainStatusEmitter();
-                    const scheduleWaitFrame = (delayMs) => {
-                        waitTimer = setTimeout(() => {
-                            waitTimer = undefined;
-                            if (firstTokenSeen || firedFirstTokenDeadlineMs !== undefined || Date.now() - waitStartedAt >= firstTokenTimeoutMs)
-                                return;
-                            announcedWait = true;
-                            emitWaitFrame({
-                                phase: "waiting_first_token",
-                                detail: "waiting for the first token",
-                                elapsedMs: Date.now() - waitStartedAt,
-                                timeoutMs: firstTokenTimeoutMs,
-                            });
-                            scheduleWaitFrame(WAITING_FIRST_TOKEN_EVERY_MS);
-                        }, delayMs);
-                    };
-                    scheduleWaitFrame(WAITING_FIRST_TOKEN_AFTER_MS);
-                }
+                firstTokenWait = armWaitDisclosure(firstTokenTimeoutMs);
             }
             let firedIdleDeadlineMs;
             let idleTimer;
@@ -546,19 +612,20 @@ export function runStreamingBrain(args) {
                 if (firstTokenSeen)
                     return;
                 firstTokenSeen = true;
+                firstTokenArrived = true;
                 firedFirstTokenDeadlineMs = undefined;
                 if (ftTimer) {
                     clearTimeout(ftTimer);
                     ftTimer = undefined;
                 }
-                clearWaitTimer();
+                firstTokenWait.stop();
             };
             cleanup = () => {
                 if (ftTimer) {
                     clearTimeout(ftTimer);
                     ftTimer = undefined;
                 }
-                clearWaitTimer();
+                firstTokenWait.stop();
                 if (idleTimer) {
                     clearTimeout(idleTimer);
                     idleTimer = undefined;
@@ -631,7 +698,7 @@ export function runStreamingBrain(args) {
                 clearTimeout(ftTimer);
                 ftTimer = undefined;
             }
-            clearWaitTimer();
+            firstTokenWait.stop();
             if (idleTimer) {
                 clearTimeout(idleTimer);
                 idleTimer = undefined;
@@ -678,7 +745,7 @@ export function runStreamingBrain(args) {
                 throw failure.err;
             cleanup?.();
             cleanup = undefined;
-            const announcement = midstreamRetryAnnouncement(failure);
+            const announcement = retryAnnouncement(failure);
             if (snap.hasOnlyThinking) {
                 if (thinkingRetries >= THINKING_RETRY_BUDGET)
                     throw failure.err;