@guuey/agent-client 0.1.0 → 0.2.1

package/dist/web-adapters.js

@@ -1,4 +1,4 @@
-import { fetchThreadHistory } from "./history";
+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
@@ -47,14 +47,60 @@ export function webGenerateId() {
     return `cmid-${Date.now()}-${Math.floor(Math.random() * 1e9)}`;
 }
 /**
- * Web SSE transport. When `accessToken` is present the pod identifies the
- * caller by their verified Cognito access token (the same identity the
- * history read plane uses, so persisted threads round-trip on reload).
- * Otherwise it falls back to `credentials: "include"`, which round-trips the
- * HttpOnly `guuey_guest` cookie the pod mints for anonymous browser callers.
+ * 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) {
+    return typeof secret === "string" && GUEST_SECRET_RE.test(secret) ? secret : null;
+}
+/**
+ * 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).
  */
-export async function* fetchStreamTransport(req, accessToken) {
+export async function* fetchStreamTransport(req, accessToken, guestSecret) {
     const headers = {
         "Content-Type": "application/json",
         Accept: "text/event-stream",
@@ -65,9 +111,13 @@ export async function* fetchStreamTransport(req, accessToken) {
         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";
     }
@@ -100,34 +150,78 @@ export async function* fetchStreamTransport(req, accessToken) {
 }
 /**
  * Build the web host-adapter bundle for {@link useAgentInvoke}. Pass an
- * access-token resolver (and the read-plane base) to authenticate the chat
- * transport and enable transcript restore on reload; omit them for an
- * anonymous, history-less bundle.
+ * access-token resolver and/or a guest-secret resolver (plus the read-plane
+ * base) to give the chat transport an identity the read plane can also see,
+ * which is what enables transcript restore on reload; omit both for a
+ * cookie-only, history-less bundle.
  */
 export function createWebAdapters(opts = {}) {
-    const { apiBaseUrl, getAccessToken } = opts;
+    const { apiBaseUrl, getAccessToken, getGuestSecret } = opts;
     const transport = async function* (req) {
         const token = getAccessToken ? await getAccessToken() : null;
-        yield* fetchStreamTransport(req, token);
+        // 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);
     };
     const adapters = {
         storage: localStorageThreadStore,
         generateId: webGenerateId,
         transport,
     };
-    if (apiBaseUrl && getAccessToken) {
+    // History needs an identity the READ plane can resolve: a Bearer or the
+    // `x-guuey-guest` header. Either resolver can supply one, so either one
+    // installs the adapter; a cookie-only caller is unidentifiable there and
+    // gets no adapter at all.
+    if (apiBaseUrl && (getAccessToken || getGuestSecret)) {
         adapters.history = {
             load: async (threadId) => {
-                const token = await getAccessToken();
+                // Same precedence, and the same one-carrier rule, as the transport:
+                // a bearer wins over the guest header, and the two never combine.
+                if (getAccessToken) {
+                    const token = await getAccessToken();
+                    if (token) {
+                        try {
+                            return await fetchThreadHistory({
+                                baseUrl: apiBaseUrl,
+                                threadId,
+                                includeCards: true,
+                                requestInit: { headers: { Authorization: `Bearer ${token}` } },
+                            });
+                        }
+                        catch (err) {
+                            if (!(err instanceof HistoryUnauthorizedError))
+                                throw err;
+                            // The one retry the send path already gets on a 401
+                            // (`withIdentifiedToken`): this read runs from a mount effect,
+                            // before the send path has asked anyone for anything, so a
+                            // token cached earlier can be the exact stale value that just
+                            // failed. `forceRefresh` is the signal that asks past whatever
+                            // cache the resolver keeps instead of returning that same dead
+                            // value.
+                            const fresh = await getAccessToken({ forceRefresh: true });
+                            if (!fresh)
+                                throw err; // nothing fresher to retry with — the ORIGINAL 401 is the honest cause
+                            return fetchThreadHistory({
+                                baseUrl: apiBaseUrl,
+                                threadId,
+                                includeCards: true,
+                                requestInit: { headers: { Authorization: `Bearer ${fresh}` } },
+                            });
+                        }
+                    }
+                }
+                const guest = sendableGuestSecret(getGuestSecret?.());
+                if (guest) {
+                    return fetchThreadHistory({
+                        baseUrl: apiBaseUrl,
+                        threadId,
+                        includeCards: true,
+                        requestInit: { headers: { [GUEST_HEADER]: guest } },
+                    });
+                }
                 // No readable identity → leave the chat empty (skip) rather than
                 // `gone`, which would clear the persisted threadId.
-                if (!token)
-                    return { messages: [] };
-                return fetchThreadHistory({
-                    baseUrl: apiBaseUrl,
-                    threadId,
-                    requestInit: { headers: { Authorization: `Bearer ${token}` } },
-                });
+                return { messages: [] };
             },
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/agent-client",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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,7 @@
     }
   },
   "dependencies": {
-    "@silverprotocol/core": "0.3.2"
+    "@silverprotocol/core": "0.4.1"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/block-ui.ts

@@ -86,7 +86,12 @@ export function scanProviderRawForUiResource(
  * Extract a mountable UI resource from an opaque AgBlock-shaped `JsonValue`
  * (used for persisted card snapshot parts, which arrive untyped). Dispatches
  * by `block.type`:
- *   - `tool-result` → its `uiData` surface channel
+ *   - `tool-result` → its `uiData` surface channel, then a `ui://` resource
+ *     degraded into a `provider-raw` content part — the SAME two channels
+ *     the live path ({@link toolResultUiResource}) mounts. The write side
+ *     (`nocode-runtime`'s `uiCardArtifactsFromMessages`, guuey#86) persists
+ *     card rows for both, so the snapshot arm must mount both or
+ *     provider-raw-only cards rehydrate as placeholders.
  *   - `provider-raw` → a `ui://` resource hiding in `raw`
  *   - `resource`     → a first-class embedded resource (gated on `ui://`)
  * Everything else → `undefined`.
@@ -94,8 +99,19 @@ export function scanProviderRawForUiResource(
 export function blockUiResource(block: JsonValue): McpUiResourcePayload | undefined {
   if (!isJsonObject(block)) return undefined;
   switch (block.type) {
-    case "tool-result":
-      return asUiResource(block.uiData);
+    case "tool-result": {
+      const fromUiData = asUiResource(block.uiData);
+      if (fromUiData) return fromUiData;
+      if (Array.isArray(block.content)) {
+        for (const part of block.content) {
+          if (isJsonObject(part) && part.type === "provider-raw") {
+            const found = scanProviderRawForUiResource(part.raw);
+            if (found) return found;
+          }
+        }
+      }
+      return undefined;
+    }
     case "provider-raw":
       return scanProviderRawForUiResource(block.raw);
     case "resource": {

package/src/card-mount.ts

@@ -0,0 +1,101 @@
+/**
+ * The card-mount dispatcher: ONE narrowing that answers "what, if anything,
+ * does this block mount?" across BOTH generative-UI channels a guuey pod
+ * emits.
+ *
+ *   1. **inline mcp-ui resource** — `{uri, text|blob}` on `uiData`, or a
+ *      `ui://` resource degraded into a `provider-raw` content part. Handled
+ *      verbatim by `block-ui.ts`; this module does not touch that path, it
+ *      only tries it FIRST.
+ *   2. **ggui render** — `uiData.resourceUri` + the `_meta["ai.ggui/render"]`
+ *      bootstrap, mounted through ggui's self-contained shell. See
+ *      `ggui-render.ts`.
+ *
+ * Both channels land on the SAME `McpUiResourcePayload`, which is the whole
+ * point: a host that already mounts inline resources through
+ * `@mcp-ui/client`'s `AppRenderer` in a second-origin sandbox gains ggui cards
+ * without a second mount mechanism, a second iframe contract, or a second
+ * security posture to review.
+ *
+ * Precedence is inline-first and deliberate: an inline resource is the
+ * server's explicit, self-sufficient HTML. A ggui render only ever wins when
+ * there is no inline resource to prefer, so this dispatcher can never change
+ * what an existing inline card renders.
+ *
+ * ## Why the CHANNEL is returned alongside the resource
+ *
+ * The payload alone cannot say where it came from — a ggui shell is a string
+ * of HTML like any other. But a host has one decision that genuinely depends
+ * on the origin of that HTML: WHICH sandbox host page to mount it in. A ggui
+ * shell must load ggui's runtime bundle and open its WSS, so it needs a page
+ * whose CSP names the ggui origins; an inline card is arbitrary tenant HTML
+ * and must keep the self-only page it has always had. Handing back the channel
+ * keeps that one narrowing in one place — the alternative was for every host
+ * to re-run `toolResultGguiRender` beside this call and ask again.
+ */
+import { cardUiResource, toolResultUiResource, type McpUiResourcePayload } from "./block-ui";
+import { blockGguiRender, gguiRenderResource, toolResultGguiRender } from "./ggui-render";
+import type { AgBlock, JsonValue } from "@silverprotocol/core";
+
+/** Which generative-UI channel produced a mount. See this module's header. */
+export type CardMountChannel = "inline" | "ggui";
+
+/** A mountable card: the resource to hand the host, and where it came from. */
+export interface CardMount {
+  /** The payload an mcp-ui host mounts, identical in shape for both channels. */
+  resource: McpUiResourcePayload;
+  /**
+   * `"inline"` — the server's own HTML, untrusted tenant content.
+   * `"ggui"` — a shell that boots the ggui runtime from a platform-pinned
+   * origin, and therefore needs a host page whose CSP allows that origin.
+   */
+  channel: CardMountChannel;
+}
+
+/**
+ * A live `tool-result` block → the card to mount, across both channels.
+ * `undefined` when the block carries no generative UI at all (or carries a
+ * ggui render whose bootstrap did not reach us — see `ggui-render.ts`).
+ */
+export function toolResultCardMount(
+  block: Extract<AgBlock, { type: "tool-result" }>,
+): CardMount | undefined {
+  const inline = toolResultUiResource(block);
+  if (inline) return { resource: inline, channel: "inline" };
+  const ggui = toolResultGguiRender(block);
+  const resource = ggui ? gguiRenderResource(ggui) : undefined;
+  return resource ? { resource, channel: "ggui" } : undefined;
+}
+
+/**
+ * A persisted `HistoryCard`'s `cardSnapshot` → the card to mount, across both
+ * channels.
+ *
+ * The ggui arm is reached only for a snapshot that stored the render's
+ * `_meta`; a bootstrap old enough to have been persisted has an expired
+ * `wsToken` anyway, so in practice a ggui history card resolves to `undefined`
+ * and the host renders its placeholder — honest, and NOT a broken mount.
+ */
+export function cardCardMount(cardSnapshot: JsonValue): CardMount | undefined {
+  const inline = cardUiResource(cardSnapshot);
+  if (inline) return { resource: inline, channel: "inline" };
+  for (const block of snapshotBlocks(cardSnapshot)) {
+    const ggui = blockGguiRender(block);
+    const resource = ggui ? gguiRenderResource(ggui) : undefined;
+    if (resource) return { resource, channel: "ggui" };
+  }
+  return undefined;
+}
+
+/**
+ * The blocks to scan inside a card snapshot: the stored `AgArtifact`'s `parts`
+ * when present, then the snapshot root itself — exactly `cardUiResource`'s own
+ * walk order, so both channels see the same candidates in the same order.
+ */
+function snapshotBlocks(cardSnapshot: JsonValue): JsonValue[] {
+  if (typeof cardSnapshot !== "object" || cardSnapshot === null || Array.isArray(cardSnapshot)) {
+    return [];
+  }
+  const parts = cardSnapshot.parts;
+  return Array.isArray(parts) ? [...parts, cardSnapshot] : [cardSnapshot];
+}

package/src/ggui-render.ts

@@ -0,0 +1,270 @@
+/**
+ * The **ggui render** channel: narrowing + self-contained shell construction
+ * for a generative-UI card produced by the ggui MCP server (`ggui_render`).
+ *
+ * ## Why this is a second channel and not the existing one
+ *
+ * `block-ui.ts`'s original narrowing accepts exactly one shape — an mcp-ui
+ * embedded resource that carries its HTML INLINE (`{uri, text|blob}`). A ggui
+ * render carries no HTML at all. Its `tool.done` looks like this on the wire
+ * (shaped identically to the production capture the widget's fixtures
+ * replay, but with the SAME synthetic ids those redacted fixtures use —
+ * `apps/widget/src/fixtures/issue2627-render-capture.sse.txt` seq 48):
+ *
+ * ```jsonc
+ * {"type":"tool.done", "toolCallId":"toolu_0000…0005",
+ *  "uiData":{"sessionId":"render_0000…0001",
+ *            "resourceUri":"ui://ggui/render/render_0000…0001/c10a2055…", … },
+ *  "_meta":{"ai.ggui/render":{"sessionId":"render_0000…0001","appId":"APP00000",
+ *              "runtimeUrl":"https://dev.mcp.sandbox.ggui.ai/_ggui/iframe-runtime.js",
+ *              "wsUrl":"wss://…/ws","wsToken":"eyJ…","expiresAt":"…",
+ *              "propsJson":"{…}"},
+ *           "ui":{"resourceUri":"ui://ggui/render/…"}}}
+ * ```
+ *
+ * Two facts follow, and they shape everything below:
+ *
+ *  1. **`uiData.resourceUri` is the RECOGNITION signal.** It is the only part
+ *     of the render's identity that survives `@silverprotocol/core`'s fold
+ *     (the reducer copies `uiData` — and, as of `@silverprotocol/core`
+ *     0.4.1 (workspace#9), `_meta` — onto the `tool-result` block).
+ *  2. **`_meta["ai.ggui/render"]` is the MOUNT MATERIAL.** Everything needed
+ *     to boot the card — which runtime bundle to load, which live-channel to
+ *     open, which props to seed — lives there and nowhere else.
+ *
+ * ## How the card mounts (the ggui-documented self-contained shell)
+ *
+ * ggui's iframe runtime accepts its bootstrap from three delivery channels;
+ * the highest-priority one is the **self-contained shell**: HTML that inlines
+ * the slice envelope at `globalThis.__GGUI_META__` synchronously BEFORE the
+ * runtime bundle's `<script type="module">` evaluates, after which the runtime
+ * autostarts, creates its own mount container and renders — no postMessage
+ * round-trip, no host-side ggui code. That contract is stated verbatim by the
+ * runtime's own reader (`@ggui-ai/iframe-runtime`'s `parseMetaFromGlobal`:
+ * *"The global carries the SAME slice envelope shape as the wire `_meta`
+ * (`{ "ai.ggui/render": {...} }`) … per-render shells populate this
+ * synchronously BEFORE the runtime bundle's `<script type="module">`
+ * evaluates"*), and by its boot resolver (`runtime.js`'s autostart:
+ * `readSelfContainedMeta()` first, postMessage channels after).
+ *
+ * {@link gguiShellHtml} builds exactly that shell. Because the shell IS a
+ * string of HTML, the ggui card then rides the host's EXISTING mcp-ui mount
+ * path unchanged: it narrows to the same `McpUiResourcePayload` an inline
+ * resource does, so `@mcp-ui/client`'s `AppRenderer` posts it as `srcdoc` into
+ * the second-origin `mcp-app-sandbox.html` page — same double-iframe rule,
+ * same sandbox origin, same opaque inner frame. No second mount mechanism.
+ *
+ * The slice is inlined **verbatim**: `runtimeUrl` is honored as given (ggui's
+ * host checklist item 8 — "no fallback URL, no substitution"), and every other
+ * field is passed through untouched for the runtime's own projector to
+ * validate. This module reads exactly one field (`runtimeUrl`) and only to
+ * prove the slice is mountable at all.
+ *
+ * NOT in scope here: rehydrating a ggui card from persisted history. The
+ * bootstrap's `wsToken` expires minutes after the render (`expiresAt` in the
+ * capture above), so a stored bootstrap is dead on arrival — a history card
+ * without a live bootstrap correctly resolves to `undefined` and renders the
+ * host's placeholder rather than a broken mount.
+ */
+import type { AgBlock, JsonValue } from "@silverprotocol/core";
+import { isJsonObject, type McpUiResourcePayload } from "./block-ui";
+
+/** The `_meta` key the ggui render bootstrap rides on (MCP-Apps slice convention). */
+export const GGUI_RENDER_META_KEY = "ai.ggui/render";
+
+/** The `ui://` scheme prefix every ggui render resource uri carries. */
+const UI_SCHEME = "ui://";
+
+/**
+ * A ggui render bootstrap: the runtime bundle URL this module reads, plus the
+ * WHOLE `ai.ggui/render` slice, verbatim, for the shell to inline.
+ */
+export interface GguiRenderBootstrap {
+  /** `runtimeUrl` — the ESM bundle the shell loads. Honored as given. */
+  runtimeUrl: string;
+  /**
+   * The verbatim slice. Open-ended by construction: it is ggui's wire
+   * contract, not one this package owns, and the runtime's own projector is
+   * the authority on every field. Re-declaring it here would duplicate a
+   * contract we do not own and rot at ggui's next field addition.
+   */
+  slice: { [key: string]: JsonValue };
+}
+
+/** A ggui render recognised on a tool result: its resource uri + mount material. */
+export interface GguiRenderDescriptor {
+  /** `uiData.resourceUri` — `ui://ggui/render/<sessionId>/<contractHash>`. */
+  resourceUri: string;
+  /** `uiData.sessionId`, when present. */
+  sessionId?: string;
+  /**
+   * The `_meta["ai.ggui/render"]` slice, when it reached us. Absent for a
+   * persisted history card and for any consumer folding without `fold.ts`'s
+   * `_meta` carriage — such a descriptor is recognised but NOT mountable.
+   */
+  bootstrap?: GguiRenderBootstrap;
+}
+
+/** A non-empty JSON string field. */
+function isNonEmptyString(value: JsonValue | undefined): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+/**
+ * Does this slice carry at least one MOUNT MODE discriminator?
+ *
+ * Mirrors `@ggui-ai/iframe-runtime`'s `validateMeta` (see
+ * `node_modules/@ggui-ai/iframe-runtime/dist/meta-parse.d.ts`) and the
+ * `McpAppAiGguiRenderMeta` doc comment it implements
+ * (`@ggui-ai/protocol/integrations/mcp-apps`): the runtime needs `runtimeUrl`
+ * PLUS one of live mode (`wsUrl` + `wsToken` together), `codeUrl`, or `kind` —
+ * without one of those three the iframe has nothing to mount.
+ */
+function hasModeDiscriminator(slice: { [key: string]: JsonValue }): boolean {
+  if (isNonEmptyString(slice.wsUrl) && isNonEmptyString(slice.wsToken)) return true;
+  if (isNonEmptyString(slice.codeUrl)) return true;
+  if (isNonEmptyString(slice.kind)) return true;
+  return false;
+}
+
+/**
+ * A `_meta` container → the ggui render bootstrap, or `undefined`.
+ *
+ * Two hard requirements, both the runtime's own `validateMeta` enforces
+ * (`MALFORMED_BOOTSTRAP`): a non-empty `runtimeUrl`, AND at least one mode
+ * discriminator (see {@link hasModeDiscriminator}). A slice with `runtimeUrl`
+ * alone has a bundle to load but nothing for it to mount — the runtime would
+ * boot into a blank shell rather than a card, so this guard treats that shape
+ * as unmountable too and returns `undefined`.
+ */
+export function asGguiRenderBootstrap(meta: JsonValue | undefined): GguiRenderBootstrap | undefined {
+  if (!isJsonObject(meta)) return undefined;
+  const slice = meta[GGUI_RENDER_META_KEY];
+  if (!isJsonObject(slice)) return undefined;
+  const runtimeUrl = slice.runtimeUrl;
+  if (typeof runtimeUrl !== "string" || runtimeUrl.length === 0) return undefined;
+  if (!hasModeDiscriminator(slice)) return undefined;
+  return { runtimeUrl, slice };
+}
+
+/**
+ * A tool result's `uiData` (+ its `_meta`, when carried) → a ggui render
+ * descriptor, or `undefined` for anything that is not one.
+ *
+ * The `ui://` scheme gate is deliberate: `uiData` is a general-purpose channel
+ * (every `structuredContent` of a `_meta.ui`-stamped tool lands there), so a
+ * bare `resourceUri` string is not on its own a claim of generative UI.
+ */
+export function asGguiRender(
+  uiData: JsonValue | undefined,
+  meta: JsonValue | undefined,
+): GguiRenderDescriptor | undefined {
+  if (!isJsonObject(uiData)) return undefined;
+  const resourceUri = uiData.resourceUri;
+  if (typeof resourceUri !== "string" || !resourceUri.startsWith(UI_SCHEME)) return undefined;
+  const bootstrap = asGguiRenderBootstrap(meta);
+  return {
+    resourceUri,
+    ...(typeof uiData.sessionId === "string" ? { sessionId: uiData.sessionId } : {}),
+    ...(bootstrap ? { bootstrap } : {}),
+  };
+}
+
+/** A live `tool-result` AgBlock → its ggui render descriptor, if it is one. */
+export function toolResultGguiRender(
+  block: Extract<AgBlock, { type: "tool-result" }>,
+): GguiRenderDescriptor | undefined {
+  return asGguiRender(block.uiData, block._meta);
+}
+
+/** An untyped (persisted-snapshot) block → its ggui render descriptor, if it is one. */
+export function blockGguiRender(block: JsonValue): GguiRenderDescriptor | undefined {
+  if (!isJsonObject(block)) return undefined;
+  if (block.type !== "tool-result") return undefined;
+  return asGguiRender(block.uiData, block._meta);
+}
+
+/**
+ * Embed a JSON value inside an inline `<script>` safely.
+ *
+ * `</script` inside a string literal terminates the element in the HTML
+ * parser regardless of JS quoting, and U+2028/U+2029 are line terminators in
+ * JS source but not in JSON — both are escaped at the `<`/codepoint level so
+ * the emitted text is still exactly the same JSON value.
+ */
+function inlineJson(value: JsonValue): string {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+/** Escape a string for use inside a double-quoted HTML attribute. */
+function attr(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * The ggui **self-contained shell** for a render bootstrap — see this module's
+ * header for the contract it implements.
+ *
+ * Ordering is guaranteed twice over: the classic `<script>` runs during parse,
+ * and the runtime's `<script type="module">` is deferred by definition, so the
+ * global is always populated before the bundle evaluates.
+ */
+export function gguiShellHtml(bootstrap: GguiRenderBootstrap): string {
+  const envelope = inlineJson({ [GGUI_RENDER_META_KEY]: bootstrap.slice });
+  return [
+    "<!doctype html>",
+    '<html lang="en">',
+    "<head>",
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    '<meta name="color-scheme" content="light dark">',
+    "<title>ggui card</title>",
+    "<style>html,body{margin:0;height:100%;background:transparent}</style>",
+    `<script>globalThis.__GGUI_META__=${envelope};</script>`,
+    `<script type="module" src="${attr(bootstrap.runtimeUrl)}"></script>`,
+    "</head>",
+    "<body></body>",
+    "</html>",
+    "",
+  ].join("\n");
+}
+
+/**
+ * A ggui render descriptor → the mountable resource the host's existing
+ * mcp-ui path already knows how to mount, or `undefined` when the descriptor
+ * carries no bootstrap (history cards, and any fold that dropped `_meta`).
+ *
+ * The `uri` is the render's REAL `resourceUri` — the shell is the payload, not
+ * a renaming of the resource.
+ *
+ * **On `_meta` being required to MOUNT (but never to RECOGNISE).** Recognition
+ * — "this tool result is a ggui card" — is keyed on `uiData.resourceUri` alone
+ * and never waits for anything (see {@link asGguiRender}); nothing in this
+ * package is blocked on an upstream change. Mounting is different, and the
+ * requirement is ggui's, not ours: its runtime rejects a slice without
+ * `runtimeUrl` AND without at least one mode discriminator (`wsUrl`+`wsToken`,
+ * `codeUrl`, or `kind`) as `MALFORMED_BOOTSTRAP` and renders nothing. `uiData`
+ * carries none of those fields — it has `sessionId`, `resourceUri`, `action`,
+ * `contractHash`, `blueprintId`, `variantKey`, `cache`, `nextStep`, and that is
+ * all. So a bootstrap-less descriptor could only ever produce a blank frame;
+ * returning `undefined` and letting the host show its own placeholder is the
+ * honest answer, not a deferral. `@silverprotocol/core`'s `Reducer` is what
+ * puts `_meta` on the block for a live turn, in-repo, today.
+ */
+export function gguiRenderResource(
+  render: GguiRenderDescriptor,
+): McpUiResourcePayload | undefined {
+  if (!render.bootstrap) return undefined;
+  return {
+    uri: render.resourceUri,
+    mimeType: "text/html",
+    text: gguiShellHtml(render.bootstrap),
+  };
+}

package/src/history.ts

@@ -33,6 +33,22 @@ interface ThreadMessagesResponse {
   nextToken: string | null;
 }
 
+/**
+ * Thrown when the read plane returns 401 on a transcript fetch — distinct
+ * from the generic non-OK throw below so a caller holding a token can
+ * `instanceof`-match it and retry once with a freshly-refreshed one
+ * (`createWebAdapters`'s history adapter is the concrete retry). A cached
+ * bearer that has expired since the caller last checked it is exactly the
+ * shape a refresh can fix; a 500 or a malformed request is not, and gets no
+ * such retry.
+ */
+export class HistoryUnauthorizedError extends Error {
+  constructor(message = "history load failed: 401") {
+    super(message);
+    this.name = "HistoryUnauthorizedError";
+  }
+}
+
 /** Rows requested per history page. */
 const HISTORY_PAGE_LIMIT = 100;
 
@@ -112,6 +128,7 @@ export async function fetchThreadHistory({
       (nextToken ? `&nextToken=${encodeURIComponent(nextToken)}` : "");
     const res = await fetchImpl(url, requestInit);
     if (res.status === 403 || res.status === 404) return { gone: true };
+    if (res.status === 401) throw new HistoryUnauthorizedError();
     if (!res.ok) throw new Error(`history load failed: ${res.status}`);
     const body: ThreadMessagesResponse = await res.json();
     rows.push(...body.rows);