@guuey/agent-client 0.4.0 → 0.6.0

package/src/useAgentInvoke.ts

@@ -23,15 +23,10 @@
  */
 import { useCallback, useEffect, useRef, useState } from "react";
 import { Reducer, type AgReduceResult } from "@silverprotocol/core";
-import {
-  parseConsentRequest,
-  parseLinkRequest,
-  parseSseEvents,
-  reduceAssistantText,
-  stringField,
-} from "./sse.js";
-import { ingestMessageFrame } from "./blocks.js";
+import { invokeTurn, toInvokeUrl } from "./invoke-turn.js";
 import { AgentResponseError } from "./errors.js";
+import { withActivityObserver } from "./transport.js";
+import { CLIENT_ERROR_CODES } from "./error-codes.js";
 import type {
   AgentInvokeAdapters,
   AgentInvokeStatus,
@@ -40,6 +35,7 @@ import type {
   HistoryLoadResult,
   ProfileConsentRequest,
   ProfileLinkRequest,
+  StallRecoveryOptions,
   UseAgentInvokeOptions,
   UseAgentInvokeReturn,
 } from "./types.js";
@@ -70,6 +66,53 @@ export function applyHistoryResult(
   return { kind: "seed", messages: result.messages };
 }
 
+/** The guuey#192 stall watchdog's resolved tuning (see {@link stallProbeDecision}). */
+export const STALL_RECOVERY_DEFAULTS = { windowMs: 25_000, probeAttempts: 4 } as const;
+
+function resolveStallRecovery(
+  option: false | StallRecoveryOptions | undefined,
+): { windowMs: number; probeAttempts: number } | null {
+  if (option === false) return null;
+  return {
+    windowMs: option?.windowMs ?? STALL_RECOVERY_DEFAULTS.windowMs,
+    probeAttempts: option?.probeAttempts ?? STALL_RECOVERY_DEFAULTS.probeAttempts,
+  };
+}
+
+/**
+ * Pure decision seam for the guuey#192 stall probe: does a freshly-loaded
+ * transcript already contain THIS turn's finished reply?
+ *
+ * `adopt` requires BOTH signals, because each alone lies in a real case:
+ *
+ *  - **user-count**: history must hold at least as many user turns as the
+ *    local transcript (which includes the just-sent optimistic one). Without
+ *    it, a thread whose PREVIOUS turn ended in a completed assistant reply
+ *    would adopt that OLD transcript and silently drop the in-flight turn.
+ *  - **finished tail**: history's last message must be a non-empty assistant
+ *    reply. Without it, a history read that caught the persisted user row
+ *    before the assistant row would adopt a reply-less transcript.
+ *
+ * KNOWN LIMIT (documented, accepted): the runtime persists a turn's rows at
+ * completion — the guuey#192 evidence (a reload mid-stall renders the FULL
+ * reply) is only possible under that model, and the read plane carries no
+ * per-row clientMessageId to match against. If persistence ever becomes
+ * progressive (partial assistant rows), this heuristic needs the read plane
+ * to grow a turn-completion marker — do not "fix" it client-side by text
+ * comparison, which cannot distinguish a partial row from a finished one.
+ */
+export function stallProbeDecision(
+  history: AgentMessage[],
+  localUserCount: number,
+): "adopt" | "in-flight" {
+  let historyUserCount = 0;
+  for (const m of history) if (m.role === "user") historyUserCount += 1;
+  if (historyUserCount < localUserCount) return "in-flight";
+  const last = history[history.length - 1];
+  if (!last || last.role !== "assistant" || last.text.trim() === "") return "in-flight";
+  return "adopt";
+}
+
 export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeReturn {
   const { endpointUrl, appId } = opts;
   const [messages, setMessages] = useState<AgentMessage[]>([]);
@@ -102,6 +145,13 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
   // explicit dismiss, same lifecycle as `profileConsentRequest` — the two are
   // independent (an unlinked-invite vs an already-linked consent ask).
   const [profileLinkRequest, setProfileLinkRequest] = useState<ProfileLinkRequest | null>(null);
+  // The last turn's ending posture + the optimistic-send ledger — the
+  // transcript renderer's inputs (guuey#135 wave 3b; see the return-type
+  // contract for each). `aborted` is USER abort only — the #192 watchdog's
+  // internal stream abort never sets it.
+  const [aborted, setAborted] = useState(false);
+  const [adopted, setAdopted] = useState(false);
+  const [sendStates, setSendStates] = useState<Readonly<Record<string, "sending" | "failed">>>({});
 
   const abortRef = useRef<AbortController | null>(null);
   // Mirror the latest threadId + adapters into refs so `send` reads fresh
@@ -110,6 +160,13 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
   const threadIdRef = useRef<string | null>(null);
   const adaptersRef = useRef<AgentInvokeAdapters>(opts.adapters);
   adaptersRef.current = opts.adapters;
+  // The stall probe (guuey#192) needs the committed transcript's user-turn
+  // count long after `send`'s closures captured state — same render-time
+  // mirror idiom as `adaptersRef`.
+  const messagesRef = useRef<AgentMessage[]>(messages);
+  messagesRef.current = messages;
+  const stallRecoveryRef = useRef(opts.stallRecovery);
+  stallRecoveryRef.current = opts.stallRecovery;
   // The per-conversation AgJSON fold (only built when `preserveBlocks`).
   // Lazily (re)created on the first valid AgEvent after a fresh start / reset,
   // so an off run never constructs one and a bypass run never allocates.
@@ -147,6 +204,9 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     // A prior app's consent ask must never leak into the new conversation.
     setProfileConsentRequest(null);
     setProfileLinkRequest(null);
+    setAborted(false);
+    setAdopted(false);
+    setSendStates({});
 
     let cancelled = false;
     const key = threadStorageKey(appId);
@@ -237,6 +297,9 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     setHistoryCards([]);
     setProfileConsentRequest(null);
     setProfileLinkRequest(null);
+    setAborted(false);
+    setAdopted(false);
+    setSendStates({});
   }, [appId]);
 
   const clearProfileConsentRequest = useCallback(() => {
@@ -249,14 +312,47 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
 
   const send = useCallback(
     async (input: string) => {
-      if (!endpointUrl || !input.trim() || status !== "ready") return;
+      // An already-aborted external signal refuses the send outright —
+      // before the optimistic transcript push, so nothing is left to undo.
+      if (!endpointUrl || !input.trim() || status !== "ready" || opts.signal?.aborted) return;
       setError(null);
       setErrorCode(null);
+      setAborted(false);
+      setAdopted(false);
       setStatus("connecting");
-      setMessages((prev) => [...prev, { role: "user", text: input }, { role: "assistant", text: "" }]);
+      // ONE id for the whole turn: the optimistic user entry, the send-state
+      // ledger, and the invoke body all carry it — the R0 lifecycle join.
+      const clientMessageId = adaptersRef.current.generateId();
+      /** Move this turn's ledger entry; `null` removes it (absent = sent). */
+      const markSend = (state: "sending" | "failed" | null): void => {
+        setSendStates((prev) => {
+          if (state === null) {
+            if (!(clientMessageId in prev)) return prev;
+            const next: Record<string, "sending" | "failed"> = { ...prev };
+            delete next[clientMessageId];
+            return next;
+          }
+          if (prev[clientMessageId] === state) return prev;
+          return { ...prev, [clientMessageId]: state };
+        });
+      };
+      markSend("sending");
+      let admitted = false;
+      setMessages((prev) => [
+        ...prev,
+        { role: "user", text: input, clientMessageId },
+        { role: "assistant", text: "" },
+      ]);
 
       const controller = new AbortController();
       abortRef.current = controller;
+      // Compose the host's external abort authority (opts.signal) with the
+      // per-turn controller: an external abort stops this turn exactly as
+      // `abort()` would. Listener removed in `finally` — the signal outlives
+      // the turn, the subscription must not.
+      const externalSignal = opts.signal;
+      const onExternalAbort = (): void => controller.abort();
+      externalSignal?.addEventListener("abort", onExternalAbort, { once: true });
       const adapters = adaptersRef.current;
       // Wait for the persisted threadId to load before deciding whether to
       // replay it — otherwise a fast first send mints a new orphan thread and
@@ -280,92 +376,155 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
         });
       };
 
+      // ── guuey#192 stall watchdog ─────────────────────────────────────
+      // A half-dead connection (TCP alive, zero bytes, no error, no `done`)
+      // never resolves the read below, so a parallel clock watches byte
+      // activity: armed by the FIRST chunk (so a silent cold start never
+      // trips it), reset by every chunk, and on expiry it probes history
+      // WITHOUT touching the stream — killing a live-but-quiet stream on a
+      // timer would trade a frozen cursor for a lost turn. Only two things
+      // end the turn early: adoption (history already holds the finished
+      // reply — the reload the user would have done, minus the reload) and
+      // the bounded give-up (STREAM_STALLED after `probeAttempts` fruitless
+      // probes with still-zero bytes).
+      const stall = resolveStallRecovery(stallRecoveryRef.current);
+      let turnEnded = false;
+      let probeInFlight = false;
+      let fruitlessProbes = 0;
+      let activityCount = 0;
+      let stallTimer: ReturnType<typeof setTimeout> | null = null;
+      const clearStallTimer = (): void => {
+        if (stallTimer !== null) {
+          clearTimeout(stallTimer);
+          stallTimer = null;
+        }
+      };
+      const armStallTimer = (): void => {
+        if (!stall || turnEnded || controller.signal.aborted) return;
+        clearStallTimer();
+        stallTimer = setTimeout(() => {
+          void onStallWindow();
+        }, stall.windowMs);
+      };
+      const endTurnWith = (apply: () => void): void => {
+        turnEnded = true;
+        clearStallTimer();
+        apply();
+        // Unwinds the suspended read; the catch sees `aborted` and stays
+        // silent, so whatever `apply` decided IS the turn's outcome.
+        controller.abort();
+      };
+      const onStallWindow = async (): Promise<void> => {
+        if (!stall || turnEnded || controller.signal.aborted || probeInFlight) return;
+        const tid = threadIdRef.current;
+        const history = adaptersRef.current.history;
+        if (tid && history) {
+          probeInFlight = true;
+          const countAtProbe = activityCount;
+          let result: HistoryLoadResult | null = null;
+          try {
+            result = await history.load(tid);
+          } catch {
+            result = null; // transient read failure = one fruitless probe
+          }
+          probeInFlight = false;
+          if (turnEnded || controller.signal.aborted) return;
+          // Bytes resumed while the probe was in flight: the stream is alive
+          // — discard the now-stale read; the chunk observer already reset
+          // the count and re-armed the clock.
+          if (activityCount !== countAtProbe) return;
+          if (result && !("gone" in result)) {
+            let localUserCount = 0;
+            for (const m of messagesRef.current) if (m.role === "user") localUserCount += 1;
+            if (stallProbeDecision(result.messages, localUserCount) === "adopt") {
+              const adoptedResult = result;
+              endTurnWith(() => {
+                setMessages(adoptedResult.messages);
+                if ("cards" in adoptedResult && adoptedResult.cards && adoptedResult.cards.length > 0) {
+                  setHistoryCards(adoptedResult.cards);
+                }
+                // The renderer's #192 signal: calm renders the adopted turn
+                // identically; debug may mark it (guuey#135 3b).
+                setAdopted(true);
+              });
+              return;
+            }
+          }
+        }
+        // No probe possible (no threadId yet / no history adapter), a failed
+        // read, or history says the turn is still in flight — all count the
+        // same: one fruitless window.
+        fruitlessProbes += 1;
+        if (fruitlessProbes >= stall.probeAttempts) {
+          endTurnWith(() => {
+            setError("The response stream stalled and the finished reply was not found in history.");
+            setErrorCode(CLIENT_ERROR_CODES.STREAM_STALLED);
+          });
+          return;
+        }
+        armStallTimer();
+      };
+      const transport = stall
+        ? withActivityObserver(adapters.transport, () => {
+            activityCount += 1;
+            fruitlessProbes = 0;
+            armStallTimer();
+          })
+        : adapters.transport;
+
       try {
-        // The endpointUrl may be a pod base (`https://host`) or the full
-        // invoke URL the deploy-controller records (`https://host/agent/invoke`).
-        // Normalize to exactly one `/agent/invoke`.
-        const base = endpointUrl.replace(/\/+$/, "");
-        const invokeUrl = base.endsWith("/agent/invoke") ? base : `${base}/agent/invoke`;
+        const invokeUrl = toInvokeUrl(endpointUrl);
         const body = {
           input,
           ...(threadIdRef.current ? { threadId: threadIdRef.current } : {}),
-          clientMessageId: adapters.generateId(),
+          clientMessageId,
         };
 
-        let buffer = "";
-        for await (const chunk of adapters.transport({ url: invokeUrl, body, signal: controller.signal })) {
-          buffer += chunk;
-          const { events, rest } = parseSseEvents(buffer);
-          buffer = rest;
-          for (const ev of events) {
-            if (ev.event === "session") {
-              // The pod is awake and the turn is admitted — 'connecting' ends
-              // here (this frame arrives within ~1s of a warm pod; a cold
-              // scale-to-zero start is exactly the long 'connecting' phase).
-              setStatus("thinking");
-              const tid = stringField(ev.data, "threadId");
-              if (tid) {
-                threadIdRef.current = tid;
-                setThreadId(tid);
-                void adapters.storage.save(threadStorageKey(appId), tid);
-              }
-            } else if (ev.event === "message") {
-              // Status derivation (guuey#91) — read the frame's `type` before
-              // the text fold. Silver frames announce tools + text explicitly;
-              // bypass frames ('text' / 'assistant' SDKMessages) only ever
-              // carry assistant text, so they map to 'responding'. Unknown
-              // types deliberately leave the status untouched.
-              const frameType = stringField(ev.data, "type");
-              if (frameType === "tool.start") {
-                setStatus("using-tool");
-                setActiveTool(stringField(ev.data, "name") ?? null);
-              } else if (frameType === "tool.done") {
-                setStatus("thinking");
-                setActiveTool(null);
-              } else if (
-                frameType === "text.start" ||
-                frameType === "text.delta" ||
-                frameType === "text" ||
-                frameType === "assistant"
-              ) {
-                setStatus("responding");
-              }
-              renderAssistant(reduceAssistantText(assistantText, ev.data));
-              // Additively fold the SAME frame into the AgJSON reducer when
-              // opted in. The text surface above is untouched; only VALID
-              // AgEvents advance the reducer (bypass frames ingest to [] and
-              // leave `reduceResult` null — see the return-type contract).
-              if (preserveBlocksRef.current) {
-                const agEvents = ingestMessageFrame(ev.data);
-                if (agEvents.length > 0) {
-                  if (!reducerRef.current) reducerRef.current = new Reducer();
-                  for (const agEvent of agEvents) reducerRef.current.push(agEvent);
-                  setReduceResult(reducerRef.current.result());
-                }
-              }
-            } else if (ev.event === "error") {
-              // In-band failure frame — one of the two channels that carry the
-              // pod's wire code (the other is the pre-stream refusal caught
-              // below). A frame without a `code` clears it rather than leaving
-              // a previous turn's code standing beside a new message.
-              setError(stringField(ev.data, "message") ?? "agent error");
-              setErrorCode(stringField(ev.data, "code") ?? null);
-            } else if (ev.event === "profile-consent-needed") {
-              // Cross-app profile consent ask (T6). Only a well-formed payload
-              // updates state; a malformed one is dropped, leaving any prior
-              // valid request untouched (never clobbered to null).
-              const parsed = parseConsentRequest(ev.data);
-              if (parsed) setProfileConsentRequest(parsed);
-            } else if (ev.event === "profile-link-needed") {
-              // Cross-app profile LINK invite (linkcoh T3) for an unlinked byo
-              // caller. Same drop-if-malformed contract as consent above.
-              const parsed = parseLinkRequest(ev.data);
-              if (parsed) setProfileLinkRequest(parsed);
+        // The wire walk lives in `invokeTurn` (the pure per-turn generator —
+        // its docblock owns the switch semantics); this hook only maps each
+        // semantic event onto React state.
+        for await (const ev of invokeTurn(
+          { url: invokeUrl, body, signal: controller.signal },
+          transport,
+        )) {
+          if (ev.kind === "session") {
+            // The pod is awake and the turn is admitted — 'connecting' ends
+            // here, and so does the R0 "sending" state (absent = sent).
+            admitted = true;
+            markSend(null);
+            setStatus("thinking");
+            if (ev.threadId) {
+              threadIdRef.current = ev.threadId;
+              setThreadId(ev.threadId);
+              void adapters.storage.save(threadStorageKey(appId), ev.threadId);
+            }
+          } else if (ev.kind === "message") {
+            // Absent status/activeTool mean "no change" — never touched, so
+            // an unknown frame type leaves both standing (guuey#91 rule).
+            if (ev.status !== undefined) setStatus(ev.status);
+            if (ev.activeTool !== undefined) setActiveTool(ev.activeTool);
+            renderAssistant(ev.assistantText);
+            // Additively fold the frame's AgEvents into the AgJSON reducer
+            // when opted in. The text surface above is untouched; only VALID
+            // AgEvents advance the reducer (bypass frames carry [] and leave
+            // `reduceResult` null — see the return-type contract).
+            if (preserveBlocksRef.current && ev.agEvents.length > 0) {
+              if (!reducerRef.current) reducerRef.current = new Reducer();
+              for (const agEvent of ev.agEvents) reducerRef.current.push(agEvent);
+              setReduceResult(reducerRef.current.result());
             }
-            // `done` needs no handling — the stream closes after it. Any other
-            // (unknown) event falls through silently — there is no default
-            // branch, so a consumer that never renders a field is unaffected.
+          } else if (ev.kind === "error") {
+            // In-band failure frame — the code moves in lockstep with the
+            // message (an event without one carries null rather than leaving
+            // a previous turn's code standing).
+            setError(ev.message);
+            setErrorCode(ev.code);
+          } else if (ev.kind === "profile-consent") {
+            setProfileConsentRequest(ev.request);
+          } else if (ev.kind === "profile-link") {
+            setProfileLinkRequest(ev.request);
           }
+          // `done` needs no handling here — the stream closes after it.
         }
       } catch (e) {
         if (!controller.signal.aborted) {
@@ -376,8 +535,21 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
           // other throw — a network drop, a host-adapter failure — has no wire
           // code, so the field stays null beside the message.
           setErrorCode(e instanceof AgentResponseError ? (e.code ?? null) : null);
+          // A failure BEFORE admission means the message never reached the
+          // agent — the R0 failed-to-send state. Post-admission failures
+          // leave the entry removed (the send itself succeeded).
+          if (!admitted) markSend("failed");
         }
       } finally {
+        // The turn is over however it ended — no probe may fire after this,
+        // and the pending timer must not leak past the turn. `turnEnded`
+        // already true here ⟺ the #192 watchdog ended the turn (adoption or
+        // stall give-up) — its internal `controller.abort()` must not read
+        // as a USER abort below.
+        const endedByWatchdog = turnEnded;
+        turnEnded = true;
+        clearStallTimer();
+        externalSignal?.removeEventListener("abort", onExternalAbort);
         setStatus("ready");
         setActiveTool(null);
         abortRef.current = null;
@@ -392,9 +564,16 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
               : prev;
           });
         }
+        if (controller.signal.aborted && !endedByWatchdog) {
+          // USER abort (abort() or the external signal): surface it, and a
+          // pre-admission cancel clears the "sending" entry — a turn the
+          // user stopped is not a failed send.
+          setAborted(true);
+          if (!admitted) markSend(null);
+        }
       }
     },
-    [endpointUrl, appId, status],
+    [endpointUrl, appId, status, opts.signal],
   );
 
   return {
@@ -413,5 +592,8 @@ export function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeRetur
     clearProfileConsentRequest,
     profileLinkRequest,
     clearProfileLinkRequest,
+    aborted,
+    adopted,
+    sendStates,
   };
 }

package/src/web-adapters.ts

@@ -15,19 +15,9 @@ import {
   type ResolvedViewMount,
   type UiActionRequest,
 } from "@guuey/mcp-apps-host";
-import type {
-  AgentInvokeAdapters,
-  InvokeRequest,
-  InvokeTransport,
-  ThreadIdStore,
-} from "./types.js";
+import type { AgentInvokeAdapters, InvokeTransport, ThreadIdStore } from "./types.js";
 import { fetchThreadHistory, HistoryUnauthorizedError } from "./history.js";
-import { AgentResponseError } from "./errors.js";
-import {
-  parseRetryAfterSeconds,
-  withSaturationRetry,
-  type SaturationRetryOptions,
-} from "./saturation-retry.js";
+import { fetchStreamTransport, sendableGuestSecret, GUEST_HEADER } from "./transport.js";
 
 /** Persists the threadId in `window.localStorage` (synchronously). */
 export const localStorageThreadStore: ThreadIdStore = {
@@ -57,142 +47,6 @@ export function webGenerateId(): string {
   return `cmid-${Date.now()}-${Math.floor(Math.random() * 1e9)}`;
 }
 
-/**
- * Header carrying a caller-owned anonymous guest secret. A LOCAL MIRROR of the
- * two server-side constants — the pod's `GUEST_HEADER_NAME`
- * (`backend/services/nocode-runtime/src/identity.ts`) and the read plane's
- * `GUEST_HEADER` (`backend/amplify/functions/publicApi/identity.ts`) — because
- * this is a published npm package and cannot take a `@guuey-private` dep (same
- * arrangement as `@guuey/host`'s mirrored fs-contract constants). The string is
- * a wire contract: both planes already advertise it in
- * `Access-Control-Allow-Headers`, so changing it is a breaking protocol change,
- * not a rename.
- */
-const GUEST_HEADER = "x-guuey-guest";
-
-/**
- * A well-formed guest secret: exactly 32 bytes as 64 LOWERCASE hex chars —
- * the shape `crypto.getRandomValues` + hex-encoding mints.
- *
- * Deliberately stricter than the server's `/^[a-f0-9]{64}$/i` (pod
- * `identity.ts`, publicApi `identity.ts`): both sides lowercase before
- * hashing, so an uppercase secret would in fact be accepted, but the only
- * supported mint path emits lowercase and a non-canonical value means the
- * caller's storage is not what this adapter expects. Anything that fails is
- * IGNORED — the request falls through to cookie mode rather than sending a
- * secret the two identity planes might key differently.
- */
-const GUEST_SECRET_RE = /^[0-9a-f]{64}$/;
-
-/**
- * Narrow a caller-supplied guest secret to a value that is safe to put on the
- * wire, or `null`. The single gate for the header: every write of
- * {@link GUEST_HEADER} in this module goes through it, so a malformed secret
- * can never reach a request. The value is never logged (here or anywhere on
- * this path) — it IS the anonymous identity, so a leak is an impersonation.
- */
-function sendableGuestSecret(secret: string | null | undefined): string | null {
-  return typeof secret === "string" && GUEST_SECRET_RE.test(secret) ? secret : null;
-}
-
-/**
- * One invoke attempt: opens the request and yields decoded SSE chunks.
- * {@link fetchStreamTransport} wraps this with the shared saturation retry —
- * every behaviour below is per-attempt.
- *
- * Exactly ONE identity carrier per request, in order:
- *
- *  1. `accessToken` → `Authorization: Bearer` — the pod identifies the caller
- *     by their verified access token (the same identity the history read
- *     plane uses, so persisted threads round-trip on reload).
- *  2. a well-formed `guestSecret` → `x-guuey-guest` — the caller owns and
- *     persists its own anonymous secret. The path for hosts with no usable
- *     cookie jar: React-Native, and the embedded widget, whose third-party
- *     iframe cannot rely on the pod's cookie surviving browser partitioning.
- *     The pod never mints a cookie for a header client.
- *  3. neither → `credentials: "include"`, which round-trips the HttpOnly
- *     `guuey_guest` cookie the pod mints for anonymous browser callers.
- *
- * Never two at once: a bearer wins over a guest secret, and a request that
- * carries either header does NOT also send cookie credentials.
- *
- * Reads the body via `ReadableStream.getReader()` (browser).
- */
-async function* streamInvokeOnce(
-  req: InvokeRequest,
-  accessToken?: string | null,
-  guestSecret?: string | null,
-): AsyncGenerator<string> {
-  const headers: Record<string, string> = {
-    "Content-Type": "application/json",
-    Accept: "text/event-stream",
-  };
-  const init: RequestInit = {
-    method: "POST",
-    signal: req.signal,
-    headers,
-    body: JSON.stringify(req.body),
-  };
-  const guest = sendableGuestSecret(guestSecret);
-  if (accessToken) {
-    headers.Authorization = `Bearer ${accessToken}`;
-  } else if (guest) {
-    headers[GUEST_HEADER] = guest;
-  } else {
-    init.credentials = "include";
-  }
-  const resp = await fetch(req.url, init);
-  if (!resp.ok || !resp.body) {
-    // Surface a structured pod error ({ code, message }) when present — e.g. a
-    // QUOTA_EXCEEDED 429 carries an upgrade message the UI should show. Fall
-    // back to the bare status for non-JSON failures.
-    const body: unknown = await resp.json().catch(() => null);
-    let message = `agent responded ${resp.status}`;
-    let code: string | undefined;
-    if (body !== null && typeof body === "object") {
-      if ("message" in body && typeof body.message === "string" && body.message) {
-        message = body.message;
-      }
-      if ("code" in body && typeof body.code === "string") {
-        code = body.code;
-      }
-    }
-    throw new AgentResponseError(
-      message,
-      resp.status,
-      code,
-      parseRetryAfterSeconds(resp.headers.get("Retry-After")),
-    );
-  }
-  const reader = resp.body.getReader();
-  const decoder = new TextDecoder();
-  for (;;) {
-    const { value, done } = await reader.read();
-    if (done) break;
-    yield decoder.decode(value, { stream: true });
-  }
-}
-
-/**
- * The web SSE transport: {@link streamInvokeOnce} under the shared
- * {@link withSaturationRetry} wrapper. Every consumer of this transport
- * (Studio, the widget, anything built on {@link createWebAdapters}) therefore
- * inherits the single `POD_SATURATED` retry, and inherits the SAME one Portal's
- * React-Native transport wears — see that wrapper's docblock for which refusals
- * retry, which deliberately do not, and why the retry is invisible to the hook.
- */
-export function fetchStreamTransport(
-  req: InvokeRequest,
-  accessToken?: string | null,
-  guestSecret?: string | null,
-  options: SaturationRetryOptions = {},
-): AsyncIterable<string> {
-  return withSaturationRetry(
-    (attempt) => streamInvokeOnce(attempt, accessToken, guestSecret),
-    options,
-  )(req);
-}
-
 export interface CreateWebAdaptersOptions {
   /**
    * Public read-plane base (ending in `/v1`) for transcript history. When
@@ -274,10 +128,16 @@ export function createWebAdapters(
   const { apiBaseUrl, getAccessToken, getGuestSecret } = opts;
 
   const transport: InvokeTransport = async function* (req) {
-    const token = getAccessToken ? await getAccessToken() : null;
     // Both candidates go to the transport; it owns the precedence (and the
     // never-two-carriers rule) so there is exactly one place that decides.
-    yield* fetchStreamTransport(req, token, getGuestSecret ? getGuestSecret() : null);
+    // The bearer goes through as the PROVIDER, not a pre-resolved value:
+    // the transport re-asks it per attempt, so a cold-start retry after a
+    // backoff wait re-reads a fresh token instead of replaying one that may
+    // have expired during the wait (the same reason Portal's RN transport
+    // resolves inside its generator).
+    yield* fetchStreamTransport(req, null, getGuestSecret ? getGuestSecret() : null, {
+      getBearer: getAccessToken,
+    });
   };
 
   const adapters: AgentInvokeAdapters = {