@guuey/agent-client 0.3.1 → 0.5.0

package/dist/invoke-turn.js

@@ -0,0 +1,124 @@
+import { parseConsentRequest, parseLinkRequest, parseSseEvents, reduceAssistantText, stringField, } from "./sse.js";
+import { ingestMessageFrame } from "./blocks.js";
+/**
+ * Normalize an agent endpoint to its invoke URL (guuey#186 G3). Accepts BOTH
+ * shapes a consumer legitimately holds — a pod base (`https://host`) and the
+ * full invoke URL the deploy-controller records (`https://host/agent/invoke`)
+ * — and returns exactly one `/agent/invoke`, trailing slashes dropped. This
+ * is the single normalization `useAgentInvoke` applies to its `endpointUrl`;
+ * a host driving {@link invokeTurn} (or any raw transport) directly builds
+ * its request URL with the same call instead of re-implementing the rule.
+ */
+export function toInvokeUrl(endpointUrl) {
+    const base = endpointUrl.replace(/\/+$/, "");
+    return base.endsWith("/agent/invoke") ? base : `${base}/agent/invoke`;
+}
+/**
+ * Drive one `/agent/invoke` turn over `transport`, yielding semantic events.
+ * Pure per-turn: no React, no storage, no retry policy (the transport owns
+ * saturation retry), no reducer — see the module docblock for what belongs
+ * to the caller.
+ *
+ * The event stream is also the OBSERVATION channel (guuey#186 Gap 4): there
+ * is deliberately no `onToolResult` callback API, because filtering the
+ * generator expresses it directly — every tool result arrives as a typed
+ * `tool.done` AgEvent on a `message` event, carrying `toolCallId`,
+ * `content`, `outcome` and `structuredContent`.
+ *
+ * @example Telemetry off the fold — observe tool results without touching
+ * the transcript path:
+ * ```ts
+ * for await (const ev of invokeTurn(req, transport)) {
+ *   if (ev.kind !== "message") continue;
+ *   for (const agEvent of ev.agEvents) {
+ *     if (agEvent.type === "tool.done") {
+ *       telemetry.record(agEvent.toolCallId, agEvent.outcome ?? "ok");
+ *     }
+ *   }
+ *   render(ev.assistantText); // the fold is untouched by the observation
+ * }
+ * ```
+ */
+export async function* invokeTurn(req, transport) {
+    let assistantText = "";
+    let buffer = "";
+    for await (const chunk of transport(req)) {
+        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 (this frame arrives
+                // within ~1s of a warm pod; a cold scale-to-zero start is exactly
+                // the long wait before it).
+                yield { kind: "session", threadId: stringField(ev.data, "threadId") ?? null };
+            }
+            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 imply no status change.
+                const frameType = stringField(ev.data, "type");
+                assistantText = reduceAssistantText(assistantText, ev.data);
+                // Only VALID AgEvents surface (bypass frames ingest to []) — the
+                // caller's reducer, if any, advances on these alone.
+                const agEvents = ingestMessageFrame(ev.data);
+                if (frameType === "tool.start") {
+                    yield {
+                        kind: "message",
+                        status: "using-tool",
+                        activeTool: stringField(ev.data, "name") ?? null,
+                        assistantText,
+                        agEvents,
+                    };
+                }
+                else if (frameType === "tool.done") {
+                    yield { kind: "message", status: "thinking", activeTool: null, assistantText, agEvents };
+                }
+                else if (frameType === "text.start" ||
+                    frameType === "text.delta" ||
+                    frameType === "text" ||
+                    frameType === "assistant") {
+                    yield { kind: "message", status: "responding", assistantText, agEvents };
+                }
+                else {
+                    yield { kind: "message", assistantText, agEvents };
+                }
+            }
+            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 thrown by the
+                // transport). A frame without a `code` yields null rather than
+                // leaving a previous turn's code standing beside a new message.
+                yield {
+                    kind: "error",
+                    message: stringField(ev.data, "message") ?? "agent error",
+                    code: stringField(ev.data, "code") ?? null,
+                };
+            }
+            else if (ev.event === "profile-consent-needed") {
+                // Cross-app profile consent ask (T6). Only a well-formed payload
+                // yields; a malformed one is dropped, leaving any prior valid
+                // request untouched (never clobbered to null).
+                const parsed = parseConsentRequest(ev.data);
+                if (parsed)
+                    yield { kind: "profile-consent", request: 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)
+                    yield { kind: "profile-link", request: parsed };
+            }
+            else if (ev.event === "done") {
+                // The stream closes after this frame; yielded so a host can read the
+                // pod's stop reason without private wire knowledge.
+                yield { kind: "done", stopReason: stringField(ev.data, "stopReason") ?? null };
+            }
+            // Any other (unknown) event falls through silently — additive wire
+            // events never disturb a consumer.
+        }
+    }
+}

package/dist/react.d.ts

@@ -6,6 +6,6 @@
  * history reader, and the web adapters). Consumers that only need those never
  * import React at all; consumers that render chat import the hook from here.
  */
-export { useAgentInvoke, applyHistoryResult, type HistoryApplication } from "./useAgentInvoke";
+export { useAgentInvoke, applyHistoryResult, type HistoryApplication, stallProbeDecision, STALL_RECOVERY_DEFAULTS, } from "./useAgentInvoke.js";
 export type { AgEvent, AgReduceResult } from "@silverprotocol/core";
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAI/F,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAI7B,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/react.js

@@ -6,4 +6,4 @@
  * history reader, and the web adapters). Consumers that only need those never
  * import React at all; consumers that render chat import the hook from here.
  */
-export { useAgentInvoke, applyHistoryResult } from "./useAgentInvoke";
+export { useAgentInvoke, applyHistoryResult, stallProbeDecision, STALL_RECOVERY_DEFAULTS, } from "./useAgentInvoke.js";

package/dist/saturation-retry.d.ts

@@ -0,0 +1,101 @@
+import type { InvokeTransport } from "./types.js";
+/**
+ * Read `Retry-After` as WHOLE SECONDS, or `undefined`.
+ *
+ * HTTP also allows an absolute HTTP-date, which is deliberately NOT parsed:
+ * the pod only ever emits a delta-seconds integer, and silently mis-reading a
+ * date as `NaN` seconds is worse than falling back to the fixed delay.
+ *
+ * Exported because every transport that builds an {@link AgentResponseError}
+ * has to fill `retryAfterSeconds` the same way for {@link withSaturationRetry}
+ * to honour the same hint — a second hand-rolled regex in a host adapter is
+ * exactly the drift this module exists to prevent.
+ */
+export declare function parseRetryAfterSeconds(header: string | null): number | undefined;
+/** Options for {@link withSaturationRetry}. */
+export interface SaturationRetryOptions {
+    /**
+     * The saturation-retry wait. Injectable so tests drive the retry without a
+     * real 15s timer; production uses an abort-aware `setTimeout`.
+     */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+/**
+ * Wrap an invoke transport with ONE automatic retry on a saturated pod.
+ *
+ * ## What retries, and what deliberately does not
+ *
+ * `POD_SATURATED` (503) means the pod is at its concurrent-turn cap right now
+ * — a transient queue state that clears as in-flight turns finish, so a single
+ * delayed re-send usually just works. The wait is the pod's own `Retry-After`
+ * hint (via {@link AgentResponseError.retryAfterSeconds}), defaulting to 15s
+ * when it sent none and capped at 30s.
+ *
+ * `DRAINING` (also 503 + `Retry-After`) is NOT retried in v1. The refusing pod
+ * is shutting down: its readiness probe is already failing and the endpoint
+ * pull is in flight, so the useful retry is the one that reaches a DIFFERENT
+ * pod — and a wrapped transport re-sends to the same URL. Retrying here would
+ * spend the user's 15s to arrive back at the same draining pod (or at a fresh
+ * one by luck), which is not a guarantee worth building on. When the retry can
+ * be made routing-aware, this is the code to revisit.
+ *
+ * Exactly ONE retry: a second saturation propagates as
+ * {@link AgentResponseError}, so a genuinely overloaded agent surfaces instead
+ * of looping. Nothing is retried once a chunk has been yielded — replaying
+ * mid-stream would duplicate a partial assistant turn (the same `yielded`
+ * guard the widget's `withIdentifiedToken` 401-retry uses). An abort during
+ * the wait skips the retry and surfaces the original refusal.
+ *
+ * The retry is INVISIBLE to `useAgentInvoke`: no frames were yielded, so the
+ * turn simply stays in `connecting` for the duration of the wait. There is no
+ * `retrying` status by design — the hook's state machine describes the pod's
+ * turn lifecycle, not the transport's plumbing.
+ *
+ * The wrapped transport is re-invoked from scratch for the retry, so a host
+ * that resolves identity inside its own generator (Portal's RN transport reads
+ * the bearer bridge per attempt) re-reads it on the second try rather than
+ * replaying a token that may have expired during the wait.
+ */
+export declare function withSaturationRetry(transport: InvokeTransport, options?: SaturationRetryOptions): InvokeTransport;
+/** Options for {@link withColdStartRetry}. */
+export interface ColdStartRetryOptions {
+    /**
+     * Retries after the initial attempt (`0` disables the wrapper's behaviour
+     * entirely). Default 3 — a small, bounded budget: the point is parity with
+     * guuey's first-party embeds during the ordinary post-redeploy window, not
+     * riding out an outage. Raise it for an unattended harness that would
+     * rather wait than fail.
+     */
+    attempts?: number;
+    /**
+     * First wait in ms; each subsequent wait doubles, capped at
+     * {@link maxDelayMs}. Default 2000 → 2s / 4s / 8s for the default budget.
+     */
+    baseDelayMs?: number;
+    /** Ceiling on any single wait (hinted or computed), in ms. Default 10000. */
+    maxDelayMs?: number;
+    /** The wait itself — injectable so tests drive the retry without timers. */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+/**
+ * Wrap an invoke transport with a bounded retry on cold-start 503s
+ * (guuey#186 Gap 3 — parity with first-party embeds, which already carry
+ * this behaviour; SDK consumers were eating the raw 503 window instead).
+ *
+ * Matches ONLY {@link isColdStartRefusal} — an envelope-less 503 — and
+ * retries up to `attempts` times with doubling, capped backoff (honouring a
+ * `Retry-After` hint when the response carried one). Exhaustion propagates
+ * the final refusal untouched.
+ *
+ * Nothing is retried once a chunk has been yielded: a stream that dies
+ * MID-turn is never silently re-POSTed — the turn may have had side effects
+ * and the consumer already saw partial output. Same `yielded` guard as
+ * {@link withSaturationRetry}, same reasoning. An abort during a wait
+ * surfaces the refusal that caused the wait.
+ *
+ * Like the saturation wrapper, the retry is invisible to `useAgentInvoke`
+ * (the turn stays in `connecting`), and the wrapped transport is re-invoked
+ * from scratch so per-attempt identity resolution re-runs.
+ */
+export declare function withColdStartRetry(transport: InvokeTransport, options?: ColdStartRetryOptions): InvokeTransport;
+//# sourceMappingURL=saturation-retry.d.ts.map

package/dist/saturation-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saturation-retry.d.ts","sourceRoot":"","sources":["../src/saturation-retry.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,YAAY,CAAC;AAiBjE;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAMhF;AA4BD,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,eAAe,EAC1B,OAAO,GAAE,sBAA2B,GACnC,eAAe,CAqBjB;AAED,8CAA8C;AAC9C,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAkBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,eAAe,EAC1B,OAAO,GAAE,qBAA0B,GAClC,eAAe,CA0BjB"}

package/dist/saturation-retry.js

@@ -0,0 +1,207 @@
+/**
+ * The invoke-refusal retry wrappers, transport-agnostic: the single
+ * `POD_SATURATED` auto-retry ({@link withSaturationRetry}) and the bounded
+ * cold-start 503 retry ({@link withColdStartRetry}).
+ *
+ * Their own module — rather than living inside `./web-adapters.ts`, where the
+ * first was born — because the behaviour is a property of the platform's
+ * refusal vocabulary, not of `fetch`. Every host that speaks `/agent/invoke`
+ * wants them, including the ones that cannot import the web adapter bundle:
+ * Portal's React-Native transport wraps its own `fetch` call with these the
+ * same way `fetchStreamTransport` wraps its browser streaming reader, so the
+ * two wear byte-identical retry semantics instead of two hand-written copies
+ * that drift.
+ *
+ * The two wrappers are DELIBERATELY distinct code paths: saturation retry is
+ * driven by the pod's structured refusal envelope (`code: POD_SATURATED`),
+ * while the cold-start retry matches only an envelope-LESS 503 — the raw
+ * infra answer (ingress with no ready pod) during the post-redeploy window,
+ * which by definition carries no wire code. They share the backoff machinery,
+ * never the predicate.
+ *
+ * This module imports only `./types.js`, `./errors.js` and `./error-codes.js`
+ * — all pure — so pulling it in costs a React-Native build nothing.
+ */
+import { AGENT_ERROR_CODES } from "./error-codes.js";
+import { AgentResponseError } from "./errors.js";
+/**
+ * Fallback wait before the saturation retry when the pod sent no usable
+ * `Retry-After` — the same 15s the pod's governor hints today
+ * (`GOVERNOR_RETRY_AFTER_SECONDS`), so a stripped header behaves like the
+ * normal case rather than hammering.
+ */
+const SATURATION_FALLBACK_DELAY_SECONDS = 15;
+/**
+ * Ceiling on the honoured hint. A pod that (mis)configures a multi-minute
+ * `Retry-After` must not park a chat UI in `connecting` for that long — past
+ * this the user is better served by the visible failure they can act on.
+ */
+const SATURATION_MAX_DELAY_SECONDS = 30;
+/**
+ * Read `Retry-After` as WHOLE SECONDS, or `undefined`.
+ *
+ * HTTP also allows an absolute HTTP-date, which is deliberately NOT parsed:
+ * the pod only ever emits a delta-seconds integer, and silently mis-reading a
+ * date as `NaN` seconds is worse than falling back to the fixed delay.
+ *
+ * Exported because every transport that builds an {@link AgentResponseError}
+ * has to fill `retryAfterSeconds` the same way for {@link withSaturationRetry}
+ * to honour the same hint — a second hand-rolled regex in a host adapter is
+ * exactly the drift this module exists to prevent.
+ */
+export function parseRetryAfterSeconds(header) {
+    if (header === null)
+        return undefined;
+    const trimmed = header.trim();
+    if (!/^\d+$/.test(trimmed))
+        return undefined;
+    const seconds = Number(trimmed);
+    return Number.isSafeInteger(seconds) ? seconds : undefined;
+}
+/** How long to wait before the single saturation retry, in milliseconds. */
+function saturationDelayMs(retryAfterSeconds) {
+    const hinted = retryAfterSeconds ?? SATURATION_FALLBACK_DELAY_SECONDS;
+    return Math.min(hinted, SATURATION_MAX_DELAY_SECONDS) * 1000;
+}
+/**
+ * Wait `ms`, or resolve early if the turn is aborted — a user who hits stop
+ * must not sit through the remainder of a 15s backoff before the UI settles.
+ */
+function delay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const finish = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, ms);
+        signal.addEventListener("abort", finish, { once: true });
+    });
+}
+/**
+ * Wrap an invoke transport with ONE automatic retry on a saturated pod.
+ *
+ * ## What retries, and what deliberately does not
+ *
+ * `POD_SATURATED` (503) means the pod is at its concurrent-turn cap right now
+ * — a transient queue state that clears as in-flight turns finish, so a single
+ * delayed re-send usually just works. The wait is the pod's own `Retry-After`
+ * hint (via {@link AgentResponseError.retryAfterSeconds}), defaulting to 15s
+ * when it sent none and capped at 30s.
+ *
+ * `DRAINING` (also 503 + `Retry-After`) is NOT retried in v1. The refusing pod
+ * is shutting down: its readiness probe is already failing and the endpoint
+ * pull is in flight, so the useful retry is the one that reaches a DIFFERENT
+ * pod — and a wrapped transport re-sends to the same URL. Retrying here would
+ * spend the user's 15s to arrive back at the same draining pod (or at a fresh
+ * one by luck), which is not a guarantee worth building on. When the retry can
+ * be made routing-aware, this is the code to revisit.
+ *
+ * Exactly ONE retry: a second saturation propagates as
+ * {@link AgentResponseError}, so a genuinely overloaded agent surfaces instead
+ * of looping. Nothing is retried once a chunk has been yielded — replaying
+ * mid-stream would duplicate a partial assistant turn (the same `yielded`
+ * guard the widget's `withIdentifiedToken` 401-retry uses). An abort during
+ * the wait skips the retry and surfaces the original refusal.
+ *
+ * The retry is INVISIBLE to `useAgentInvoke`: no frames were yielded, so the
+ * turn simply stays in `connecting` for the duration of the wait. There is no
+ * `retrying` status by design — the hook's state machine describes the pod's
+ * turn lifecycle, not the transport's plumbing.
+ *
+ * The wrapped transport is re-invoked from scratch for the retry, so a host
+ * that resolves identity inside its own generator (Portal's RN transport reads
+ * the bearer bridge per attempt) re-reads it on the second try rather than
+ * replaying a token that may have expired during the wait.
+ */
+export function withSaturationRetry(transport, options = {}) {
+    return async function* retrying(req) {
+        let yielded = false;
+        try {
+            for await (const chunk of transport(req)) {
+                yielded = true;
+                yield chunk;
+            }
+            return;
+        }
+        catch (err) {
+            const saturated = err instanceof AgentResponseError && err.code === AGENT_ERROR_CODES.POD_SATURATED;
+            if (!saturated || yielded)
+                throw err;
+            await (options.sleep ?? delay)(saturationDelayMs(err.retryAfterSeconds), req.signal);
+            // Aborted mid-wait: the user is done with this turn. Surface the refusal
+            // that caused the wait rather than spending a request that `fetch` would
+            // reject on the signal anyway.
+            if (req.signal.aborted)
+                throw err;
+        }
+        yield* transport(req);
+    };
+}
+const COLD_START_DEFAULT_ATTEMPTS = 3;
+const COLD_START_BASE_DELAY_MS = 2_000;
+const COLD_START_MAX_DELAY_MS = 10_000;
+/**
+ * Is this failure the cold-start refusal shape? An envelope-less 503: the
+ * status came from infra (no ready pod behind the route — the ~30–60s window
+ * after a redeploy), so there is no wire `code`. A 503 that DOES carry a code
+ * is the pod itself refusing (`POD_SATURATED`, `DRAINING`) and belongs to
+ * {@link withSaturationRetry}'s policy — including its deliberate decision NOT
+ * to retry `DRAINING` — never to this wrapper.
+ */
+function isColdStartRefusal(err) {
+    return err instanceof AgentResponseError && err.status === 503 && err.code === undefined;
+}
+/**
+ * Wrap an invoke transport with a bounded retry on cold-start 503s
+ * (guuey#186 Gap 3 — parity with first-party embeds, which already carry
+ * this behaviour; SDK consumers were eating the raw 503 window instead).
+ *
+ * Matches ONLY {@link isColdStartRefusal} — an envelope-less 503 — and
+ * retries up to `attempts` times with doubling, capped backoff (honouring a
+ * `Retry-After` hint when the response carried one). Exhaustion propagates
+ * the final refusal untouched.
+ *
+ * Nothing is retried once a chunk has been yielded: a stream that dies
+ * MID-turn is never silently re-POSTed — the turn may have had side effects
+ * and the consumer already saw partial output. Same `yielded` guard as
+ * {@link withSaturationRetry}, same reasoning. An abort during a wait
+ * surfaces the refusal that caused the wait.
+ *
+ * Like the saturation wrapper, the retry is invisible to `useAgentInvoke`
+ * (the turn stays in `connecting`), and the wrapped transport is re-invoked
+ * from scratch so per-attempt identity resolution re-runs.
+ */
+export function withColdStartRetry(transport, options = {}) {
+    const attempts = options.attempts ?? COLD_START_DEFAULT_ATTEMPTS;
+    const baseDelayMs = options.baseDelayMs ?? COLD_START_BASE_DELAY_MS;
+    const maxDelayMs = options.maxDelayMs ?? COLD_START_MAX_DELAY_MS;
+    const sleep = options.sleep ?? delay;
+    return async function* retrying(req) {
+        let yielded = false;
+        for (let attempt = 0;; attempt++) {
+            try {
+                for await (const chunk of transport(req)) {
+                    yielded = true;
+                    yield chunk;
+                }
+                return;
+            }
+            catch (err) {
+                if (!isColdStartRefusal(err) || yielded || attempt >= attempts)
+                    throw err;
+                const hintedMs = err.retryAfterSeconds !== undefined ? err.retryAfterSeconds * 1000 : undefined;
+                const waitMs = Math.min(hintedMs ?? baseDelayMs * 2 ** attempt, maxDelayMs);
+                await sleep(waitMs, req.signal);
+                // Aborted mid-wait: surface the refusal that caused the wait rather
+                // than spending a request that `fetch` would reject on the signal.
+                if (req.signal.aborted)
+                    throw err;
+            }
+        }
+    };
+}

package/dist/sse.d.ts

@@ -3,7 +3,7 @@
  * platform dependencies — unit-tested in isolation (`sse.test.ts`) and shared
  * verbatim across web (Studio) and React-Native (Portal).
  */
-import type { ProfileConsentRequest, ProfileLinkRequest } from "./types";
+import type { ProfileConsentRequest, ProfileLinkRequest } from "./types.js";
 export interface ParsedSseEvent {
     event: string;
     data: unknown;

package/dist/sse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAEzE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAqBzF;AAsBD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAU1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAmC1D;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI1E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,qBAAqB,GAAG,IAAI,CAO/E;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,GAAG,IAAI,CAOzE"}
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE5E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAqBzF;AAsBD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAU1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAmC1D;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI1E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,qBAAqB,GAAG,IAAI,CAO/E;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,GAAG,IAAI,CAOzE"}

package/dist/transport.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The web SSE invoke transport, and the guest-identity wire pieces it shares
+ * with the read-plane adapters.
+ *
+ * Its own module (rather than living in `./web-adapters.ts`) for the same
+ * reason `AgentResponseError` lives in `./errors.ts`, one level down: the
+ * web-adapter bundle takes VALUE imports of `@guuey/mcp-apps-host` (the
+ * ui-resource reader / action-relay assemblies), so a consumer that only
+ * wants the transport — a custom chat surface with its own card layer, or
+ * none — would drag the whole host-role graph into its build, and any
+ * version skew between the two packages becomes that consumer's build
+ * failure (guuey#186 G2). This module's import closure is
+ * `types`/`errors`/`saturation-retry` only; `./web-adapters.ts` imports
+ * from HERE, never the reverse, and `@guuey/agent-client/transport`
+ * publishes exactly this graph.
+ */
+import type { InvokeRequest, InvokeTransport } from "./types.js";
+import { type ColdStartRetryOptions, type SaturationRetryOptions } from "./saturation-retry.js";
+/**
+ * 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.
+ */
+export declare const GUEST_HEADER = "x-guuey-guest";
+/**
+ * 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 package 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.
+ */
+export declare function sendableGuestSecret(secret: string | null | undefined): string | null;
+/** Options for {@link fetchStreamTransport}. */
+export interface FetchStreamTransportOptions extends SaturationRetryOptions {
+    /**
+     * Bounded retry on cold-start 503s — the envelope-less refusal an embed
+     * eats for ~30–60s after the agent redeploys (guuey#186 Gap 3). ON by
+     * default (small budget: 3 attempts, 2s/4s/8s) for parity with guuey's
+     * first-party embeds; pass `false` to disable, or options to re-budget.
+     * See {@link withColdStartRetry} for exactly what matches (and what
+     * deliberately stays with the saturation policy instead).
+     */
+    coldStartRetry?: ColdStartRetryOptions | false;
+    /**
+     * Injectable bearer provider (guuey#186 Gap 4) — identity is a transport
+     * concern (see {@link InvokeTransport}: "owns headers + identity
+     * entirely"), and a harness or non-React host holds credentials in its own
+     * lifecycle, not in a closure minted once at page load. Resolved PER
+     * ATTEMPT, before each request — a retry after a backoff wait re-reads it,
+     * so a token that expired during the wait is refreshed rather than
+     * replayed. When present it takes precedence over the positional
+     * `accessToken`; resolving `null` falls through to the guest secret /
+     * cookie chain exactly as a null `accessToken` does (and carries the same
+     * silent-anonymous-downgrade hazard the `createWebAdapters` docs warn
+     * about). A throw propagates and fails the invoke — deliberately not
+     * caught, for the same reason as `getGuestSecret` there.
+     */
+    getBearer?: () => string | null | Promise<string | null>;
+}
+/**
+ * The web SSE transport: {@link streamInvokeOnce} under the shared
+ * {@link withSaturationRetry} wrapper, itself under {@link withColdStartRetry}.
+ * Every consumer of this transport (Studio, the widget, anything built on
+ * `createWebAdapters`) therefore inherits the single `POD_SATURATED` retry AND
+ * the bounded cold-start 503 retry, the same pair Portal's React-Native
+ * transport wears — see the wrappers' docblocks for which refusals retry,
+ * which deliberately do not, and why both retries are invisible to the hook.
+ * Both wrappers guard on "nothing yielded yet": once a chunk has streamed,
+ * NOTHING re-POSTs.
+ */
+export declare function fetchStreamTransport(req: InvokeRequest, accessToken?: string | null, guestSecret?: string | null, options?: FetchStreamTransportOptions): AsyncIterable<string>;
+/**
+ * Wrap a transport so every yielded chunk ALSO pings `onChunk` — the
+ * byte-level liveness signal `useAgentInvoke`'s stall watchdog runs on
+ * (guuey#192). Purely observational: chunks pass through unchanged, errors
+ * and completion propagate untouched, and the wrapper adds no timers of its
+ * own — the OBSERVER owns the clock, this module only reports activity. The
+ * first ping doubles as the "first byte seen" arming signal, which is why
+ * the watchdog never fires during a silent cold start: no bytes, no ping,
+ * no armed timer (that phase belongs to {@link withColdStartRetry} and the
+ * user's own abort).
+ */
+export declare function withActivityObserver(transport: InvokeTransport, onChunk: () => void): InvokeTransport;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEjE,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC5B,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,kBAAkB,CAAC;AAgB5C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAEpF;AAoHD,gDAAgD;AAChD,MAAM,WAAW,2BAA4B,SAAQ,sBAAsB;IACzE;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAC/C;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,aAAa,EAClB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,OAAO,GAAE,2BAAgC,GACxC,aAAa,CAAC,MAAM,CAAC,CAcvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,MAAM,IAAI,GAClB,eAAe,CAOjB"}