@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/session-remote.js

@@ -1,50 +1,94 @@
 import { SSE_HEARTBEAT_MS } from "./channels/sse.js";
 import { abortFirstIterator } from "./collect.js";
 import { isAddressableSession, } from "./session.js";
-/** Dead-connection watchdog for SSE reads: the server heartbeats every SSE_HEARTBEAT_MS, so a
- *  PENDING READ seeing no bytes (of ANY kind — comments included) for this many missed beats
- *  means the connection is a black hole. The stream is aborted and surfaced as an error, so a
- *  consumer's failure budget ticks instead of hanging forever. Quiet-but-alive streams (a long
- *  tool call) keep heartbeating and never trip this. */
+/**
+ * Dead-connection watchdog for SSE reads: the server heartbeats every SSE_HEARTBEAT_MS, so a PENDING READ seeing no
+ * bytes (of ANY kind — comments included) for this many missed beats means the connection is a black hole.
+ */
 const SSE_IDLE_LIMIT_MS = 3 * SSE_HEARTBEAT_MS;
-function idleWatchdog(abort) {
-    let armedAt;
-    let stale = false;
-    const timer = setInterval(() => {
-        if (armedAt !== undefined && Date.now() - armedAt > SSE_IDLE_LIMIT_MS) {
-            stale = true;
-            abort.abort();
-        }
-    }, SSE_HEARTBEAT_MS);
+/**
+ * Every request carries a TIMEOUT: a client's reliability model counts failed rounds against a budget ("unreachable
+ * for ~Ns"), which a black-hole endpoint (firewall drop, half-dead tunnel) would silently defeat — a hung
+ * state()/entries(), or a stream that never finishes connecting, ticks nothing.
+ */
+const REQUEST_TIMEOUT_MS = 10_000;
+/** The PAYLOAD-bearing calls get a longer budget than the black-hole detector's 10s. */
+const PAYLOAD_TIMEOUT_MS = 60_000;
+class StreamEnded extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = "StreamEnded";
+        this.kind = kind;
+    }
+}
+/** The reason this connection was ended, when one was given — `undefined` for any other failure. */
+function endedBecause(signal) {
+    return signal.reason instanceof StreamEnded ? signal.reason : undefined;
+}
+function readBudget(abort, what, connectMs) {
+    let timer;
+    let connected = false;
+    const expire = () => abort.abort(connected
+        ? new StreamEnded("idle", `${what}: no bytes for ${SSE_IDLE_LIMIT_MS / 1000}s (heartbeats absent) — dead connection`)
+        : new StreamEnded("connect-timeout", `${what}: no usable response in ${connectMs / 1000}s — the endpoint accepted the connection and never completed one`));
+    const disarm = () => {
+        clearTimeout(timer);
+        timer = undefined;
+    };
     return {
+        // `??=`: a nested arm does not restart the clock, so one long read cannot be extended by re-arming inside it.
         arm: () => {
-            armedAt ??= Date.now();
+            timer ??= setTimeout(expire, connected ? SSE_IDLE_LIMIT_MS : connectMs);
         },
-        disarm: () => {
-            armedAt = undefined;
+        disarm,
+        connected: () => {
+            disarm();
+            connected = true;
         },
-        stale: () => stale,
-        stop: () => clearInterval(timer),
     };
 }
-/** A control request the server answered with a non-2xx status. Carries the STRUCTURED status so a
- *  consumer distinguishing auth failure (401 — stale token, unrecoverable) from transient transport
- *  trouble branches on `status`, never on message prose. */
+/**
+ * Open a streaming response — the one connect sequence both wire planes perform, under one budget: the headers, the
+ * error body of a non-2xx (a half-dead tunnel answering 4xx and then black-holing the body is the case that makes
+ * this one phase rather than two), and the check that a body exists at all. It returns only once the connection is
+ * something that can carry events, which is the moment the budget switches to the idle limit.
+ */
+async function openStreamBody(options) {
+    const { fetchFn, url, init, abort, budget, what } = options;
+    budget.arm(); // the connect await is a pending read
+    const res = await fetchFn(url, { ...init, signal: abort.signal });
+    if (!res.ok)
+        throw new ControlRequestError(res.status, await res.text());
+    if (!res.body)
+        throw new Error(`${what}: response has no body`);
+    budget.connected();
+    return res.body;
+}
+/** A control request the server answered with a non-2xx status. */
 export class ControlRequestError extends Error {
     status;
-    /** The plane's own error code, when the reply carried one (`sessions()` is the only read that
-     *  does today — design §13). Absent for a plain-text rejection (401) or a proxy's page: a caller
-     *  distinguishing "this deployment cannot list sessions" from "the endpoint is unreachable" reads
-     *  THIS, not the status. */
+    /**
+     * The plane's own error code, when the reply carried one (`sessions()` is the only read that does today — design
+     * §13).
+     */
     code;
-    constructor(status, body, code) {
+    /**
+     * Whether re-sending is worth it, as the plane itself answered — the same question `SessionResult.retryable`
+     * answers for a write, carried here because a throwing read has no result to put it in. Absent when the reply
+     * declared no opinion; a caller then has only the status.
+     */
+    retryable;
+    constructor(status, body, declared) {
         super(`control request failed: ${status} ${body}`);
         this.status = status;
-        if (code !== undefined)
-            this.code = code;
+        if (declared?.code !== undefined)
+            this.code = declared.code;
+        if (declared?.retryable !== undefined)
+            this.retryable = declared.retryable;
     }
 }
-/** A non-2xx reply as an error, carrying the plane's code when the reply declared one. */
+/** A non-2xx reply as an error, carrying what the plane declared about it. */
 async function controlError(res) {
     const body = await res.text();
     if (!res.headers.get("content-type")?.includes("application/json"))
@@ -54,77 +98,73 @@ async function controlError(res) {
         parsed = JSON.parse(body);
     }
     catch {
-        // The reply declared JSON and is not — a protocol fault worth seeing, but not worth losing the
-        // status over: both travel in one error rather than a bare SyntaxError from a rejection path.
+        // The reply declared JSON and is not — a protocol fault worth seeing, but not worth losing the status over.
         return new ControlRequestError(res.status, `${body} (declared application/json but did not parse)`);
     }
-    return new ControlRequestError(res.status, body, typeof parsed?.code === "string" ? parsed.code : undefined);
+    return new ControlRequestError(res.status, body, {
+        ...(typeof parsed?.code === "string" ? { code: parsed.code } : {}),
+        ...(typeof parsed?.retryable === "boolean" ? { retryable: parsed.retryable } : {}),
+    });
 }
-/**
- * Connect and return a remote `SessionControl`. Async because `capabilities()` is synchronous in
- * the contract: the static declaration is fetched ONCE here and served from memory — which also
- * makes a wrong URL/token fail at connect time, not on first use.
- */
 export async function connectSessionControl(options) {
-    const { url, token, fetchFn = fetch } = options;
+    const { url, fetchFn = fetch } = options;
     const base = url.replace(/\/$/, "");
-    const headers = { authorization: `Bearer ${token}` };
-    // Non-streaming requests carry a TIMEOUT: attach's whole reliability model counts failed rounds
-    // against a budget ("unreachable for ~Ns"), which a black-hole endpoint (firewall drop, half-dead
-    // tunnel) would silently defeat — a hung state()/entries() ticks nothing. The SSE stream stays
-    // timeout-free (quiet is normal there; heartbeats cover proxy idling).
-    const REQUEST_TIMEOUT_MS = 10_000;
-    // The PAYLOAD-bearing calls get a longer budget than the black-hole detector's 10s — in both
-    // directions: dispatch may UPLOAD up to the 1 MiB body cap (base64 images in steer/follow_up),
-    // and entries may DOWNLOAD a long session's full record (a cursor-less first backfill) — a slow
-    // link legitimately needs longer, and cutting a healthy transfer would be indistinguishable from
-    // a dead endpoint. capabilities/state stay on the short detector: they are small by contract.
-    const PAYLOAD_TIMEOUT_MS = 60_000;
     const get = async (path, timeoutMs = REQUEST_TIMEOUT_MS) => {
-        const res = await fetchFn(`${base}${path}`, { headers, signal: AbortSignal.timeout(timeoutMs) });
+        const res = await fetchFn(`${base}${path}`, { signal: AbortSignal.timeout(timeoutMs) });
         if (!res.ok)
             throw await controlError(res);
         return (await res.json());
     };
     const capabilities = await get("/control/capabilities");
     const eventsOf = (session) => {
-        // Each ITERATION opens its own connection (gen/abort created inside asyncIterator), matching
-        // the local hub's "every iteration is a fresh subscription" — a shared single-use generator
-        // would make the second for-await silently empty, breaking local/remote isomorphism.
-        // The abort controller lives OUTSIDE the generator: a consumer's `return()`/`break` while the
-        // generator is suspended on a quiet SSE read must abort the fetch FIRST — an async generator's
-        // own finally only runs after the pending await settles, which a silent stream never does.
+        // The server subscribes BEFORE it writes the response headers (channels/sse.ts pulls the source once first), so
+        // "headers arrived, 2xx" IS "this session's subscription exists" — the boundary a reconnecting client awaits
+        // before reading history (session.ts, SessionEventStream).
+        let subscribed;
+        let unreachable;
+        const ready = new Promise((resolve, reject) => {
+            subscribed = resolve;
+            unreachable = reject;
+        });
+        // A consumer that never awaits `ready` (it can iterate and let the stream report the same failure) would
+        // otherwise take an unhandled rejection for a connection that legitimately failed. Awaiters still get it.
+        ready.catch(() => { });
+        // ONE CALL IS ONE SUBSCRIPTION — one connection, one readiness. A second iteration would open a second
+        // connection and inherit this `ready`, reporting a boundary the first one crossed; it is refused instead, the
+        // same way the local hub refuses it.
         const openStream = (abort) => (async function* iterate() {
-            // Armed BEFORE the fetch: the connect phase (headers never arriving from a black-holed
-            // endpoint) is otherwise a window no timeout covers — the same watchdog terminates it,
-            // with headers-arrival counting as the first sign of life.
-            const watchdog = idleWatchdog(abort);
-            watchdog.arm(); // the connect await is a pending read
+            const budget = readBudget(abort, "control events", REQUEST_TIMEOUT_MS);
             try {
-                const res = await fetchFn(`${base}/control/sessions/${encodeURIComponent(session)}/events`, {
-                    headers,
-                    signal: abort.signal,
-                });
-                watchdog.disarm(); // headers arrived
-                if (!res.ok) {
-                    // The error body is a pending read too — a half-dead tunnel serving 4xx headers then
-                    // black-holing the body must not hang the round outside every budget. Re-armed: the
-                    // watchdog aborts the read and the round fails with the dead-connection diagnosis.
-                    watchdog.arm();
-                    throw new ControlRequestError(res.status, await res.text());
+                let body;
+                try {
+                    body = await openStreamBody({
+                        fetchFn,
+                        url: `${base}/control/sessions/${encodeURIComponent(session)}/events`,
+                        init: {},
+                        abort,
+                        budget,
+                        what: "control events",
+                    });
                 }
-                if (!res.body)
-                    throw new Error("control events: response has no body");
+                catch (error) {
+                    // The subscription was never established: the endpoint is unreachable or never completed a response, a
+                    // gateway in front refused it, the consumer cancelled first. Whoever ended it said why, and `fetch` rejected with
+                    // that very object. A waiter on `ready` must learn it instead of waiting out a stream that will never
+                    // carry anything — including the cancellation, which the ITERATION reports as a clean end (walking away
+                    // is not an error) while `ready` still has a promise it cannot keep.
+                    const failure = endedBecause(abort.signal) ?? error;
+                    unreachable(failure);
+                    throw failure;
+                }
+                subscribed();
                 let nextSeq = 0;
-                for await (const data of sseData(res.body, watchdog)) {
-                    // Parse discipline, same as the other two wire planes (dispatch parses, invoke
-                    // classifies drift): a non-JSON or non-envelope payload is PROTOCOL MISMATCH —
-                    // thrown, so a consumer's failure budget applies — never misdiagnosed as an
-                    // in-transit gap whose remedy (reconnect) can never fix it.
+                for await (const data of sseData(body, budget)) {
+                    // Parse discipline, same as the other two wire planes (dispatch parses, invoke classifies drift): a
+                    // non-JSON or non-envelope payload is PROTOCOL MISMATCH.
                     let wire;
                     try {
-                        // The ONE envelope type (control.ts's WireEvent) — an inline shape would let the
-                        // envelope drift server-side while this cast silently kept the old fields.
+                        // The ONE envelope type (control.ts's WireEvent) — an inline shape would let the envelope drift
+                        // server-side while this cast silently kept the old fields.
                         wire = JSON.parse(data);
                     }
                     catch (parseError) {
@@ -138,11 +178,7 @@ export async function connectSessionControl(options) {
                         typeof wire.event.type !== "string") {
                         throw new Error("control events: malformed envelope — the endpoint does not speak this protocol version");
                     }
-                    // Envelope checks — consumed HERE. (epoch is not compared: it cannot change within
-                    // one connection — see the header note.) A gap THROWS like a protocol mismatch: the
-                    // consumer's failure path (budget, its own io) owns the diagnostic — a library-level
-                    // log would bypass consumer output discipline, and a silent clean end would be
-                    // indistinguishable from the server closing normally.
+                    // Envelope checks — consumed HERE.
                     if (wire.seq !== nextSeq) {
                         throw new Error(`control events: sequence gap (expected ${nextSeq}, got ${wire.seq}) — events were lost in transit; resync via entries()`);
                     }
@@ -151,34 +187,48 @@ export async function connectSessionControl(options) {
                 }
             }
             catch (error) {
-                if (abort.signal.aborted) {
-                    if (watchdog.stale()) {
-                        throw new Error(`control events: no bytes for ${SSE_IDLE_LIMIT_MS / 1000}s (heartbeats absent) — dead connection; resync via entries()`);
-                    }
+                const ended = endedBecause(abort.signal);
+                if (ended?.kind === "cancelled")
                     return; // the consumer walked away — clean end, not an error
-                }
-                throw error;
+                throw ended ?? error;
             }
             finally {
-                watchdog.stop();
+                budget.disarm();
                 abort.abort();
             }
         })();
+        let iterated = false;
         return {
+            ready,
             [Symbol.asyncIterator]() {
+                if (iterated) {
+                    throw new Error("control events: this stream is one subscription — call events() again for another");
+                }
+                iterated = true;
                 const abort = new AbortController();
-                // Abort-first cancellation (see abortFirstIterator): aborting the connection unblocks a
-                // generator suspended on a quiet stream read.
-                return abortFirstIterator(openStream(abort), () => abort.abort());
+                // Abort-first cancellation (see abortFirstIterator): aborting the connection unblocks a generator suspended
+                // on a quiet stream read.
+                return abortFirstIterator(openStream(abort), () => {
+                    const cancelled = new StreamEnded("cancelled", "control events: cancelled by the consumer");
+                    abort.abort(cancelled);
+                    // Said HERE as well as in the generator's catch, because a generator that was never pulled does not run its
+                    // body on `return()` — and then nothing else would ever settle `ready`. Rejecting an already-settled
+                    // promise is a no-op, so the connected case still reports whatever ended it.
+                    unreachable(cancelled);
+                });
             },
         };
     };
-    /** A write that answers a `SessionResult`: the result rides HTTP 200 either way (`ok: false` is a
-     *  protocol answer, not a transport failure), so a non-2xx here is a REAL transport/auth fault. */
+    /**
+     * A write that answers a `SessionResult`: the result rides HTTP 200 either way (`ok: false` is a protocol answer,
+     * not a transport failure), so a non-2xx here is a REAL transport fault.
+     */
     const write = async (path, method, body) => {
+        // Always declared, body or not: the plane refuses a write it was not told is JSON (channels/body.ts), and an
+        // empty `PATCH` is a legal no-op that still has to get through.
         const res = await fetchFn(`${base}${path}`, {
             method,
-            headers: body === undefined ? headers : { ...headers, "content-type": "application/json" },
+            headers: { "content-type": "application/json" },
             ...(body === undefined ? {} : { body: JSON.stringify(body) }),
             signal: AbortSignal.timeout(PAYLOAD_TIMEOUT_MS),
         });
@@ -189,12 +239,8 @@ export async function connectSessionControl(options) {
     const id = (session) => encodeURIComponent(session);
     return {
         capabilities: () => capabilities,
-        // NOT prefetched like capabilities: a live definition can grow a skill between calls, so the
-        // list is fetched per call. The endpoint is UNCACHED server-side (it re-reads the definition's
-        // skills/ per request), which is what keeps it honest about a directory that changes underneath
-        // it. A 404 is SKEW, not a fault in the definition: without this the two read identically
-        // (uncoded non-2xx), and a client would report "this agent's skills are unreadable" about a
-        // serve that simply predates the route.
+        // NOT prefetched like capabilities: a live definition can grow a skill between calls, so the list is fetched per
+        // call.
         async commands() {
             try {
                 return await get("/control/commands");
@@ -207,16 +253,9 @@ export async function connectSessionControl(options) {
             }
         },
         sessions: {
-            // Rejects when the deployment cannot enumerate its store — the coded 503 arrives as a
-            // ControlRequestError carrying `sessions_unavailable`, so a client can tell it from an
-            // unreachable endpoint instead of retrying forever.
+            // Rejects when the deployment cannot enumerate its store.
             list: () => get("/control/sessions", PAYLOAD_TIMEOUT_MS),
-            // PUT: the fork is idempotent, and so is the request that carries it. `into` becomes a path
-            // segment exactly like `get`'s id, so it is refused on the same rule — without this the local
-            // plane answers `invalid_command` while the wire answers 404 from a URL that normalised away.
-            // ASYNC, so the guard REJECTS rather than throwing out of a method typed `Promise`: a caller
-            // that wrote `.catch(…)` — or handed this to `Promise.all` — must not be surprised by a
-            // synchronous throw. (`get` may throw: it is synchronous by signature.)
+            // PUT: the fork is idempotent, and so is the request that carries it.
             fork: async ({ from, at, into }) => {
                 if (!isAddressableSession(into)) {
                     throw new Error(`session id ${JSON.stringify(into)} cannot travel as a URL path segment — this transport cannot address it`);
@@ -224,12 +263,6 @@ export async function connectSessionControl(options) {
                 return write(`/control/sessions/${id(into)}`, "PUT", { from, at });
             },
             // The local hub's handle is a pure binding; so is this one — an id and the transport above it.
-            // Nothing is FETCHED here, which is what keeps the two isomorphic. What is checked is the one
-            // thing the wire cannot express: `.` and `..` survive `encodeURIComponent` and are then
-            // normalised away by URL parsing, so every call on such a handle would arrive at a DIFFERENT
-            // route — `.` reads as the collection (200 JSON, which the SSE reader ends as a silently empty
-            // stream) and `..` as a 404 the local plane answers normally. Refused at the binding, where a
-            // caller can see it, rather than once per call in a place it looks like a server answer.
             get: (session) => {
                 if (!isAddressableSession(session)) {
                     throw new Error(`session id ${JSON.stringify(session)} cannot travel as a URL path segment — this transport cannot address it`);
@@ -254,18 +287,12 @@ export async function connectSessionControl(options) {
     };
 }
 /**
- * The remote DATA plane: an `Agent` whose `invoke` drives `POST /control/invoke` on a serving
- * process — paired with {@link connectSessionControl}, a client holds a full remote fastagent
- * instance through the same two contracts local code uses. A REAL Agent, failure discipline
- * included: SPEC MUST 2 forbids iteration throws, so every failure — transport (401/refused/
- * dropped mid-stream), protocol, and the images precheck — becomes a terminal `failed` event
- * (`retryable` from the HTTP status where one exists; network trouble is retryable). Breaking out
- * of iteration disconnects the request, which cancels the run (SPEC cancellation semantics travel
- * the wire). The invoke wire is text-only for now: a prompt with images fails visibly instead of
- * silently dropping them (steer/follow_up on the control plane carry full Prompts).
+ * The remote DATA plane: an `Agent` whose `invoke` drives `POST /invoke` on a serving process. A real Agent,
+ * failure discipline included — SPEC MUST 2 forbids iteration throws, so transport, protocol and precheck failures
+ * all become `failed` events.
  */
 export function connectAgent(options) {
-    const { url, token, fetchFn = fetch } = options;
+    const { url, fetchFn = fetch } = options;
     const base = url.replace(/\/$/, "");
     const toFailed = (error) => {
         if (error instanceof ControlRequestError) {
@@ -273,13 +300,12 @@ export function connectAgent(options) {
         }
         return { type: "failed", details: String(error), retryable: true }; // network-class: worth re-sending
     };
-    // COMPILE-TIME drift guard (dispatch-wire parity): the invoke body carries exactly text (and
-    // rejects images visibly) — a new Prompt field must break THIS line and force a decision
-    // (carry it or reject it), never vanish on the wire while the client believes it was sent.
+    // COMPILE-TIME drift guard (dispatch-wire parity): the invoke body carries exactly text (and rejects images
+    // visibly).
     const _invokeDriftGuard = {};
     void _invokeDriftGuard;
-    // Same guard for Scope: the body carries session + the lineage extension — a new Scope field must
-    // force a decision (carry it or reject it), never vanish on the wire.
+    // Same guard for Scope: the body carries session + the lineage extension — a new Scope field must force a decision
+    // (carry it or reject it), never vanish on the wire.
     const _scopeDriftGuard = {};
     void _scopeDriftGuard;
     return {
@@ -296,37 +322,33 @@ export function connectAgent(options) {
                 }
                 // A terminal closes the stream. Cleanup errors must not append a second terminal.
                 let terminalSeen = false;
-                // Armed BEFORE the fetch — the run's driver must not hang on a black-holed connect
-                // either (the connect await is a pending read; headers arriving disarm it).
-                const watchdog = idleWatchdog(abort);
-                watchdog.arm();
+                // The run's driver rides the same mechanism as the events plane, with the connect limit its own callers
+                // need: a black-holed POST must not hang it, but a scale-to-zero host (fly `auto_start_machines`, a cold
+                // AgentCore container) can legitimately hold this open for tens of seconds before the first header, and
+                // that is a slow success, not a dead endpoint. A connect failure lands in the catch below, which is where
+                // every non-terminal failure becomes the one `failed` event this stream owes its caller.
+                const budget = readBudget(abort, "remote invoke", PAYLOAD_TIMEOUT_MS);
                 try {
-                    const res = await fetchFn(`${base}/control/invoke`, {
-                        method: "POST",
-                        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
-                        body: JSON.stringify({
-                            session: scope.session,
-                            text: prompt.text,
-                            // Lineage rides the wire so a remote thread scope inherits server-side; the server
-                            // reads it on the session-create path only, same as in-process.
-                            ...(scope.parentSession !== undefined ? { parentSession: scope.parentSession } : {}),
-                            ...(scope.branchHints !== undefined ? { branchHints: scope.branchHints } : {}),
-                        }),
-                        signal: abort.signal,
+                    const body = await openStreamBody({
+                        fetchFn,
+                        url: `${base}/invoke`,
+                        init: {
+                            method: "POST",
+                            headers: { "content-type": "application/json" },
+                            body: JSON.stringify({
+                                session: scope.session,
+                                text: prompt.text,
+                                // Lineage rides the wire so a remote thread scope inherits server-side; the server reads it on the
+                                // session-create path only, same as in-process.
+                                ...(scope.parentSession !== undefined ? { parentSession: scope.parentSession } : {}),
+                                ...(scope.branchHints !== undefined ? { branchHints: scope.branchHints } : {}),
+                            }),
+                        },
+                        abort,
+                        budget,
+                        what: "remote invoke",
                     });
-                    watchdog.disarm(); // headers arrived
-                    if (!res.ok) {
-                        watchdog.arm(); // the error body is a pending read too — see the events() twin
-                        const failure = toFailed(new ControlRequestError(res.status, await res.text()));
-                        watchdog.disarm();
-                        yield failure;
-                        return;
-                    }
-                    if (!res.body) {
-                        yield { type: "failed", details: "remote invoke: response has no body", retryable: true };
-                        return;
-                    }
-                    for await (const data of sseData(res.body, watchdog)) {
+                    for await (const data of sseData(body, budget)) {
                         let event;
                         try {
                             event = JSON.parse(data);
@@ -339,9 +361,8 @@ export function connectAgent(options) {
                             };
                             return;
                         }
-                        // Shape check, same discipline as the events plane: `data: null` / `data: 42` is
-                        // valid JSON but protocol drift — it must not TypeError into the catch below and be
-                        // misclassified as retryable network trouble.
+                        // Shape check, same discipline as the events plane: `data: null` / `data: 42` is valid JSON but
+                        // protocol drift.
                         if (typeof event !== "object" || event === null || typeof event.type !== "string") {
                             yield {
                                 type: "failed",
@@ -358,29 +379,23 @@ export function connectAgent(options) {
                     yield { type: "failed", details: "remote invoke: stream ended without a terminal", retryable: true };
                 }
                 catch (error) {
-                    if (abort.signal.aborted) {
-                        if (watchdog.stale() && !terminalSeen) {
-                            yield {
-                                type: "failed",
-                                details: `remote invoke: no bytes for ${SSE_IDLE_LIMIT_MS / 1000}s (heartbeats absent) — dead connection`,
-                                retryable: true,
-                            };
-                        }
-                        return; // the consumer walked away — cancellation, not an error
-                    }
+                    const ended = endedBecause(abort.signal);
+                    // Cancellation is the consumer's own doing — reporting it back would be news to nobody. Any other stated
+                    // reason is a connection that died under the run, and this stream still owes its caller a terminal —
+                    // unless one was already sent, since a second would describe the run rather than the connection.
+                    if (ended?.kind === "cancelled")
+                        return;
                     if (!terminalSeen)
-                        yield toFailed(error);
+                        yield ended ? { type: "failed", details: ended.message, retryable: true } : toFailed(error);
                 }
                 finally {
-                    watchdog.stop();
+                    budget.disarm();
                     abort.abort();
                 }
             })();
-            // ONE stream per invoke, like a local async generator (which is its own iterator): a second
-            // iteration must never re-POST — that would silently start a second run with the same prompt.
-            // Abort-first cancellation (see abortFirstIterator): disconnect = cancel the run, even
-            // while suspended on a quiet read.
-            const iterator = abortFirstIterator(openStream(), () => abort.abort());
+            // ONE stream per invoke, like a local async generator (which is its own iterator): a second iteration must
+            // never re-POST.
+            const iterator = abortFirstIterator(openStream(), () => abort.abort(new StreamEnded("cancelled", "remote invoke: cancelled by the consumer")));
             return {
                 [Symbol.asyncIterator]() {
                     return iterator;
@@ -389,10 +404,7 @@ export function connectAgent(options) {
         },
     };
 }
-/** Minimal SSE reader: yields each `data:` payload; ignores comments (heartbeats) and other
- *  fields. The explicit reader loop (not for-await) exists for the watchdog: armed strictly
- *  around each pending read, so only "we are listening and nothing arrives" counts as idle — a
- *  consumer pausing at a yield leaves the watch disarmed (see {@link ReadWatch}). */
+/** Minimal SSE reader: yields each `data:` payload; ignores comments (heartbeats) and other fields. */
 async function* sseData(body, watch) {
     const decoder = new TextDecoder();
     let buffer = "";
@@ -404,8 +416,7 @@ async function* sseData(body, watch) {
             watch?.disarm(); // bytes (ANY bytes — heartbeats included) or a clean end arrived
             if (done)
                 return;
-            // SSE permits CRLF line endings (proxies/other servers may produce them); normalize AFTER
-            // appending so a \r\n split across chunks still collapses once its second half arrives.
+            // SSE permits CRLF line endings (proxies/other servers may produce them).
             buffer = (buffer + decoder.decode(value, { stream: true })).replace(/\r\n/g, "\n");
             let sep = buffer.indexOf("\n\n");
             while (sep !== -1) {