@guuey/agent-client 0.2.2 → 0.3.0

package/dist/ggui-render.js

@@ -1,164 +0,0 @@
-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/src/block-ui.ts

@@ -1,212 +0,0 @@
-/**
- * Pure block-walk / resource-narrowing helpers for a block-preserving agent
- * transcript — no React, no DOM, so the narrowing logic stays unit-testable in
- * isolation (this package's vitest runs a `node` environment) and can be shared
- * by every host renderer (Studio's `AgentBlocks`, Portal-web's agent chat).
- *
- * The pod's AgJSON wire carries generative-UI payloads on `tool.done` events,
- * which the reducer folds onto `tool-result` blocks. Two channels reach us:
- *
- *  1. **`uiData`** — the MCP-Apps *surface* channel. The pod's Claude facet
- *     routes a tool result's `structuredContent` here when the server stamped
- *     `_meta.ui`. Any resource here is intended as UI.
- *  2. **`provider-raw` content blocks** — an MCP embedded `resource` content
- *     part does NOT survive as a first-class `resource` AgBlock in the Claude
- *     facet; it degrades to `{ type:'provider-raw', vendor, raw:<part> }`. So a
- *     `ui://` resource can be hiding inside `provider-raw.raw` and must be
- *     scanned for defensively.
- *
- * The resource-narrowing (opaque `JsonValue` → typed payload) mirrors the
- * proven `create-agentic-app` web template — structural validation, never a cast.
- */
-import type { AgBlock, AgMessage, JsonValue } from "@silverprotocol/core";
-import type { HistoryCard } from "./types";
-
-/** A narrowed MCP embedded UI resource (the `_meta.ui.resource` shape). */
-export interface McpUiResourcePayload {
-  uri: string;
-  mimeType?: string;
-  text?: string;
-  blob?: string;
-}
-
-/** Narrow an opaque `JsonValue` to a plain (non-array) JSON object. */
-export function isJsonObject(v: JsonValue | undefined): v is { [key: string]: JsonValue } {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
-/**
- * A JSON object → an MCP UI resource, if it has a `uri` plus renderable
- * payload (`text` or base64 `blob`). Returns `undefined` for anything else.
- */
-export function asResourcePayload(v: JsonValue | undefined): McpUiResourcePayload | undefined {
-  if (!isJsonObject(v)) return undefined;
-  if (typeof v.uri !== "string") return undefined;
-  if (typeof v.text !== "string" && typeof v.blob !== "string") return undefined;
-  return {
-    uri: v.uri,
-    ...(typeof v.mimeType === "string" ? { mimeType: v.mimeType } : {}),
-    ...(typeof v.text === "string" ? { text: v.text } : {}),
-    ...(typeof v.blob === "string" ? { blob: v.blob } : {}),
-  };
-}
-
-/**
- * Does a `tool-result` block's `uiData` carry an MCP embedded UI resource?
- * Accepts the resource inlined directly, or wrapped as `{ resource: {...} }`
- * (the shape an MCP `resource` content part carries). No `ui://` scheme gate
- * here on purpose: `uiData` is the explicit *surface* channel (the server
- * stamped `_meta.ui`), so any resource on it is meant to render.
- */
-export function asUiResource(uiData: JsonValue | undefined): McpUiResourcePayload | undefined {
-  if (!isJsonObject(uiData)) return undefined;
-  const direct = asResourcePayload(uiData);
-  if (direct) return direct;
-  return asResourcePayload(uiData.resource);
-}
-
-/**
- * Scan a `provider-raw` block's `raw` (the vendor tool_result content part)
- * for a *generative-UI* resource. Unlike {@link asUiResource}, this path IS
- * gated on the `ui://` scheme: `provider-raw` degradation is a lossy catch-all,
- * so a plain file/text resource riding it is NOT a UI to mount — only the
- * mcp-ui `ui://` convention is.
- */
-export function scanProviderRawForUiResource(
-  raw: JsonValue | undefined,
-): McpUiResourcePayload | undefined {
-  if (!isJsonObject(raw)) return undefined;
-  const candidate =
-    raw.resource !== undefined ? asResourcePayload(raw.resource) : asResourcePayload(raw);
-  if (!candidate) return undefined;
-  return candidate.uri.startsWith("ui://") ? candidate : undefined;
-}
-
-/**
- * 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, 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`.
- */
-export function blockUiResource(block: JsonValue): McpUiResourcePayload | undefined {
-  if (!isJsonObject(block)) return undefined;
-  switch (block.type) {
-    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": {
-      const r = asResourcePayload(block.resource);
-      return r && r.uri.startsWith("ui://") ? r : undefined;
-    }
-    default:
-      return undefined;
-  }
-}
-
-/**
- * A live `tool-result` AgBlock → its mountable UI resource, checking BOTH
- * channels the Claude facet uses:
- *   1. the `uiData` surface channel (server stamped `_meta.ui`), and
- *   2. an embedded `ui://` resource that degraded into a `provider-raw`
- *      content part inside the tool result (MCP `resource` parts do NOT survive
- *      as first-class `resource` AgBlocks here).
- * First-class `resource` content parts are intentionally not scanned in this
- * typed live path (the Claude facet never emits them); the untyped card path
- * ({@link blockUiResource}) covers them for other facets' persisted snapshots.
- */
-export function toolResultUiResource(
-  block: Extract<AgBlock, { type: "tool-result" }>,
-): McpUiResourcePayload | undefined {
-  const fromUiData = asUiResource(block.uiData);
-  if (fromUiData) return fromUiData;
-  for (const part of block.content) {
-    if (part.type === "provider-raw") {
-      const found = scanProviderRawForUiResource(part.raw);
-      if (found) return found;
-    }
-  }
-  return undefined;
-}
-
-/**
- * A persisted `HistoryCard`'s `cardSnapshot` → a mountable UI resource. The
- * snapshot is the verbatim `AgArtifact` the pod stored (`{ parts: AgBlock[] }`),
- * so walk its `parts` for the first block that yields a resource; fall back to
- * treating the snapshot root itself as a block.
- *
- * NOTE (`no-ggui-tools`): a ggui-rendered card carries NO inline HTML resource —
- * its UI rides `_meta.ggui.bootstrap` and mounts via `@ggui-ai/react`'s
- * `McpAppIframe`. That branch is OUT OF SCOPE for v1 (deferred-pending-capture).
- * So a real ggui card resolves to `undefined` here and renders as the host's
- * coherent placeholder, not a broken mount.
- */
-export function cardUiResource(cardSnapshot: JsonValue): McpUiResourcePayload | undefined {
-  if (!isJsonObject(cardSnapshot)) return undefined;
-  const parts = cardSnapshot.parts;
-  if (Array.isArray(parts)) {
-    for (const part of parts) {
-      const found = blockUiResource(part);
-      if (found) return found;
-    }
-  }
-  return blockUiResource(cardSnapshot);
-}
-
-/**
- * The resource's HTML: inline `text` wins; else base64-decode `blob`. `atob`
- * alone yields a Latin-1 string (mojibake on multibyte UTF-8), so decode via
- * bytes + `TextDecoder`. Invalid base64 → `undefined` (no renderable payload).
- */
-export function resourceHtml(resource: McpUiResourcePayload): string | undefined {
-  if (resource.text !== undefined) return resource.text;
-  if (resource.blob !== undefined) {
-    try {
-      return new TextDecoder().decode(Uint8Array.from(atob(resource.blob), (c) => c.charCodeAt(0)));
-    } catch {
-      return undefined;
-    }
-  }
-  return undefined;
-}
-
-/**
- * The tool name for a `tool-result` block, read off its paired `tool-call`
- * block in the same message (the reducer keeps both in one message's content).
- * Falls back to `"tool"` when the pair is missing.
- */
-export function toolNameFor(message: AgMessage, toolCallId: string): string {
-  for (const b of message.content) {
-    if (b.type === "tool-call" && b.toolCallId === toolCallId) return b.name;
-  }
-  return "tool";
-}
-
-/**
- * Persisted cards, ascending by transcript `seq` (stable; input untouched).
- * These are PRIOR-turn cards — they always precede the live fold, so a
- * block-preserving renderer surfaces them first (e.g. under an "Earlier in
- * this conversation" divider).
- */
-export function sortHistoryCards(cards: readonly HistoryCard[]): HistoryCard[] {
-  return [...cards].sort((a, b) => a.seq - b.seq);
-}

package/src/card-mount.ts

@@ -1,101 +0,0 @@
-/**
- * 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];
-}