@guuey/agent-client 0.1.0 → 0.2.0

package/dist/card-mount.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 { type McpUiResourcePayload } from "./block-ui";
+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 declare function toolResultCardMount(block: Extract<AgBlock, {
+    type: "tool-result";
+}>): CardMount | 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 declare function cardCardMount(cardSnapshot: JsonValue): CardMount | undefined;
+//# sourceMappingURL=card-mount.d.ts.map

package/dist/card-mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card-mount.d.ts","sourceRoot":"","sources":["../src/card-mount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAwC,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE7F,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjD,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,+EAA+E;IAC/E,QAAQ,EAAE,oBAAoB,CAAC;IAC/B;;;;OAIG;IACH,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,GAC/C,SAAS,GAAG,SAAS,CAMvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAS5E"}

package/dist/card-mount.js

@@ -0,0 +1,83 @@
+/**
+ * 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 } from "./block-ui";
+import { blockGguiRender, gguiRenderResource, toolResultGguiRender } from "./ggui-render";
+/**
+ * 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) {
+    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) {
+    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) {
+    if (typeof cardSnapshot !== "object" || cardSnapshot === null || Array.isArray(cardSnapshot)) {
+        return [];
+    }
+    const parts = cardSnapshot.parts;
+    return Array.isArray(parts) ? [...parts, cardSnapshot] : [cardSnapshot];
+}

package/dist/ggui-render.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 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 { type McpUiResourcePayload } from "./block-ui";
+/** The `_meta` key the ggui render bootstrap rides on (MCP-Apps slice convention). */
+export declare const GGUI_RENDER_META_KEY = "ai.ggui/render";
+/**
+ * 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 `_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 declare function asGguiRenderBootstrap(meta: JsonValue | undefined): GguiRenderBootstrap | undefined;
+/**
+ * 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 declare function asGguiRender(uiData: JsonValue | undefined, meta: JsonValue | undefined): GguiRenderDescriptor | undefined;
+/** A live `tool-result` AgBlock → its ggui render descriptor, if it is one. */
+export declare function toolResultGguiRender(block: Extract<AgBlock, {
+    type: "tool-result";
+}>): GguiRenderDescriptor | undefined;
+/** An untyped (persisted-snapshot) block → its ggui render descriptor, if it is one. */
+export declare function blockGguiRender(block: JsonValue): GguiRenderDescriptor | undefined;
+/**
+ * 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 declare function gguiShellHtml(bootstrap: GguiRenderBootstrap): string;
+/**
+ * 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 declare function gguiRenderResource(render: GguiRenderDescriptor): McpUiResourcePayload | undefined;
+//# sourceMappingURL=ggui-render.d.ts.map

package/dist/ggui-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ggui-render.d.ts","sourceRoot":"","sources":["../src/ggui-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAgB,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAErE,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AAKrD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,KAAK,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;CACrC;AAED,oFAAoF;AACpF,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;CACjC;AAwBD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,mBAAmB,GAAG,SAAS,CAQlG;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,GAAG,SAAS,EAC7B,IAAI,EAAE,SAAS,GAAG,SAAS,GAC1B,oBAAoB,GAAG,SAAS,CAUlC;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,GAC/C,oBAAoB,GAAG,SAAS,CAElC;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAIlF;AA0BD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,mBAAmB,GAAG,MAAM,CAkBpE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,oBAAoB,GAC3B,oBAAoB,GAAG,SAAS,CAOlC"}

package/dist/ggui-render.js

@@ -0,0 +1,164 @@
+import { isJsonObject } 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 non-empty JSON string field. */
+function isNonEmptyString(value) {
+    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) {
+    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) {
+    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, meta) {
+    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) {
+    return asGguiRender(block.uiData, block._meta);
+}
+/** An untyped (persisted-snapshot) block → its ggui render descriptor, if it is one. */
+export function blockGguiRender(block) {
+    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) {
+    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) {
+    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) {
+    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) {
+    if (!render.bootstrap)
+        return undefined;
+    return {
+        uri: render.resourceUri,
+        mimeType: "text/html",
+        text: gguiShellHtml(render.bootstrap),
+    };
+}

package/dist/history.d.ts

@@ -26,6 +26,18 @@ export interface ThreadHistoryRow {
      */
     cardSnapshot?: JsonValue | 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 declare class HistoryUnauthorizedError extends Error {
+    constructor(message?: string);
+}
 /** Project raw rows to chat turns: text rows only, author → role. */
 export declare function threadHistoryRowsToMessages(rows: ThreadHistoryRow[]): AgentMessage[];
 /**

package/dist/history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE5E,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CACjC;AAoBD,qEAAqE;AACrE,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,YAAY,EAAE,CAOpF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,WAAW,EAAE,CAOhF;AAED,MAAM,WAAW,yBAAyB;IACxC,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,OAAO,EACP,QAAQ,EACR,WAAW,EACX,YAAoB,EACpB,SAAiB,GAClB,EAAE,yBAAyB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAsBxD"}
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE5E,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CACjC;AAOD;;;;;;;;GAQG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,SAA6B;CAIjD;AAeD,qEAAqE;AACrE,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,YAAY,EAAE,CAOpF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,gBAAgB,EAAE,GAAG,WAAW,EAAE,CAOhF;AAED,MAAM,WAAW,yBAAyB;IACxC,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,OAAO,EACP,QAAQ,EACR,WAAW,EACX,YAAoB,EACpB,SAAiB,GAClB,EAAE,yBAAyB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuBxD"}

package/dist/history.js

@@ -1,3 +1,18 @@
+/**
+ * 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;
 /**
@@ -51,6 +66,8 @@ export async function fetchThreadHistory({ baseUrl, threadId, requestInit, inclu
         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 = await res.json();

package/dist/index.d.ts

@@ -1,8 +1,11 @@
-export { parseSseEvents, extractAssistantText, reduceAssistantText, stringField, type ParsedSseEvent, } from "./sse";
+export { parseSseEvents, extractAssistantText, reduceAssistantText, stringField, parseConsentRequest, parseLinkRequest, type ParsedSseEvent, } from "./sse";
+export { dismissLinkPrompt } from "./link-prompt";
 export { createWebAdapters, localStorageThreadStore, webGenerateId, fetchStreamTransport, AgentResponseError, type CreateWebAdaptersOptions, } from "./web-adapters";
-export { fetchThreadHistory, threadHistoryRowsToMessages, threadHistoryRowsToCards, type ThreadHistoryRow, type ThreadHistoryFetchOptions, } from "./history";
+export { fetchThreadHistory, threadHistoryRowsToMessages, threadHistoryRowsToCards, HistoryUnauthorizedError, type ThreadHistoryRow, type ThreadHistoryFetchOptions, } from "./history";
 export { ingestMessageFrame } from "./blocks";
 export { asResourcePayload, asUiResource, blockUiResource, cardUiResource, isJsonObject, resourceHtml, scanProviderRawForUiResource, sortHistoryCards, toolNameFor, toolResultUiResource, type McpUiResourcePayload, } from "./block-ui";
+export { asGguiRender, asGguiRenderBootstrap, blockGguiRender, gguiRenderResource, gguiShellHtml, toolResultGguiRender, GGUI_RENDER_META_KEY, type GguiRenderBootstrap, type GguiRenderDescriptor, } from "./ggui-render";
+export { cardCardMount, toolResultCardMount, type CardMount, type CardMountChannel, } from "./card-mount";
 export type { AgEvent, AgReduceResult, AgMessage, AgBlock } from "@silverprotocol/core";
-export type { AgentMessage, HistoryCard, ThreadIdStore, GenerateId, InvokeRequest, InvokeTransport, AgentInvokeAdapters, AgentInvokeHistoryAdapter, HistoryLoadResult, UseAgentInvokeOptions, UseAgentInvokeReturn, } from "./types";
+export type { AgentMessage, HistoryCard, ProfileConsentRequest, ProfileLinkRequest, ThreadIdStore, GenerateId, InvokeRequest, InvokeTransport, AgentInvokeAdapters, AgentInvokeHistoryAdapter, AgentInvokeStatus, HistoryLoadResult, UseAgentInvokeOptions, UseAgentInvokeReturn, } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,KAAK,cAAc,GACpB,MAAM,OAAO,CAAC;AACf,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,wBAAwB,GAC9B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,GAC/B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAG9C,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,4BAA4B,EAC5B,gBAAgB,EAChB,WAAW,EACX,oBAAoB,EACpB,KAAK,oBAAoB,GAC1B,MAAM,YAAY,CAAC;AAIpB,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACxF,YAAY,EACV,YAAY,EACZ,WAAW,EACX,aAAa,EACb,UAAU,EACV,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,cAAc,GACpB,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,wBAAwB,GAC9B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,GAC/B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAG9C,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,4BAA4B,EAC5B,gBAAgB,EAChB,WAAW,EACX,oBAAoB,EACpB,KAAK,oBAAoB,GAC1B,MAAM,YAAY,CAAC;AAIpB,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC;AAItB,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACxF,YAAY,EACV,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,7 +1,13 @@
-export { parseSseEvents, extractAssistantText, reduceAssistantText, stringField, } from "./sse";
+export { parseSseEvents, extractAssistantText, reduceAssistantText, stringField, parseConsentRequest, parseLinkRequest, } from "./sse";
+export { dismissLinkPrompt } from "./link-prompt";
 export { createWebAdapters, localStorageThreadStore, webGenerateId, fetchStreamTransport, AgentResponseError, } from "./web-adapters";
-export { fetchThreadHistory, threadHistoryRowsToMessages, threadHistoryRowsToCards, } from "./history";
+export { fetchThreadHistory, threadHistoryRowsToMessages, threadHistoryRowsToCards, HistoryUnauthorizedError, } from "./history";
 export { ingestMessageFrame } from "./blocks";
 // Pure block-walk / resource-narrowing helpers for a block-preserving renderer
 // (shared by Studio's `AgentBlocks` and Portal-web's agent chat). React-free.
 export { asResourcePayload, asUiResource, blockUiResource, cardUiResource, isJsonObject, resourceHtml, scanProviderRawForUiResource, sortHistoryCards, toolNameFor, toolResultUiResource, } from "./block-ui";
+// The ggui render channel (`uiData.resourceUri` + the `_meta["ai.ggui/render"]`
+// bootstrap) and the dispatcher that mounts EITHER channel through the same
+// second-origin sandbox path.
+export { asGguiRender, asGguiRenderBootstrap, blockGguiRender, gguiRenderResource, gguiShellHtml, toolResultGguiRender, GGUI_RENDER_META_KEY, } from "./ggui-render";
+export { cardCardMount, toolResultCardMount, } from "./card-mount";

package/dist/link-prompt.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Client for the pod's `POST /v1/link-prompt/dismiss` route (nocode-runtime
+ * linkcoh T4) — the "don't ask again" action on the
+ * {@link ProfileLinkRequest} prompt (see `./sse`'s `parseLinkRequest` and
+ * `useAgentInvoke`'s `profileLinkRequest` state). Host-agnostic like
+ * {@link fetchThreadHistory} in `./history`: takes a bearer directly (the
+ * route authenticates ONLY off the verified bearer — the request body is
+ * never read server-side, so there is nothing else to send) and an
+ * injectable `fetchImpl` for tests, defaulting to the global `fetch`.
+ */
+/**
+ * Dismiss the pending cross-app profile link prompt for the calling byo
+ * end-user. `baseUrl` is the public read-plane base already ending in `/v1`
+ * (same convention as {@link fetchThreadHistory}'s `baseUrl`); `bearer` is the
+ * caller's byo access token, sent as `Authorization: Bearer <bearer>` — the
+ * ONLY thing the pod's route reads to determine the dismissal subject.
+ *
+ * Resolves on a 204 (the route's only success response); throws on any
+ * non-2xx status (401 unauthenticated, 403 non-byo caller, 500 write failure).
+ */
+export declare function dismissLinkPrompt(baseUrl: string, bearer: string, fetchImpl?: typeof fetch): Promise<void>;
+//# sourceMappingURL=link-prompt.d.ts.map

package/dist/link-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-prompt.d.ts","sourceRoot":"","sources":["../src/link-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/link-prompt.js

@@ -0,0 +1,29 @@
+/**
+ * Client for the pod's `POST /v1/link-prompt/dismiss` route (nocode-runtime
+ * linkcoh T4) — the "don't ask again" action on the
+ * {@link ProfileLinkRequest} prompt (see `./sse`'s `parseLinkRequest` and
+ * `useAgentInvoke`'s `profileLinkRequest` state). Host-agnostic like
+ * {@link fetchThreadHistory} in `./history`: takes a bearer directly (the
+ * route authenticates ONLY off the verified bearer — the request body is
+ * never read server-side, so there is nothing else to send) and an
+ * injectable `fetchImpl` for tests, defaulting to the global `fetch`.
+ */
+/**
+ * Dismiss the pending cross-app profile link prompt for the calling byo
+ * end-user. `baseUrl` is the public read-plane base already ending in `/v1`
+ * (same convention as {@link fetchThreadHistory}'s `baseUrl`); `bearer` is the
+ * caller's byo access token, sent as `Authorization: Bearer <bearer>` — the
+ * ONLY thing the pod's route reads to determine the dismissal subject.
+ *
+ * Resolves on a 204 (the route's only success response); throws on any
+ * non-2xx status (401 unauthenticated, 403 non-byo caller, 500 write failure).
+ */
+export async function dismissLinkPrompt(baseUrl, bearer, fetchImpl = fetch) {
+    const res = await fetchImpl(`${baseUrl}/link-prompt/dismiss`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${bearer}` },
+    });
+    if (!res.ok) {
+        throw new Error(`link prompt dismiss failed: ${res.status}`);
+    }
+}