@guuey/mcp-apps-host 0.4.0 → 0.5.0

package/src/action.ts

@@ -58,7 +58,12 @@ export const UI_ACTION_TOOLS: ReadonlySet<string> = new Set([
 export const UI_ACTION_UNAVAILABLE_TEXT =
   "This action isn't available right now.";
 
-function unavailable(): McpToolCallResult {
+/**
+ * The in-band `isError` result for an action that cannot be performed —
+ * the relay's own refusals use it, and `attachViewHost` posts it when an
+ * embedder-supplied relay hook rejects (the view is always answered).
+ */
+export function unavailableToolCallResult(): McpToolCallResult {
   return {
     content: [{ type: "text", text: UI_ACTION_UNAVAILABLE_TEXT }],
     isError: true,
@@ -152,15 +157,15 @@ export function createMcpUiActionRelay(
   deps: CreateMcpUiActionRelayDeps,
 ): (request: UiActionRequest) => Promise<McpToolCallResult> {
   return async (request) => {
-    if (!UI_ACTION_TOOLS.has(request.name)) return unavailable();
-    if (!request.resourceUri.startsWith("ui://")) return unavailable();
+    if (!UI_ACTION_TOOLS.has(request.name)) return unavailableToolCallResult();
+    if (!request.resourceUri.startsWith("ui://")) return unavailableToolCallResult();
     let raw: unknown;
     try {
       raw = await deps.callTool(request.resourceUri, request.name, request.arguments);
     } catch {
-      return unavailable(); // transport failure == unavailable, in-band
+      return unavailableToolCallResult(); // transport failure == unavailable, in-band
     }
-    if (raw === undefined) return unavailable();
-    return asToolCallResult(raw) ?? unavailable();
+    if (raw === undefined) return unavailableToolCallResult();
+    return asToolCallResult(raw) ?? unavailableToolCallResult();
   };
 }

package/src/card-mount.ts

@@ -143,6 +143,33 @@ export function snapshotViewMount(cardSnapshot: JsonValue): ViewMount | undefine
   return undefined;
 }
 
+/**
+ * The resolved-only convenience over the mount union (guuey#186 G6): every
+ * consumer that renders was writing the same two-call walk — narrow the
+ * union, then feed the `"locator"` arm to a reader. This collapses it:
+ *
+ *  - already-resolved mounts pass through untouched (no reader round-trip);
+ *  - a `"locator"` arm resolves via the reader — or the honest `undefined`
+ *    (placeholder) when no reader is wired: never a stale mount;
+ *  - a reader that answers with ANOTHER locator is treated as a miss. The
+ *    {@link UiResourceReader} contract says a read yields mount material or
+ *    nothing (guuey#127); a locator answer would loop, so the honest
+ *    reading is "could not resolve", not recursion.
+ *
+ * Takes `ViewMount | undefined` so it chains directly off
+ * `toolResultViewMount`/`snapshotViewMount` without a narrowing dance at
+ * the call site.
+ */
+export async function resolveViewMount(
+  mount: ViewMount | undefined,
+  reader?: UiResourceReader,
+): Promise<ResolvedViewMount | undefined> {
+  if (mount === undefined || mount.channel !== "locator") return mount;
+  if (reader === undefined) return undefined;
+  const read = await reader(mount.resourceUri);
+  return read === undefined || read.channel === "locator" ? undefined : read;
+}
+
 /**
  * The blocks to scan inside a card snapshot: the stored `AgArtifact`'s `parts`
  * when present, then the snapshot root itself — exactly `snapshotUiResource`'s own

package/src/index.ts

@@ -28,6 +28,7 @@ export {
   type GguiShellHtmlOptions,
 } from "./ggui-render.js";
 export {
+  resolveViewMount,
   snapshotViewMount,
   toolResultViewMount,
   type LocatorViewMount,
@@ -45,6 +46,7 @@ export {
 export {
   asToolCallResult,
   createMcpUiActionRelay,
+  unavailableToolCallResult,
   UI_ACTION_TOOLS,
   UI_ACTION_UNAVAILABLE_TEXT,
   type CreateMcpUiActionRelayDeps,
@@ -53,3 +55,34 @@ export {
   type McpToolStructuredContent,
   type UiActionRequest,
 } from "./action.js";
+export {
+  initializeResult,
+  initialViewHostState,
+  teardownMessage,
+  toolCallResponse,
+  TOOLS_CALL_METHOD,
+  viewHostElapsed,
+  viewHostReceive,
+  type ViewHostBehavior,
+  type ViewHostEffect,
+  type ViewHostOutbound,
+  type ViewHostPhase,
+  type ViewHostInfo,
+  type ViewHostState,
+  type ViewHostTransition,
+  type ViewRequestId,
+} from "./view-host-protocol.js";
+export {
+  attachViewHost,
+  viewDocumentHtml,
+  type AttachViewHostConfig,
+  type ViewFrameLike,
+  type ViewHostEvents,
+} from "./view-host.js";
+export {
+  attachSandboxPageDelivery,
+  isSandboxProxyReady,
+  SANDBOX_PROXY_READY_METHOD,
+  SANDBOX_RESOURCE_READY_METHOD,
+  type SandboxPageDeliveryConfig,
+} from "./sandbox-page.js";

package/src/react.tsx

@@ -0,0 +1,268 @@
+/**
+ * React entry point (`@guuey/mcp-apps-host/react`).
+ *
+ * `<GuueyView>` is the one React-coupled surface — the root subpath stays
+ * React-free (narrowing, rehydration, the relay, `attachViewHost` itself),
+ * so server-side consumers never import React at all. The component is a
+ * CONVENIENCE composition of the framework-agnostic primitive: iframe
+ * creation + the sandbox invariant + the handshake + lifecycle. A host
+ * that needs a different composition (a transcript renderer, a non-React
+ * surface) uses `attachViewHost` directly.
+ *
+ * ## Sandbox posture (invariant, not preference)
+ *
+ * `sandbox="allow-scripts"` WITHOUT `allow-same-origin`: a `srcdoc` frame
+ * inherits its embedder's origin, so granting both would run
+ * agent-generated HTML AS the embedding page — reach into its DOM and its
+ * signed-in session, an XSS by construction. Dropping `allow-same-origin`
+ * puts the document in an opaque origin instead. Extra flags ride ON TOP
+ * via {@link GuueyViewProps.dangerouslyAddSandboxFlags} — named the way it
+ * is because every flag it adds widens what agent-generated HTML can do.
+ * `allow="clipboard-write"` is delegated by default: generated views own
+ * copy buttons, and without the delegation every one of them silently
+ * no-ops inside the opaque origin.
+ *
+ * ## Who paints which state
+ *
+ * While `"negotiating"`, the component shows a small non-blocking status
+ * line — never a bare blank frame (guuey#186 audit). On `"connected"` the
+ * view owns its pixels (and its own failures) and the line disappears. On
+ * `"no-handshake"` the meaning is channel-aware: a `"ggui"` shell always
+ * negotiates, so silence is a boot failure and is labeled as one; an
+ * `"inline"` card is arbitrary tenant HTML with no handshake obligation,
+ * so the status line simply retires and the document stands as rendered.
+ */
+import { useEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import { attachViewHost, viewDocumentHtml, type AttachViewHostConfig } from "./view-host.js";
+import { attachSandboxPageDelivery } from "./sandbox-page.js";
+import type { ViewHostPhase } from "./view-host-protocol.js";
+import type { ResolvedViewMount } from "./card-mount.js";
+
+export { attachViewHost, viewDocumentHtml } from "./view-host.js";
+export type { AttachViewHostConfig, ViewFrameLike, ViewHostEvents } from "./view-host.js";
+export {
+  attachSandboxPageDelivery,
+  isSandboxProxyReady,
+  SANDBOX_PROXY_READY_METHOD,
+  SANDBOX_RESOURCE_READY_METHOD,
+  type SandboxPageDeliveryConfig,
+} from "./sandbox-page.js";
+export type { ViewHostPhase } from "./view-host-protocol.js";
+export type { ResolvedViewMount, ViewMount, ViewMountChannel } from "./card-mount.js";
+
+/** Accessible name for a mounted view when the caller has nothing better. */
+const DEFAULT_TITLE = "Generated view";
+
+export interface GuueyViewProps
+  extends Pick<
+    AttachViewHostConfig,
+    "hostCapabilities" | "hostInfo" | "hostContext" | "onCallTool" | "negotiationTimeoutMs"
+  > {
+  /** The resolved card to mount (see `toolResultViewMount`/`resolveViewMount`). */
+  mount: ResolvedViewMount;
+  /**
+   * Opt into the TWO-ORIGIN mount: instead of `srcdoc`, the frame loads
+   * this host-served sandbox page (guuey's `/mcp-app-sandbox` pattern — the
+   * caller builds the full URL, channel/app query included) and the
+   * document is delivered over the page's relay protocol
+   * (`attachSandboxPageDelivery`). Why: a `srcdoc` frame INHERITS the
+   * embedder's CSP, so its egress confinement is whatever the page happens
+   * to carry; the sandbox page is served WITH the per-request CSP that
+   * confines the mount — and the untrusted document lands in the page's
+   * own inner opaque frame, never in this one. In this mode the frame's
+   * `sandbox` gains `allow-same-origin` — REQUIRED and safe: the frame
+   * holds the cross-origin RELAY PAGE (which must run as its real origin
+   * for its CSP + referrer checks to mean anything), never agent HTML.
+   * The page must be a genuinely different origin; a same-origin URL is
+   * refused with a labeled state, never mounted.
+   */
+  sandboxPageUrl?: string;
+  /**
+   * Sandbox flags appended to the safe default (`allow-scripts`). Every
+   * entry widens what agent-generated HTML may do — `allow-same-origin`
+   * in particular hands it the embedder's origin. Prefer leaving unset.
+   * In `sandboxPageUrl` mode these forward to the INNER frame via the
+   * page's relay (which strips `allow-same-origin` regardless).
+   */
+  dangerouslyAddSandboxFlags?: string[];
+  /** Permissions-Policy delegation for the frame. Default `clipboard-write`. */
+  allow?: string;
+  /** Accessible frame title. Default "Generated view". */
+  title?: string;
+  className?: string;
+  style?: CSSProperties;
+  /** Observe the negotiation phase (the same states the default UI labels). */
+  onPhaseChange?: (phase: ViewHostPhase) => void;
+  /**
+   * Replace the default status/failure line for a phase. Return `null` for
+   * "render nothing". The default: a quiet "Negotiating with view…" line
+   * while `"negotiating"`; a labeled failure for `"no-handshake"` on the
+   * `"ggui"` channel; nothing once `"connected"` (the view owns its
+   * pixels) and nothing for a silent `"inline"` card.
+   */
+  renderStatus?: (phase: ViewHostPhase) => ReactNode;
+}
+
+const statusLineStyle: CSSProperties = {
+  position: "absolute",
+  insetInlineStart: 8,
+  insetBlockEnd: 8,
+  margin: 0,
+  padding: "2px 8px",
+  fontSize: 12,
+  lineHeight: "18px",
+  opacity: 0.65,
+  pointerEvents: "none",
+};
+
+function defaultStatus(phase: ViewHostPhase, channel: ResolvedViewMount["channel"]): ReactNode {
+  if (phase === "negotiating") {
+    return <p style={statusLineStyle}>Negotiating with view…</p>;
+  }
+  if (phase === "no-handshake" && channel === "ggui") {
+    // A ggui shell negotiates unconditionally before painting, so silence
+    // here is a boot failure with no other author — label it (role=alert
+    // so it is announced, not just drawn).
+    return (
+      <p role="alert" style={{ ...statusLineStyle, opacity: 1, pointerEvents: "auto" }}>
+        This view did not start — it never negotiated with the host.
+      </p>
+    );
+  }
+  return null;
+}
+
+/**
+ * Mount a resolved view and play the MCP Apps Host for it. See the module
+ * docblock for the sandbox and state contracts.
+ */
+export function GuueyView(props: GuueyViewProps): ReactNode {
+  const {
+    mount,
+    sandboxPageUrl,
+    dangerouslyAddSandboxFlags,
+    allow,
+    title,
+    className,
+    style,
+    onPhaseChange,
+    renderStatus,
+    ...hostConfig
+  } = props;
+  const frameRef = useRef<HTMLIFrameElement>(null);
+  const [phase, setPhase] = useState<ViewHostPhase>("negotiating");
+  const html = viewDocumentHtml(mount.resource);
+
+  // Vet the sandbox page once per URL. Same-origin is REFUSED (the widget's
+  // ResourceMount precedent, generalized): the whole point of the page is
+  // being a different origin — same-origin would hand the relay page (and
+  // through `allow-same-origin`, everything it can reach) the embedder's
+  // own origin.
+  const sandboxPage: URL | "refused" | undefined = useMemo(() => {
+    if (sandboxPageUrl === undefined) return undefined;
+    let url: URL;
+    try {
+      url = new URL(sandboxPageUrl);
+    } catch {
+      return "refused";
+    }
+    if (typeof window !== "undefined" && url.origin === window.location.origin) return "refused";
+    return url;
+  }, [sandboxPageUrl]);
+  const page = sandboxPage instanceof URL ? sandboxPage : undefined;
+
+  // The attachment is keyed to the mounted DOCUMENT, not to every render's
+  // fresh callback identities — host config rides a ref so the effect's
+  // dependency list is honestly just the document identity.
+  const latest = useRef({ hostConfig, onPhaseChange, dangerouslyAddSandboxFlags });
+  latest.current = { hostConfig, onPhaseChange, dangerouslyAddSandboxFlags };
+
+  useEffect(() => {
+    // Keyed to the same identity the frame is (the resource uri): a new
+    // document boots fresh, and the previous negotiation's phase must not
+    // paper over it.
+    setPhase("negotiating");
+    const frame = frameRef.current;
+    if (frame === null || html === undefined) return;
+    if (sandboxPageUrl !== undefined && page === undefined) return; // refused config — nothing mounts
+    const resourceUri = mount.resource.uri;
+    const detachHost = attachViewHost(frame, {
+      ...latest.current.hostConfig,
+      resourceUri,
+      onPhaseChange: (next) => {
+        setPhase(next);
+        latest.current.onPhaseChange?.(next);
+      },
+    });
+    if (page === undefined) return detachHost;
+    // Two-origin mode: the page announces readiness, the document is
+    // delivered over its relay (re-delivered on a reload's re-announce),
+    // and the view-host handshake crosses the same relay transparently.
+    const flags = latest.current.dangerouslyAddSandboxFlags;
+    const detachDelivery = attachSandboxPageDelivery(frame, {
+      pageOrigin: page.origin,
+      html,
+      ...(flags !== undefined && flags.length > 0
+        ? { sandbox: ["allow-scripts", ...flags].join(" ") }
+        : {}),
+    });
+    return () => {
+      detachDelivery();
+      detachHost();
+    };
+  }, [mount.resource.uri, html, sandboxPageUrl, page]);
+
+  if (html === undefined) {
+    // A resolved mount with no document is producer-side breakage; an
+    // empty frame would be a lie. Label it, in the same voice as the
+    // no-handshake state.
+    return (
+      <div className={className} style={{ position: "relative", ...style }}>
+        <p role="alert" style={{ ...statusLineStyle, opacity: 1, pointerEvents: "auto" }}>
+          This view could not be displayed — its resource carries no document.
+        </p>
+      </div>
+    );
+  }
+
+  if (sandboxPageUrl !== undefined && page === undefined) {
+    // A malformed or SAME-ORIGIN sandbox page is a configuration state, not
+    // a property of the card — refused, labeled, never mounted.
+    return (
+      <div className={className} style={{ position: "relative", ...style }}>
+        <p role="alert" style={{ ...statusLineStyle, opacity: 1, pointerEvents: "auto" }}>
+          Interactive view unavailable — the sandbox page is not usable from this origin.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className={className} style={{ position: "relative", ...style }}>
+      <iframe
+        ref={frameRef}
+        // Remount on a new resource (or mount mode) rather than reusing the
+        // frame: a view runtime boots once from the document it was handed,
+        // so swapping `srcDoc` in place would leave the old boot running
+        // against new markup.
+        key={`${page?.href ?? "srcdoc"}::${mount.resource.uri}`}
+        {...(page !== undefined ? { src: page.href } : { srcDoc: html })}
+        title={title ?? DEFAULT_TITLE}
+        // srcdoc mode: the INVARIANT — agent HTML in an opaque origin, extra
+        // flags only widen knowingly. Page mode: the frame holds the
+        // cross-origin RELAY PAGE, which must run as its real origin
+        // (`allow-same-origin`) for its CSP/referrer machinery to exist at
+        // all; the agent HTML lands in the page's own inner opaque frame,
+        // and the caller's extra flags travel to THAT frame via the relay.
+        sandbox={
+          page !== undefined
+            ? "allow-scripts allow-same-origin allow-forms"
+            : ["allow-scripts", ...(dangerouslyAddSandboxFlags ?? [])].join(" ")
+        }
+        allow={allow ?? "clipboard-write"}
+        style={{ display: "block", width: "100%", height: "100%", border: 0 }}
+      />
+      {renderStatus !== undefined ? renderStatus(phase) : defaultStatus(phase, mount.channel)}
+    </div>
+  );
+}

package/src/sandbox-page.ts

@@ -0,0 +1,116 @@
+/**
+ * Sandbox-PAGE document delivery — the client half of the two-origin mount
+ * (guuey#135 wave-3c, from the #186/#135 dogfood's finding 2).
+ *
+ * ## Why a second mount mode exists
+ *
+ * The default `<GuueyView>` mount is a `srcdoc` frame: zero configuration,
+ * opaque origin, correct sandbox posture — but a `srcdoc` document INHERITS
+ * the embedding page's Content-Security-Policy, so the strongest egress
+ * confinement it can have is whatever the embedder's page happens to carry.
+ * Guuey's production surfaces confine harder: the untrusted document mounts
+ * inside a HOST-SERVED sandbox page on a second origin, whose per-request
+ * CSP names exactly the egress that mount is entitled to (see the platform's
+ * `/mcp-app-sandbox` route — per-channel `connect-src`, per-app
+ * `frame-ancestors`). This module speaks that page's delivery protocol so
+ * any kit consumer can opt into the same confinement.
+ *
+ * ## The protocol (co-owned in-repo; two notifications)
+ *
+ * The page is the reference sandbox relay (adapted from the MCP ext-apps
+ * `basic-host` example, vendored at
+ * `create-agentic-app/templates-src/base/web/sandbox-proxy.ts` and served by
+ * the platform's landing route). Its wire is exactly two JSON-RPC
+ * notifications:
+ *
+ *  1. page → host: `ui/notifications/sandbox-proxy-ready` — the relay booted
+ *     and is listening;
+ *  2. host → page: `ui/notifications/sandbox-resource-ready` with
+ *     `params.html` (+ optional `params.sandbox` tokens for the INNER frame —
+ *     the page strips `allow-same-origin` from any value regardless).
+ *
+ * Every other message crosses the page transparently in both directions,
+ * which is why `attachViewHost` works unchanged on top of this delivery: the
+ * view's `ui/initialize` arrives relayed with `event.source` still the OUTER
+ * frame's window, and the host's answers relay inward.
+ *
+ * ## Identity + targeting
+ *
+ * Inbound messages are matched by `event.source === frame.contentWindow` —
+ * the package's standing identity invariant (`view-host.ts`). Outbound
+ * delivery targets `config.pageOrigin` EXPLICITLY (never `'*'`): unlike a
+ * srcdoc view, the sandbox page has a real origin, and the document being
+ * delivered is agent-generated content the caller confined on purpose — if
+ * the frame somehow navigated elsewhere, the browser drops the message
+ * instead of handing the document to the wrong receiver.
+ */
+import type { ViewFrameLike, ViewHostEvents } from "./view-host.js";
+
+export const SANDBOX_PROXY_READY_METHOD = "ui/notifications/sandbox-proxy-ready";
+export const SANDBOX_RESOURCE_READY_METHOD = "ui/notifications/sandbox-resource-ready";
+
+/** Structural check for the page's ready notification. */
+export function isSandboxProxyReady(data: unknown): boolean {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    !Array.isArray(data) &&
+    (data as { method?: unknown }).method === SANDBOX_PROXY_READY_METHOD
+  );
+}
+
+export interface SandboxPageDeliveryConfig {
+  /**
+   * The sandbox page's origin — the ONLY target the document is posted to.
+   * Derive it from the page URL the frame was given (`new URL(url).origin`).
+   */
+  pageOrigin: string;
+  /** The document to deliver (the view's `viewDocumentHtml`). */
+  html: string;
+  /**
+   * Inner-frame sandbox tokens forwarded as `params.sandbox`. The page's
+   * `safeSandbox` strips `allow-same-origin` and guarantees `allow-scripts`
+   * whatever is sent — this only ever WIDENS within the page's own bounds.
+   */
+  sandbox?: string;
+  /** Message-event source, injectable for tests. Default: `window`. */
+  events?: ViewHostEvents;
+}
+
+/**
+ * Deliver a view document to a mounted sandbox page, re-delivering on every
+ * `sandbox-proxy-ready` (a reloaded page announces again and must be
+ * re-seeded). Returns a detach function.
+ */
+export function attachSandboxPageDelivery(
+  frame: ViewFrameLike,
+  config: SandboxPageDeliveryConfig,
+): () => void {
+  const deliver = (): void => {
+    frame.contentWindow?.postMessage(
+      {
+        jsonrpc: "2.0",
+        method: SANDBOX_RESOURCE_READY_METHOD,
+        params: {
+          html: config.html,
+          ...(config.sandbox !== undefined ? { sandbox: config.sandbox } : {}),
+        },
+      },
+      config.pageOrigin,
+    );
+  };
+
+  const onMessage = (event: { data: unknown; source: unknown }): void => {
+    if (frame.contentWindow === null || event.source !== frame.contentWindow) return;
+    if (isSandboxProxyReady(event.data)) deliver();
+  };
+
+  const { events } = config;
+  if (events !== undefined) {
+    events.addEventListener("message", onMessage);
+    return () => events.removeEventListener("message", onMessage);
+  }
+  const domListener = (event: MessageEvent): void => onMessage(event);
+  window.addEventListener("message", domListener);
+  return () => window.removeEventListener("message", domListener);
+}