@guuey/agent-client 0.3.0 → 0.4.0

package/dist/useAgentInvoke.js

@@ -2,7 +2,7 @@
  * useAgentInvoke — the base-platform chat client.
  *
  * Speaks the nocode-runtime pod's Bedrock-style SSE contract (NOT the parked
- * ggui generative-UI protocol that `@ggui-ai/react`'s useInvoke targets):
+ * ggui generative-UI protocol that `@ggui-ai/mcp-apps-react`'s useInvoke targets):
  *
  *   POST {endpointUrl}/agent/invoke
  *     body: { input, threadId?, clientMessageId }
@@ -23,8 +23,9 @@
  */
 import { useCallback, useEffect, useRef, useState } from "react";
 import { Reducer } from "@silverprotocol/core";
-import { parseConsentRequest, parseLinkRequest, parseSseEvents, reduceAssistantText, stringField, } from "./sse";
-import { ingestMessageFrame } from "./blocks";
+import { parseConsentRequest, parseLinkRequest, parseSseEvents, reduceAssistantText, stringField, } from "./sse.js";
+import { ingestMessageFrame } from "./blocks.js";
+import { AgentResponseError } from "./errors.js";
 function threadStorageKey(appId) {
     return `guuey:thread:${appId ?? "default"}`;
 }
@@ -51,6 +52,10 @@ export function useAgentInvoke(opts) {
     const [status, setStatus] = useState("ready");
     const [activeTool, setActiveTool] = useState(null);
     const [error, setError] = useState(null);
+    // The pod's wire code for whatever put `error` there, when the failure
+    // carried one (see the return-type contract). Moves in lockstep with
+    // `error` — every set/clear of one touches the other.
+    const [errorCode, setErrorCode] = useState(null);
     const [threadId, setThreadId] = useState(null);
     // Opt-in block-preserving transcript. `reduceResult` follows the
     // null-until-first-valid-AgEvent contract documented on the return type: it
@@ -102,6 +107,7 @@ export function useAgentInvoke(opts) {
         setThreadId(null);
         setMessages([]);
         setError(null);
+        setErrorCode(null);
         setStatus("ready");
         setActiveTool(null);
         // Fresh conversation → drop the old fold; the reducer is rebuilt lazily on
@@ -192,6 +198,7 @@ export function useAgentInvoke(opts) {
         void adaptersRef.current.storage.save(threadStorageKey(appId), "");
         setMessages([]);
         setError(null);
+        setErrorCode(null);
         setStatus("ready");
         setActiveTool(null);
         // Re-create the reducer for the new conversation (rebuilt lazily on the
@@ -212,6 +219,7 @@ export function useAgentInvoke(opts) {
         if (!endpointUrl || !input.trim() || status !== "ready")
             return;
         setError(null);
+        setErrorCode(null);
         setStatus("connecting");
         setMessages((prev) => [...prev, { role: "user", text: input }, { role: "assistant", text: "" }]);
         const controller = new AbortController();
@@ -305,7 +313,12 @@ export function useAgentInvoke(opts) {
                         }
                     }
                     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
@@ -331,6 +344,12 @@ export function useAgentInvoke(opts) {
         catch (e) {
             if (!controller.signal.aborted) {
                 setError(e instanceof Error ? e.message : "failed to reach agent");
+                // Pre-stream refusals arrive as a thrown AgentResponseError carrying
+                // the pod's structured code (a transport-level saturation retry has
+                // already happened and failed by the time one surfaces here). Any
+                // 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);
             }
         }
         finally {
@@ -356,6 +375,7 @@ export function useAgentInvoke(opts) {
         status,
         activeTool,
         error,
+        errorCode,
         threadId,
         abort,
         reset,

package/dist/web-adapters.d.ts

@@ -6,43 +6,22 @@
  * functions — never at module load — so this file is import-safe under SSR
  * (the functions guard on `typeof window`).
  */
-import type { AgentInvokeAdapters, InvokeRequest, ThreadIdStore } from "./types";
-/**
- * Thrown when the pod returns a non-2xx status on `/agent/invoke` (before any
- * SSE stream opens). Carries the pod's structured `{ code, message }` when
- * present — e.g. a `QUOTA_EXCEEDED` 429 whose message ("…reached its plan
- * generation limit…") the chat UI should surface — falling back to the bare
- * status for non-JSON failures.
- */
-export declare class AgentResponseError extends Error {
-    readonly status: number;
-    readonly code?: string | undefined;
-    constructor(message: string, status: number, code?: string | undefined);
-}
+import { type McpToolCallResult, type ResolvedViewMount, type UiActionRequest } from "@guuey/mcp-apps-host";
+import type { AgentInvokeAdapters, InvokeRequest, ThreadIdStore } from "./types.js";
+import { type SaturationRetryOptions } from "./saturation-retry.js";
 /** Persists the threadId in `window.localStorage` (synchronously). */
 export declare const localStorageThreadStore: ThreadIdStore;
 /** Crypto-strong client-message id, with a non-crypto fallback. */
 export declare function webGenerateId(): string;
 /**
- * Web SSE transport. 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).
+ * 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 declare function fetchStreamTransport(req: InvokeRequest, accessToken?: string | null, guestSecret?: string | null): AsyncGenerator<string>;
+export declare function fetchStreamTransport(req: InvokeRequest, accessToken?: string | null, guestSecret?: string | null, options?: SaturationRetryOptions): AsyncIterable<string>;
 export interface CreateWebAdaptersOptions {
     /**
      * Public read-plane base (ending in `/v1`) for transcript history. When
@@ -136,36 +115,46 @@ export interface CreateUiResourceReaderOptions {
     fetchImpl?: typeof fetch;
 }
 /**
- * Build a `@guuey/mcp-apps-host` `UiResourceReader` over guuey's
- * authenticated resources/read proxy (guuey#122 Gap 1:
- * `GET /v1/threads/:threadId/ui-resource?uri=…`).
+ * Build a `UiResourceReader` over guuey's authenticated resources/read proxy
+ * (guuey#122 Gap 1: `GET /v1/threads/:threadId/ui-resource?uri=…`).
  *
+ * This is `@guuey/mcp-apps-host`'s `createMcpUiResourceReader` assembly over
+ * a guuey-platform transport (guuey#127) — channel resolution and payload
+ * narrowing live in the host package; only the transport is guuey-shaped.
  * The proxy owns EVERYTHING trust-shaped: caller identity (the same three
  * families as the history read), thread ownership, the locator-to-thread
- * scope guard, and the per-user federation mint. This reader only carries
+ * scope guard, and the per-user federation mint. This transport only carries
  * the surface's existing credential and maps EVERY non-OK — 401/403/404/502
  * alike — to `undefined`: deny is byte-identical to a miss, and a miss
  * renders the host's placeholder, never an error surface.
- *
- * Channel resolution is the phase-1 heuristic: a `ui://ggui/…` uri mounts in
- * the ggui-CSP sandbox page (`channel: "ggui"`), anything else in the
- * self-only page (`channel: "inline"`). Phase 2 (per-resource declared-CSP
- * construction from the response `_meta.ui.csp`) retires the heuristic —
- * conformance map, retirement step 3.
  */
+export declare function createUiResourceReader(options: CreateUiResourceReaderOptions): (resourceUri: string) => Promise<ResolvedViewMount | undefined>;
+/** Options for {@link createUiActionRelay} — same credential surface as the reader. */
+export interface CreateUiActionRelayOptions {
+    /** The guuey public API base (`…/v1`). */
+    apiBaseUrl: string;
+    /** The thread whose persisted cards this relay may act for. */
+    threadId: string;
+    /** Signed-in bearer — wins over the guest secret (same rule as the transport). */
+    getAccessToken?: (opts?: {
+        forceRefresh?: boolean;
+    }) => Promise<string | null>;
+    /** Caller-owned anonymous guest secret (widget / guest chat). */
+    guestSecret?: string | null;
+    /** Injectable for tests. */
+    fetchImpl?: typeof fetch;
+}
 /**
- * The mount the reader resolves — structurally assignable to
- * `@guuey/mcp-apps-host`'s `ViewMount` mountable arms (typed inline so this
- * package carries no dependency on the host package; hosts that consume
- * both see one structural type).
+ * Build the card action relay over guuey's authenticated `tools/call` proxy
+ * (guuey#158: `POST /v1/threads/:threadId/ui-action`) — the mirror of
+ * {@link createUiResourceReader}. Allowlisting, arm narrowing, and the
+ * never-reject contract live in `@guuey/mcp-apps-host`'s
+ * `createMcpUiActionRelay`; only the transport is guuey-shaped. The proxy
+ * owns EVERYTHING trust-shaped (identity, thread ownership, the
+ * locator-to-thread guard, its own server-side allowlist, the per-user
+ * federation mint) — and every non-OK here collapses to `undefined`, which
+ * the host relay answers in-band as an `isError` result, never a thrown
+ * error into the sandbox bridge.
  */
-export interface ResolvedUiResourceMount {
-    channel: "inline" | "ggui";
-    resource: {
-        uri: string;
-        mimeType?: string;
-        text: string;
-    };
-}
-export declare function createUiResourceReader(options: CreateUiResourceReaderOptions): (resourceUri: string) => Promise<ResolvedUiResourceMount | undefined>;
+export declare function createUiActionRelay(options: CreateUiActionRelayOptions): (request: UiActionRequest) => Promise<McpToolCallResult>;
 //# sourceMappingURL=web-adapters.d.ts.map

package/dist/web-adapters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web-adapters.d.ts","sourceRoot":"","sources":["../src/web-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EAEb,aAAa,EACd,MAAM,SAAS,CAAC;AAGjB;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;gBAFtB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,YAAA;CAKzB;AAED,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,EAAE,aAiBrC,CAAC;AAEF,mEAAmE;AACnE,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAwCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAuB,oBAAoB,CACzC,GAAG,EAAE,aAAa,EAClB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAC1B,cAAc,CAAC,MAAM,CAAC,CA4CxB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACtC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,GAAE,wBAA6B,GAClC,mBAAmB,CAwErB;AAED,mGAAmG;AACnG,MAAM,WAAW,6BAA6B;IAC5C,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/E,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4BAA4B;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,QAAQ,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5D;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAAC,CAkDvE"}
+{"version":3,"file":"web-adapters.d.ts","sourceRoot":"","sources":["../src/web-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAIL,KAAK,iBAAiB,EAEtB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EAEb,aAAa,EACd,MAAM,YAAY,CAAC;AAGpB,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,uBAAuB,CAAC;AAE/B,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,EAAE,aAiBrC,CAAC;AAEF,mEAAmE;AACnE,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAsHD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,aAAa,EAClB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,OAAO,GAAE,sBAA2B,GACnC,aAAa,CAAC,MAAM,CAAC,CAKvB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;;;;;;;OAiBG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACtC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,GAAE,wBAA6B,GAClC,mBAAmB,CAwErB;AAED,mGAAmG;AACnG,MAAM,WAAW,6BAA6B;IAC5C,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/E,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4BAA4B;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAoDjE;AAED,uFAAuF;AACvF,MAAM,WAAW,0BAA0B;IACzC,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/E,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4BAA4B;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,iBAAiB,CAAC,CA+C1D"}

package/dist/web-adapters.js

@@ -1,21 +1,15 @@
-import { fetchThreadHistory, HistoryUnauthorizedError } from "./history";
 /**
- * Thrown when the pod returns a non-2xx status on `/agent/invoke` (before any
- * SSE stream opens). Carries the pod's structured `{ code, message }` when
- * present — e.g. a `QUOTA_EXCEEDED` 429 whose message ("…reached its plan
- * generation limit…") the chat UI should surface — falling back to the bare
- * status for non-JSON failures.
+ * Web (browser / Next.js) host adapters for {@link useAgentInvoke}.
+ *
+ * Studio builds its bundle via {@link createWebAdapters}. The implementations
+ * touch `window.localStorage`, `crypto`, and `fetch` only inside their
+ * functions — never at module load — so this file is import-safe under SSR
+ * (the functions guard on `typeof window`).
  */
-export class AgentResponseError extends Error {
-    status;
-    code;
-    constructor(message, status, code) {
-        super(message);
-        this.status = status;
-        this.code = code;
-        this.name = "AgentResponseError";
-    }
-}
+import { createMcpUiActionRelay, createMcpUiResourceReader, } from "@guuey/mcp-apps-host";
+import { fetchThreadHistory, HistoryUnauthorizedError } from "./history.js";
+import { AgentResponseError } from "./errors.js";
+import { parseRetryAfterSeconds, withSaturationRetry, } from "./saturation-retry.js";
 /** Persists the threadId in `window.localStorage` (synchronously). */
 export const localStorageThreadStore = {
     load(key) {
@@ -82,7 +76,11 @@ function sendableGuestSecret(secret) {
     return typeof secret === "string" && GUEST_SECRET_RE.test(secret) ? secret : null;
 }
 /**
- * Web SSE transport. Exactly ONE identity carrier per request, in order:
+ * 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
@@ -100,7 +98,7 @@ function sendableGuestSecret(secret) {
  *
  * Reads the body via `ReadableStream.getReader()` (browser).
  */
-export async function* fetchStreamTransport(req, accessToken, guestSecret) {
+async function* streamInvokeOnce(req, accessToken, guestSecret) {
     const headers = {
         "Content-Type": "application/json",
         Accept: "text/event-stream",
@@ -137,7 +135,7 @@ export async function* fetchStreamTransport(req, accessToken, guestSecret) {
                 code = body.code;
             }
         }
-        throw new AgentResponseError(message, resp.status, code);
+        throw new AgentResponseError(message, resp.status, code, parseRetryAfterSeconds(resp.headers.get("Retry-After")));
     }
     const reader = resp.body.getReader();
     const decoder = new TextDecoder();
@@ -148,6 +146,17 @@ export async function* fetchStreamTransport(req, accessToken, guestSecret) {
         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, accessToken, guestSecret, options = {}) {
+    return withSaturationRetry((attempt) => streamInvokeOnce(attempt, accessToken, guestSecret), options)(req);
+}
 /**
  * Build the web host-adapter bundle for {@link useAgentInvoke}. Pass an
  * access-token resolver and/or a guest-secret resolver (plus the read-plane
@@ -227,9 +236,23 @@ export function createWebAdapters(opts = {}) {
     }
     return adapters;
 }
+/**
+ * Build a `UiResourceReader` over guuey's authenticated resources/read proxy
+ * (guuey#122 Gap 1: `GET /v1/threads/:threadId/ui-resource?uri=…`).
+ *
+ * This is `@guuey/mcp-apps-host`'s `createMcpUiResourceReader` assembly over
+ * a guuey-platform transport (guuey#127) — channel resolution and payload
+ * narrowing live in the host package; only the transport is guuey-shaped.
+ * The proxy owns EVERYTHING trust-shaped: caller identity (the same three
+ * families as the history read), thread ownership, the locator-to-thread
+ * scope guard, and the per-user federation mint. This transport only carries
+ * the surface's existing credential and maps EVERY non-OK — 401/403/404/502
+ * alike — to `undefined`: deny is byte-identical to a miss, and a miss
+ * renders the host's placeholder, never an error surface.
+ */
 export function createUiResourceReader(options) {
     const fetchImpl = options.fetchImpl ?? fetch;
-    return async (resourceUri) => {
+    const readResource = async (resourceUri) => {
         const headers = {};
         const token = options.getAccessToken ? await options.getAccessToken() : null;
         const guest = sendableGuestSecret(options.guestSecret);
@@ -272,15 +295,79 @@ export function createUiResourceReader(options) {
         catch {
             return undefined;
         }
-        if (typeof body.uri !== "string" || typeof body.text !== "string")
+        // The proxy passes the blob arm through (a blob-only resource is not
+        // silently a miss — its route contract); mirror that here.
+        if (typeof body.uri !== "string")
+            return undefined;
+        if (typeof body.text !== "string" && typeof body.blob !== "string")
             return undefined;
         return {
-            channel: resourceUri.startsWith("ui://ggui/") ? "ggui" : "inline",
-            resource: {
-                uri: body.uri,
-                ...(typeof body.mimeType === "string" ? { mimeType: body.mimeType } : {}),
-                text: body.text,
-            },
+            uri: body.uri,
+            ...(typeof body.mimeType === "string" ? { mimeType: body.mimeType } : {}),
+            ...(typeof body.text === "string" ? { text: body.text } : {}),
+            ...(typeof body.blob === "string" ? { blob: body.blob } : {}),
         };
     };
+    return createMcpUiResourceReader({ readResource });
+}
+/**
+ * Build the card action relay over guuey's authenticated `tools/call` proxy
+ * (guuey#158: `POST /v1/threads/:threadId/ui-action`) — the mirror of
+ * {@link createUiResourceReader}. Allowlisting, arm narrowing, and the
+ * never-reject contract live in `@guuey/mcp-apps-host`'s
+ * `createMcpUiActionRelay`; only the transport is guuey-shaped. The proxy
+ * owns EVERYTHING trust-shaped (identity, thread ownership, the
+ * locator-to-thread guard, its own server-side allowlist, the per-user
+ * federation mint) — and every non-OK here collapses to `undefined`, which
+ * the host relay answers in-band as an `isError` result, never a thrown
+ * error into the sandbox bridge.
+ */
+export function createUiActionRelay(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const callTool = async (uri, name, args) => {
+        const headers = { "content-type": "application/json" };
+        const token = options.getAccessToken ? await options.getAccessToken() : null;
+        const guest = sendableGuestSecret(options.guestSecret);
+        if (token) {
+            headers["authorization"] = `Bearer ${token}`;
+        }
+        else if (guest) {
+            headers[GUEST_HEADER] = guest;
+        }
+        const requestUrl = `${options.apiBaseUrl}/threads/${encodeURIComponent(options.threadId)}/ui-action`;
+        const body = JSON.stringify({ uri, name, ...(args !== undefined ? { arguments: args } : {}) });
+        let res;
+        try {
+            res = await fetchImpl(requestUrl, { method: "POST", headers, body });
+        }
+        catch {
+            return undefined; // transport failure — the host relay answers in-band
+        }
+        // One forceRefresh retry on 401 with a bearer in play — the same
+        // expired-but-refreshable recovery the reader performs.
+        if (res.status === 401 && options.getAccessToken) {
+            const fresh = await options.getAccessToken({ forceRefresh: true }).catch(() => null);
+            if (fresh) {
+                try {
+                    res = await fetchImpl(requestUrl, {
+                        method: "POST",
+                        headers: { ...headers, authorization: `Bearer ${fresh}` },
+                        body,
+                    });
+                }
+                catch {
+                    return undefined;
+                }
+            }
+        }
+        if (!res.ok)
+            return undefined;
+        try {
+            return (await res.json());
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return createMcpUiActionRelay({ callTool });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/agent-client",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Client SDK for Guuey's agent runtime: the `useAgentInvoke` React hook + pure SSE helpers that speak the /agent/invoke streaming contract, plus the paginated thread-history read plane. Host adapters (storage / id / transport) are injected, so it runs on web (Next) and React Native alike.",
   "license": "MIT",
   "type": "module",
@@ -28,7 +28,8 @@
     }
   },
   "dependencies": {
-    "@silverprotocol/core": "0.4.1"
+    "@silverprotocol/core": "0.4.1",
+    "@guuey/mcp-apps-host": "0.4.0"
   },
   "peerDependencies": {
     "react": ">=18"
@@ -55,14 +56,14 @@
     "client"
   ],
   "homepage": "https://guuey.com",
-  "bugs": {
-    "url": "https://github.com/loqu-co/guuey/issues"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/withguuey/guuey-sdks.git",
     "directory": "packages/agent-client"
   },
+  "bugs": {
+    "url": "https://github.com/withguuey/guuey-sdks/issues"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsc --watch",

package/src/error-codes.ts

@@ -0,0 +1,58 @@
+/**
+ * The pod's error-envelope wire codes, TRANSCRIBED.
+ *
+ * The source of truth is the runtime's own private module
+ * (`backend/services/nocode-runtime/src/error-codes.ts`). This package is
+ * published to npm and cannot take a `@guuey-private` dependency, so it keeps
+ * its own copy — the same arrangement as {@link GUEST_HEADER} in
+ * `./web-adapters.ts` and `@guuey/host`'s mirrored fs-contract constants. The
+ * copies are not trusted to prose alone: `agent-client-codes.sync.test.ts` in
+ * the runtime package (which can import BOTH) asserts they stay identical, so
+ * renaming a code on either side fails that test rather than silently breaking
+ * a client branch.
+ *
+ * WIRE CONTRACT (what these codes appear in):
+ *
+ *  - a pre-stream refusal — `{ "code": …, "message": … }` with an HTTP status,
+ *    parsed into {@link AgentResponseError};
+ *  - an in-band failure — `event: error` / `data: { code, message }`, surfaced
+ *    as `useAgentInvoke`'s `errorCode`.
+ *
+ * Both channels carry the SAME vocabulary, which is why one mirror serves them.
+ */
+export const AGENT_ERROR_CODES = {
+  /** No usable identity on a surface that requires one. */
+  UNAUTHORIZED: "UNAUTHORIZED",
+  /** The invoke body did not parse / validate. */
+  INVALID_REQUEST: "INVALID_REQUEST",
+  /** The builder turned anonymous access off for this agent. */
+  GUEST_ACCESS_DISABLED: "GUEST_ACCESS_DISABLED",
+  /** The caller (or the app) is out of plan allowance — the upgrade prompt. */
+  QUOTA_EXCEEDED: "QUOTA_EXCEEDED",
+  /** The app hit its builder-set managed spend cap. */
+  MANAGED_SPEND_CAP: "MANAGED_SPEND_CAP",
+  /**
+   * The pod is at its concurrent-turn cap (scaling S1-F3). A 503 carrying a
+   * `Retry-After` hint, and the ONE code {@link fetchStreamTransport} retries
+   * by itself — see its docblock for the single-attempt rule.
+   */
+  POD_SATURATED: "POD_SATURATED",
+  /**
+   * The pod took SIGTERM and refuses NEW turns while in-flight ones finish.
+   * Also a 503 + `Retry-After`, but deliberately NOT auto-retried (the
+   * endpoint pull re-routes the next request; retrying into the same pod is
+   * the one thing guaranteed not to help).
+   */
+  DRAINING: "DRAINING",
+  /** Refused for this caller — e.g. the link-prompt dismiss route's byo-only rule. */
+  FORBIDDEN: "FORBIDDEN",
+  /** The turn ran past the pod's wall-clock budget. */
+  TIMEOUT: "TIMEOUT",
+  /** A guuey-side dependency failed (not the agent's own code). */
+  PLATFORM_ERROR: "PLATFORM_ERROR",
+  /** Unclassified pod failure. */
+  INTERNAL: "INTERNAL",
+} as const;
+
+/** One of the pod's wire codes — see {@link AGENT_ERROR_CODES}. */
+export type AgentErrorCode = (typeof AGENT_ERROR_CODES)[keyof typeof AGENT_ERROR_CODES];

package/src/errors.ts

@@ -0,0 +1,35 @@
+/**
+ * Error types the transports throw and the hook branches on.
+ *
+ * Its own module (rather than living in `./web-adapters.ts`) so `useAgentInvoke`
+ * — which must stay platform-agnostic — can `instanceof`-narrow a caught error
+ * without pulling the web adapter bundle (`fetch`, the history reader,
+ * `@guuey/mcp-apps-host`) into a React-Native build.
+ */
+
+/**
+ * Thrown when the pod returns a non-2xx status on `/agent/invoke` (before any
+ * SSE stream opens). Carries the pod's structured `{ code, message }` when
+ * present — e.g. a `QUOTA_EXCEEDED` 429 whose message ("…reached its plan
+ * generation limit…") the chat UI should surface — falling back to the bare
+ * status for non-JSON failures. See `AGENT_ERROR_CODES` for the vocabulary.
+ */
+export class AgentResponseError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly code?: string,
+    /**
+     * The response's `Retry-After` hint in whole seconds, when it sent a
+     * parseable one. The pod attaches it to its two 503 refusals
+     * (`POD_SATURATED`, `DRAINING`) and exposes the header across origins via
+     * `Access-Control-Expose-Headers`, so a browser client can actually read
+     * it. `undefined` when the header was absent, malformed, or in the
+     * HTTP-date form the pod never emits.
+     */
+    readonly retryAfterSeconds?: number,
+  ) {
+    super(message);
+    this.name = "AgentResponseError";
+  }
+}

package/src/history.ts

@@ -11,7 +11,7 @@
  * has its own copy today and can migrate onto this later.
  */
 import type { AgMessage, JsonValue } from "@silverprotocol/core";
-import type { AgentMessage, HistoryCard, HistoryLoadResult } from "./types";
+import type { AgentMessage, HistoryCard, HistoryLoadResult } from "./types.js";
 
 /** One row of `GET /v1/threads/:id/messages`. */
 export interface ThreadHistoryRow {

package/src/index.ts

@@ -6,19 +6,34 @@ export {
   parseConsentRequest,
   parseLinkRequest,
   type ParsedSseEvent,
-} from "./sse";
-export { dismissLinkPrompt } from "./link-prompt";
+} from "./sse.js";
+export { dismissLinkPrompt } from "./link-prompt.js";
 export {
+  createUiActionRelay,
+  type CreateUiActionRelayOptions,
   createUiResourceReader,
   type CreateUiResourceReaderOptions,
-  type ResolvedUiResourceMount,
   createWebAdapters,
   localStorageThreadStore,
   webGenerateId,
   fetchStreamTransport,
-  AgentResponseError,
   type CreateWebAdaptersOptions,
-} from "./web-adapters";
+} from "./web-adapters.js";
+// The `POD_SATURATED` single-retry wrapper, transport-agnostic: a host that
+// brings its own `fetch` (Portal's React-Native transport) wraps it to wear the
+// same semantics as the web transport instead of hand-rolling a second copy.
+// `parseRetryAfterSeconds` ships with it because filling
+// `AgentResponseError.retryAfterSeconds` the same way is what makes the wrapper
+// honour the pod's hint.
+export {
+  withSaturationRetry,
+  parseRetryAfterSeconds,
+  type SaturationRetryOptions,
+} from "./saturation-retry.js";
+export { AgentResponseError } from "./errors.js";
+// The pod's wire-code vocabulary, mirrored — branch on these instead of
+// re-typing the string literals (see the module docblock for the sync guard).
+export { AGENT_ERROR_CODES, type AgentErrorCode } from "./error-codes.js";
 export {
   fetchThreadHistory,
   threadHistoryRowsToMessages,
@@ -26,13 +41,13 @@ export {
   HistoryUnauthorizedError,
   type ThreadHistoryRow,
   type ThreadHistoryFetchOptions,
-} from "./history";
-export { ingestMessageFrame } from "./blocks";
+} from "./history.js";
+export { ingestMessageFrame } from "./blocks.js";
 // Pure block-walk / resource-narrowing helpers for a block-preserving renderer
 // (shared by Studio's `AgentBlocks` and Portal-web's agent chat). React-free.
 // Transcript labeling/ordering helpers (mount narrowing itself moved to
 // @guuey/mcp-apps-host — the SEP-1865 Host role package; import it directly).
-export { sortHistoryCards, toolNameFor } from "./history";
+export { sortHistoryCards, toolNameFor } from "./history.js";
 // Re-export the AgJSON types the block-preserving transcript surfaces, so
 // consumers can name `reduceResult` / block types without a direct
 // `@silverprotocol/core` import.
@@ -52,4 +67,4 @@ export type {
   HistoryLoadResult,
   UseAgentInvokeOptions,
   UseAgentInvokeReturn,
-} from "./types";
+} from "./types.js";

package/src/react.ts

@@ -6,7 +6,7 @@
  * 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 } from "./useAgentInvoke.js";
 // The block-preserving transcript surfaces `AgReduceResult`; re-export it (and
 // `AgEvent`) here so `./react` consumers can type `reduceResult` without a
 // direct `@silverprotocol/core` import.