@codespar/sdk 0.10.11 → 0.12.0

package/dist/session.js

@@ -1,23 +1,35 @@
 /**
  * Session implementation for the CodeSpar managed runtime.
  */
-import { networkErrorToApiError, throwFromResponse } from "./errors.js";
-// Wraps `fetch` so network rejections become CodesparApiError
-// (status: 0) at the very edge of the SDK, rather than bubbling
-// raw TypeError / DOMException up to the caller. Every transport
-// site in this file goes through here.
-async function safeFetch(input, init, what) {
+import { CodesparApiError, networkErrorToApiError, throwFromResponse, TimeoutError } from "./errors.js";
+import { fetchWithTimeout, validateTimeout } from "./internal/fetch.js";
+import { mergeSignals } from "./internal/abort.js";
+// Every unary transport site funnels through here. The `consume`
+// callback reads the body inside the timeout/abort budget (via
+// fetchWithTimeout), so a backend that stalls the body still hits the
+// deadline. Network rejections become CodesparApiError (status: 0);
+// typed timeouts and caller aborts propagate verbatim; structured API
+// errors raised inside `consume` (throwFromResponse) pass through
+// unwrapped. Streaming sites use raw fetch (SSE idle-timeout lives at
+// the stream layer), not this helper.
+async function safeFetch(input, init, what, timeoutOpts, consume) {
     try {
-        return await fetch(input, init);
+        return await fetchWithTimeout(input, init, timeoutOpts, consume);
     }
     catch (cause) {
+        if (cause instanceof TimeoutError)
+            throw cause;
+        if (cause instanceof CodesparApiError)
+            throw cause;
+        if (timeoutOpts.signal?.aborted)
+            throw cause;
         throw networkErrorToApiError(cause, what);
     }
 }
 // The concrete session object satisfies the Session interface and carries extra
 // internal methods (tools, findTools) that the free functions in tools.ts access
 // via duck-typing. They are intentionally not declared on the Session interface.
-export async function createSession(userId, config, deps) {
+export async function createSession(userId, config, deps, createOpts) {
     const { baseUrl, apiKey } = deps;
     const projectId = config.projectId ?? deps.projectId;
     const headers = {
@@ -31,6 +43,12 @@ export async function createSession(userId, config, deps) {
         metadata: config.metadata,
         projectId: config.projectId ?? deps.projectId,
     };
+    // Resolve per-call timeout/abort against the client default. Kept local
+    // so every method funnels through one place if CallOptions grows.
+    const callOpts = (o) => ({
+        timeout: o?.timeout ?? deps.timeout,
+        signal: o?.signal,
+    });
     // Conditional spread keeps the wire body byte-identical to the
     // pre-PRD shape when the caller omits mocks (R18 wire-neutrality).
     // The field is forwarded verbatim — no canonical-name rewriting on
@@ -42,15 +60,15 @@ export async function createSession(userId, config, deps) {
         user_id: userId,
         ...(config.mocks !== undefined ? { mocks: config.mocks } : {}),
     };
-    const res = await safeFetch(`${baseUrl}/v1/sessions`, {
+    const data = await safeFetch(`${baseUrl}/v1/sessions`, {
         method: "POST",
         headers,
         body: JSON.stringify(wireBody),
-    }, "createSession");
-    if (!res.ok) {
-        await throwFromResponse(res, "createSession");
-    }
-    const data = (await res.json());
+    }, "createSession", callOpts(createOpts), async (res) => {
+        if (!res.ok)
+            await throwFromResponse(res, "createSession");
+        return (await res.json());
+    });
     let cachedTools = null;
     let cachedConnections = null;
     const session = {
@@ -80,29 +98,29 @@ export async function createSession(userId, config, deps) {
             return all.filter((t) => t.name.toLowerCase().includes(q) ||
                 t.description.toLowerCase().includes(q));
         },
-        async execute(toolName, params) {
+        async execute(toolName, params, opts) {
             const start = Date.now();
-            const r = await safeFetch(`${baseUrl}/v1/sessions/${data.id}/execute`, {
+            return await safeFetch(`${baseUrl}/v1/sessions/${data.id}/execute`, {
                 method: "POST",
                 headers,
                 body: JSON.stringify({ tool: toolName, input: params }),
-            }, "execute");
-            if (!r.ok) {
-                const body = await r.text();
-                return {
-                    success: false,
-                    data: null,
-                    error: `${r.status}: ${body}`,
-                    duration: Date.now() - start,
-                    server: "",
-                    tool: toolName,
-                };
-            }
-            const result = (await r.json());
-            return result;
+            }, "execute", callOpts(opts), async (r) => {
+                if (!r.ok) {
+                    const body = await r.text();
+                    return {
+                        success: false,
+                        data: null,
+                        error: `${r.status}: ${body}`,
+                        duration: Date.now() - start,
+                        server: "",
+                        tool: toolName,
+                    };
+                }
+                return (await r.json());
+            });
         },
-        async proxyExecute(request) {
-            const r = await safeFetch(`${baseUrl}/v1/sessions/${data.id}/proxy_execute`, {
+        async proxyExecute(request, opts) {
+            return await safeFetch(`${baseUrl}/v1/sessions/${data.id}/proxy_execute`, {
                 method: "POST",
                 headers,
                 body: JSON.stringify({
@@ -113,45 +131,72 @@ export async function createSession(userId, config, deps) {
                     params: request.params,
                     headers: request.headers,
                 }),
-            }, "proxyExecute");
-            if (!r.ok) {
-                await throwFromResponse(r, "proxyExecute");
-            }
-            return (await r.json());
+            }, "proxyExecute", callOpts(opts), async (r) => {
+                if (!r.ok)
+                    await throwFromResponse(r, "proxyExecute");
+                return (await r.json());
+            });
         },
-        async send(message) {
-            const r = await safeFetch(`${baseUrl}/v1/sessions/${data.id}/send`, {
+        async send(message, opts) {
+            return await safeFetch(`${baseUrl}/v1/sessions/${data.id}/send`, {
                 method: "POST",
                 headers: { ...headers, Accept: "application/json" },
                 body: JSON.stringify({ message }),
-            }, "send");
-            if (!r.ok) {
-                await throwFromResponse(r, "send");
-            }
-            return (await r.json());
+            }, "send", callOpts(opts), async (r) => {
+                if (!r.ok)
+                    await throwFromResponse(r, "send");
+                return (await r.json());
+            });
         },
-        async *sendStream(message) {
-            const r = await safeFetch(`${baseUrl}/v1/sessions/${data.id}/send`, {
-                method: "POST",
-                headers: { ...headers, Accept: "text/event-stream" },
-                body: JSON.stringify({ message }),
-            }, "sendStream");
-            if (!r.ok || !r.body) {
-                await throwFromResponse(r, "sendStream");
+        async *sendStream(message, opts) {
+            const ms = opts?.timeout ?? deps.timeout;
+            validateTimeout(ms);
+            const idleAc = new AbortController();
+            const merged = mergeSignals([idleAc.signal, opts?.signal]);
+            const idle = makeIdle(idleAc, ms);
+            try {
+                // Arm the timeout before the fetch so the connect/headers phase
+                // is covered too — not just post-body idle. Otherwise a backend
+                // that accepts the socket but never sends headers hangs forever.
+                idle.reset();
+                const r = await fetch(`${baseUrl}/v1/sessions/${data.id}/send`, {
+                    method: "POST",
+                    headers: { ...headers, Accept: "text/event-stream" },
+                    body: JSON.stringify({ message }),
+                    signal: merged.signal,
+                });
+                if (!r.ok || !r.body) {
+                    await throwFromResponse(r, "sendStream");
+                }
+                // r.body is non-null here — throwFromResponse always throws.
+                yield* parseSseStream(r.body, idle, merged.signal);
+            }
+            catch (err) {
+                if (opts?.signal?.aborted)
+                    throw opts.signal.reason;
+                if (idleAc.signal.aborted)
+                    throw new TimeoutError(ms);
+                // Structured API errors propagate; only raw transport rejections
+                // collapse to CodesparApiError(status: 0), matching safeFetch.
+                if (err instanceof CodesparApiError)
+                    throw err;
+                throw networkErrorToApiError(err, "sendStream");
+            }
+            finally {
+                idle.pause();
+                merged.cleanup();
             }
-            // Once we're past the !r.ok branch, r.body is guaranteed non-null.
-            yield* parseSseStream(r.body);
         },
         /**
          * codespar_discover wrapper. Same wire as
          * `execute("codespar_discover", {...})` but returns a typed
          * DiscoverResult so the caller doesn't have to cast.
          */
-        async discover(useCase, options) {
+        async discover(useCase, options, opts) {
             const result = await session.execute("codespar_discover", {
                 use_case: useCase,
                 ...(options ?? {}),
-            });
+            }, opts);
             if (!result.success) {
                 throw new Error(`discover failed: ${result.error ?? "unknown"}`);
             }
@@ -165,8 +210,8 @@ export async function createSession(userId, config, deps) {
          * when no server_id is given, "status" otherwise (matching the
          * backend default).
          */
-        async connectionWizard(options) {
-            const result = await session.execute("codespar_manage_connections", options);
+        async connectionWizard(options, opts) {
+            const result = await session.execute("codespar_manage_connections", options, opts);
             if (!result.success) {
                 throw new Error(`connectionWizard failed: ${result.error ?? "unknown"}`);
             }
@@ -179,8 +224,8 @@ export async function createSession(userId, config, deps) {
          * ToolResult.data. Distinct from the legacy `codespar_pay` rail
          * (which routes to outbound transfers/payouts).
          */
-        async charge(args) {
-            const result = await session.execute("codespar_charge", args);
+        async charge(args, opts) {
+            const result = await session.execute("codespar_charge", args, opts);
             if (!result.success) {
                 throw new Error(`charge failed: ${result.error ?? "unknown"}`);
             }
@@ -193,8 +238,8 @@ export async function createSession(userId, config, deps) {
          * ShipResult so the caller doesn't have to cast through
          * ToolResult.data.
          */
-        async ship(args) {
-            const result = await session.execute("codespar_ship", args);
+        async ship(args, opts) {
+            const result = await session.execute("codespar_ship", args, opts);
             if (!result.success) {
                 throw new Error(`ship failed: ${result.error ?? "unknown"}`);
             }
@@ -208,8 +253,8 @@ export async function createSession(userId, config, deps) {
          * LedgerResult so the caller doesn't have to cast through
          * ToolResult.data.
          */
-        async ledger(args) {
-            const result = await session.execute("codespar_ledger", args);
+        async ledger(args, opts) {
+            const result = await session.execute("codespar_ledger", args, opts);
             if (!result.success) {
                 throw new Error(`ledger failed: ${result.error ?? "unknown"}`);
             }
@@ -221,8 +266,8 @@ export async function createSession(userId, config, deps) {
          * Pomelo card-issuing program. Same wire as
          * `execute("codespar_issue", {...})` but returns a typed IssueResult.
          */
-        async issue(args) {
-            const result = await session.execute("codespar_issue", args);
+        async issue(args, opts) {
+            const result = await session.execute("codespar_issue", args, opts);
             if (!result.success) {
                 throw new Error(`issue failed: ${result.error ?? "unknown"}`);
             }
@@ -241,81 +286,123 @@ export async function createSession(userId, config, deps) {
          * (a registered implementation behind the contract); a self-hosted
          * OSS runtime with none returns "Tool not registered".
          */
-        async shop(args) {
-            const result = await session.execute("codespar_shop", args);
+        async shop(args, opts) {
+            const result = await session.execute("codespar_shop", args, opts);
             if (!result.success) {
                 throw new Error(`shop failed: ${result.error ?? "unknown"}`);
             }
             return result.data;
         },
-        async paymentStatus(toolCallId) {
-            const r = await safeFetch(`${baseUrl}/v1/tool-calls/${encodeURIComponent(toolCallId)}/payment-status`, { headers }, "paymentStatus");
-            if (!r.ok) {
-                await throwFromResponse(r, "paymentStatus");
-            }
-            return (await r.json());
+        async paymentStatus(toolCallId, opts) {
+            return await safeFetch(`${baseUrl}/v1/tool-calls/${encodeURIComponent(toolCallId)}/payment-status`, { headers }, "paymentStatus", callOpts(opts), async (r) => {
+                if (!r.ok)
+                    await throwFromResponse(r, "paymentStatus");
+                return (await r.json());
+            });
         },
-        async verificationStatus(toolCallId) {
-            const r = await safeFetch(`${baseUrl}/v1/tool-calls/${encodeURIComponent(toolCallId)}/verification-status`, { headers }, "verificationStatus");
-            if (!r.ok) {
-                await throwFromResponse(r, "verificationStatus");
-            }
-            return (await r.json());
+        async verificationStatus(toolCallId, opts) {
+            return await safeFetch(`${baseUrl}/v1/tool-calls/${encodeURIComponent(toolCallId)}/verification-status`, { headers }, "verificationStatus", callOpts(opts), async (r) => {
+                if (!r.ok)
+                    await throwFromResponse(r, "verificationStatus");
+                return (await r.json());
+            });
         },
         async paymentStatusStream(toolCallId, options = {}) {
-            const url = `${baseUrl}/v1/tool-calls/${encodeURIComponent(toolCallId)}/payment-status/stream`;
-            const r = await safeFetch(url, {
-                headers: { ...headers, Accept: "text/event-stream" },
-                signal: options.signal,
-            }, "paymentStatusStream");
-            if (!r.ok || !r.body) {
-                await throwFromResponse(r, "paymentStatusStream");
-                // unreachable — throwFromResponse always throws
-                throw new Error("unreachable");
-            }
-            let last = null;
-            for await (const frame of parseStatusSseStream(r.body)) {
-                if (frame.event === "snapshot" || frame.event === "update") {
-                    last = frame.data;
-                    options.onUpdate?.(last);
+            const ms = options.timeout ?? deps.timeout;
+            validateTimeout(ms);
+            const idleAc = new AbortController();
+            const merged = mergeSignals([idleAc.signal, options.signal]);
+            const idle = makeIdle(idleAc, ms);
+            try {
+                // Arm the timeout before the fetch so connect/headers are covered.
+                idle.reset();
+                const url = `${baseUrl}/v1/tool-calls/${encodeURIComponent(toolCallId)}/payment-status/stream`;
+                const r = await fetch(url, {
+                    headers: { ...headers, Accept: "text/event-stream" },
+                    signal: merged.signal,
+                });
+                if (!r.ok || !r.body) {
+                    await throwFromResponse(r, "paymentStatusStream");
+                }
+                let last = null;
+                // r.body is non-null here — throwFromResponse always throws.
+                for await (const frame of parseStatusSseStream(r.body, idle, merged.signal)) {
+                    if (frame.event === "snapshot" || frame.event === "update") {
+                        last = frame.data;
+                        options.onUpdate?.(last);
+                    }
+                    else if (frame.event === "done") {
+                        break;
+                    }
                 }
-                else if (frame.event === "done") {
-                    break;
+                if (!last) {
+                    throw new Error("paymentStatusStream: stream closed before snapshot");
                 }
+                return last;
             }
-            if (!last) {
-                throw new Error("paymentStatusStream: stream closed before snapshot");
+            catch (err) {
+                if (options.signal?.aborted)
+                    throw options.signal.reason;
+                if (idleAc.signal.aborted)
+                    throw new TimeoutError(ms);
+                if (err instanceof CodesparApiError)
+                    throw err;
+                throw networkErrorToApiError(err, "paymentStatusStream");
+            }
+            finally {
+                idle.pause();
+                merged.cleanup();
             }
-            return last;
         },
         async verificationStatusStream(toolCallId, options = {}) {
-            const url = `${baseUrl}/v1/tool-calls/${encodeURIComponent(toolCallId)}/verification-status/stream`;
-            const r = await safeFetch(url, {
-                headers: { ...headers, Accept: "text/event-stream" },
-                signal: options.signal,
-            }, "verificationStatusStream");
-            if (!r.ok || !r.body) {
-                await throwFromResponse(r, "verificationStatusStream");
-                // unreachable — throwFromResponse always throws
-                throw new Error("unreachable");
-            }
-            let last = null;
-            for await (const frame of parseStatusSseStream(r.body)) {
-                if (frame.event === "snapshot" || frame.event === "update") {
-                    last = frame.data;
-                    options.onUpdate?.(last);
+            const ms = options.timeout ?? deps.timeout;
+            validateTimeout(ms);
+            const idleAc = new AbortController();
+            const merged = mergeSignals([idleAc.signal, options.signal]);
+            const idle = makeIdle(idleAc, ms);
+            try {
+                // Arm the timeout before the fetch so connect/headers are covered.
+                idle.reset();
+                const url = `${baseUrl}/v1/tool-calls/${encodeURIComponent(toolCallId)}/verification-status/stream`;
+                const r = await fetch(url, {
+                    headers: { ...headers, Accept: "text/event-stream" },
+                    signal: merged.signal,
+                });
+                if (!r.ok || !r.body) {
+                    await throwFromResponse(r, "verificationStatusStream");
+                }
+                let last = null;
+                // r.body is non-null here — throwFromResponse always throws.
+                for await (const frame of parseStatusSseStream(r.body, idle, merged.signal)) {
+                    if (frame.event === "snapshot" || frame.event === "update") {
+                        last = frame.data;
+                        options.onUpdate?.(last);
+                    }
+                    else if (frame.event === "done") {
+                        break;
+                    }
                 }
-                else if (frame.event === "done") {
-                    break;
+                if (!last) {
+                    throw new Error("verificationStatusStream: stream closed before snapshot");
                 }
+                return last;
             }
-            if (!last) {
-                throw new Error("verificationStatusStream: stream closed before snapshot");
+            catch (err) {
+                if (options.signal?.aborted)
+                    throw options.signal.reason;
+                if (idleAc.signal.aborted)
+                    throw new TimeoutError(ms);
+                if (err instanceof CodesparApiError)
+                    throw err;
+                throw networkErrorToApiError(err, "verificationStatusStream");
+            }
+            finally {
+                idle.pause();
+                merged.cleanup();
             }
-            return last;
         },
-        async authorize(serverId, config) {
-            const r = await safeFetch(`${baseUrl}/v1/connect/start`, {
+        async authorize(serverId, config, opts) {
+            const payload = await safeFetch(`${baseUrl}/v1/connect/start`, {
                 method: "POST",
                 headers,
                 body: JSON.stringify({
@@ -324,43 +411,59 @@ export async function createSession(userId, config, deps) {
                     redirect_uri: config.redirectUri,
                     scopes: config.scopes,
                 }),
-            }, "authorize");
-            if (!r.ok) {
-                await throwFromResponse(r, "authorize");
-            }
-            const payload = (await r.json());
+            }, "authorize", callOpts(opts), async (r) => {
+                if (!r.ok)
+                    await throwFromResponse(r, "authorize");
+                return (await r.json());
+            });
             return {
                 linkToken: payload.link_token,
                 authorizeUrl: payload.authorize_url,
                 expiresAt: payload.expires_at,
             };
         },
-        async connections() {
+        async connections(opts) {
+            // Caller misconfiguration is NOT best-effort — validate the
+            // effective timeout before the swallow (parity with close()), so
+            // an invalid value surfaces instead of silently returning the
+            // cached list.
+            const resolved = callOpts(opts);
+            validateTimeout(resolved.timeout);
             // Best-effort — both transport failures (CodesparApiError from
             // safeFetch) and non-2xx responses fall back to the cached
             // payload so a transient blip doesn't crater the session.
             try {
-                const r = await safeFetch(`${baseUrl}/v1/sessions/${data.id}/connections`, { headers }, "connections");
-                if (!r.ok)
-                    return cachedConnections ?? [];
-                const payload = (await r.json());
-                cachedConnections = payload.servers;
-                cachedTools = payload.tools;
-                return payload.servers;
+                return await safeFetch(`${baseUrl}/v1/sessions/${data.id}/connections`, { headers }, "connections", resolved, async (r) => {
+                    if (!r.ok)
+                        return cachedConnections ?? [];
+                    const payload = (await r.json());
+                    cachedConnections = payload.servers;
+                    cachedTools = payload.tools;
+                    return payload.servers;
+                });
             }
             catch {
                 return cachedConnections ?? [];
             }
         },
-        async close() {
-            // Best-effort — the backend reaps stale sessions on a timer,
-            // so a network failure here shouldn't surface to the caller.
+        async close(opts) {
+            // Caller misconfiguration is NOT best-effort — validate the
+            // effective timeout before the swallow, so an invalid value
+            // surfaces (parity with Python's ConfigError) instead of
+            // silently skipping the DELETE.
+            const { timeout } = callOpts(opts);
+            validateTimeout(timeout);
+            // Best-effort: the DELETE is bounded by the timeout/abort budget
+            // so close() can't hang, but its outcome is swallowed so a slow
+            // or failing backend cleanup never throws from a caller's
+            // teardown/finally. Parity with the Python client (suppresses
+            // ApiError + TimeoutError) and the managed-agents adapter (close
+            // never throws). The backend reaps stale sessions on a timer.
             try {
-                await safeFetch(`${baseUrl}/v1/sessions/${data.id}`, { method: "DELETE", headers }, "close");
+                await safeFetch(`${baseUrl}/v1/sessions/${data.id}`, { method: "DELETE", headers }, "close", callOpts(opts), async () => undefined);
             }
             catch {
-                // Intentional swallow — matches the previous fire-and-forget
-                // contract; close() never threw.
+                // intentionally ignored — see above
             }
         },
     };
@@ -369,31 +472,53 @@ export async function createSession(userId, config, deps) {
         const start = Date.now();
         while (Date.now() - start < timeout) {
             const conns = await session.connections();
-            if (conns.every((c) => c.connected))
+            // `connections()` returns [] on a failed/empty response; an empty
+            // list must NOT count as "all connected" — [].every() is vacuously
+            // true and would resolve the gate with zero servers connected.
+            if (conns.length > 0 && conns.every((c) => c.connected))
                 break;
             await new Promise((resolve) => setTimeout(resolve, 1000));
         }
     }
     return session;
 }
-/**
- * Parse a Server-Sent Events stream into typed StreamEvent objects.
- *
- * The backend emits events shaped like:
- *   event: assistant_text
- *   data: {"content":"...","iteration":1}
- *
- * which we map to discriminated-union StreamEvent values that the SDK
- * exports. We intentionally keep parsing tiny: split on double newlines,
- * pick out `event:` and `data:` lines, JSON-parse the data.
- */
-async function* parseSseStream(body) {
+function makeIdle(idleAc, ms) {
+    let timer;
+    return {
+        reset() {
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => idleAc.abort(), ms);
+        },
+        pause() {
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+    };
+}
+async function* parseSseStream(body, idle, signal) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
+    // Single abort promise + single listener per parser call — avoids
+    // per-iteration listener accumulation and MaxListeners warnings.
+    let abortReject;
+    const abortPromise = new Promise((_resolve, reject) => {
+        abortReject = reject;
+    });
+    const onAbort = () => abortReject(signal.reason);
+    if (signal.aborted) {
+        queueMicrotask(() => abortReject(signal.reason));
+    }
+    else {
+        signal.addEventListener("abort", onAbort, { once: true });
+    }
     try {
+        idle.reset();
         while (true) {
-            const { done, value } = await reader.read();
+            const { done, value } = await Promise.race([reader.read(), abortPromise]);
             if (done)
                 break;
             buffer += decoder.decode(value, { stream: true });
@@ -401,18 +526,42 @@ async function* parseSseStream(body) {
             while ((sep = buffer.indexOf("\n\n")) !== -1) {
                 const chunk = buffer.slice(0, sep);
                 buffer = buffer.slice(sep + 2);
+                // A complete SSE comment frame (":..." heartbeat) carries no
+                // data but IS protocol liveness — reset idle. Only an
+                // incomplete byte trickle (no "\n\n" yet) must still time out.
+                if (chunk.startsWith(":")) {
+                    idle.reset();
+                    continue;
+                }
                 const event = parseSseChunk(chunk);
-                if (event)
+                if (event) {
+                    // Pause while the consumer processes the event so its
+                    // processing time is not counted as transport idle; re-arm
+                    // once control returns, before the next read.
+                    idle.pause();
                     yield event;
+                    idle.reset();
+                }
             }
         }
         if (buffer.trim()) {
             const event = parseSseChunk(buffer);
-            if (event)
+            if (event) {
+                // Same invariant as the inner loop: pause the idle timer
+                // while the consumer holds control. The stream has ended, so
+                // there is no read to re-arm for afterwards.
+                idle.pause();
                 yield event;
+            }
         }
     }
     finally {
+        idle.pause();
+        signal.removeEventListener("abort", onAbort);
+        // Best-effort, NON-blocking: a degraded ReadableStream may return a
+        // cancel() promise that never settles; awaiting it here would delay
+        // delivery of the very TimeoutError/abort the caller is waiting for.
+        void Promise.resolve(reader.cancel()).catch(() => { });
         reader.releaseLock();
     }
 }
@@ -488,13 +637,27 @@ const PRESET_SERVERS = {
  * just need raw `{event, data}` pairs the caller's typed wrapper
  * casts via the route-level envelope shape.
  */
-async function* parseStatusSseStream(body) {
+async function* parseStatusSseStream(body, idle, signal) {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
+    // Single abort promise + single listener per parser call — avoids
+    // per-iteration listener accumulation and MaxListeners warnings.
+    let abortReject;
+    const abortPromise = new Promise((_resolve, reject) => {
+        abortReject = reject;
+    });
+    const onAbort = () => abortReject(signal.reason);
+    if (signal.aborted) {
+        queueMicrotask(() => abortReject(signal.reason));
+    }
+    else {
+        signal.addEventListener("abort", onAbort, { once: true });
+    }
     try {
+        idle.reset();
         while (true) {
-            const { done, value } = await reader.read();
+            const { done, value } = await Promise.race([reader.read(), abortPromise]);
             if (done)
                 break;
             buffer += decoder.decode(value, { stream: true });
@@ -502,9 +665,16 @@ async function* parseStatusSseStream(body) {
             while ((sep = buffer.indexOf("\n\n")) !== -1) {
                 const chunk = buffer.slice(0, sep);
                 buffer = buffer.slice(sep + 2);
-                // Comment frames (heartbeats) start with ":" and carry no data.
-                if (chunk.startsWith(":"))
+                // Comment frames (heartbeats) start with ":" and carry no
+                // data, but a complete heartbeat frame IS protocol liveness —
+                // reset idle so healthy long-pending streams don't time out
+                // (parity with Python httpx, whose read timeout any byte
+                // resets). An incomplete byte trickle still times out because
+                // it never forms a "\n\n" frame.
+                if (chunk.startsWith(":")) {
+                    idle.reset();
                     continue;
+                }
                 let eventName = "message";
                 let dataLine = "";
                 for (const line of chunk.split("\n")) {
@@ -515,16 +685,27 @@ async function* parseStatusSseStream(body) {
                 }
                 if (!dataLine)
                     continue;
+                let parsed;
                 try {
-                    yield { event: eventName, data: JSON.parse(dataLine) };
+                    parsed = JSON.parse(dataLine);
                 }
                 catch {
                     continue;
                 }
+                // Pause while the consumer processes the frame; re-arm after.
+                idle.pause();
+                yield { event: eventName, data: parsed };
+                idle.reset();
             }
         }
     }
     finally {
+        idle.pause();
+        signal.removeEventListener("abort", onAbort);
+        // Best-effort, NON-blocking: a degraded ReadableStream may return a
+        // cancel() promise that never settles; awaiting it here would delay
+        // delivery of the very TimeoutError/abort the caller is waiting for.
+        void Promise.resolve(reader.cancel()).catch(() => { });
         reader.releaseLock();
     }
 }