@guuey/mcp-apps-host 0.3.1 → 0.5.0

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);
+}

package/src/view-host-protocol.ts

@@ -0,0 +1,299 @@
+/**
+ * The Host half of the MCP Apps (SEP-1865) App handshake, as a PURE state
+ * machine — message in, `{state, effects}` out, zero DOM (guuey#186 Gap 1).
+ *
+ * ## Why the view hangs without this
+ *
+ * A spec-following App (ggui's iframe-runtime included) opens with
+ * `ui/initialize` posted to its parent and BLOCKS — the handshake runs
+ * before the view reads any seeded boot data, so a frame whose parent
+ * never answers stays blank forever. `toolResultViewMount` prepares the
+ * document; THIS module answers the document. The two halves together are
+ * the Host role the package is named for.
+ *
+ * ## Why a pure machine
+ *
+ * Only a real browser runs the postMessage/sandbox physics, but the
+ * publish gate (guuey-sdks mirror CI) is Node-only — the exact blind spot
+ * that let the missing-host gap ship (mount-material assertions run in
+ * Node; nothing ran the negotiation). So the protocol logic lives here,
+ * exhaustively unit-tested against scripted message sequences, and the DOM
+ * glue in `view-host.ts` stays thin enough to carry no decisions. Even the
+ * negotiation timeout is a machine INPUT ({@link viewHostElapsed}), not a
+ * timer here.
+ *
+ * ## Spec posture
+ *
+ * Types and method names come from `@modelcontextprotocol/ext-apps` — the
+ * SEP-1865 surface itself, someone else's frozen contract. Zero ggui
+ * imports, deliberately (guuey#123): this host answers ANY spec-following
+ * view; everything ggui-specific stays in `ggui-render.ts` behind ggui's
+ * own published protocol package.
+ */
+import {
+  INITIALIZE_METHOD,
+  LATEST_PROTOCOL_VERSION,
+  RESOURCE_TEARDOWN_METHOD,
+  type McpUiHostCapabilities,
+  type McpUiHostContext,
+  type McpUiInitializeResult,
+} from "@modelcontextprotocol/ext-apps";
+import type { McpToolStructuredContent } from "./action.js";
+
+/**
+ * The host identity in the initialize result — structurally the spec's
+ * `Implementation` (which the ext-apps root does not re-export), narrowed
+ * to the two fields a host must supply.
+ */
+export interface ViewHostInfo {
+  name: string;
+  version: string;
+}
+
+/** JSON-RPC `method not found` — the spec's code, not an invented one. */
+const METHOD_NOT_SUPPORTED = -32601;
+
+/** The standard MCP method a view uses to reach host-proxied tools. */
+export const TOOLS_CALL_METHOD = "tools/call";
+
+/** A JSON-RPC id as the wire allows it. */
+export type ViewRequestId = number | string;
+
+/** The messages this host posts INTO the view frame. */
+export interface ViewHostOutbound {
+  jsonrpc: "2.0";
+  id?: ViewRequestId;
+  method?: string;
+  params?: { [key: string]: unknown };
+  result?: { [key: string]: unknown };
+  error?: { code: number; message: string };
+}
+
+/**
+ * Where the negotiation stands, from the host's side of the boundary.
+ *
+ *  - `"negotiating"` — attached; no `ui/initialize` seen yet. A plain-HTML
+ *    inline card may stay here forever, legitimately: the handshake is how
+ *    a spec App boots, not an obligation on arbitrary tenant HTML.
+ *  - `"connected"` — `ui/initialize` was answered. The view owns its own
+ *    pixels (and its own failures) from here on.
+ *  - `"no-handshake"` — the caller declared the negotiation window over
+ *    ({@link viewHostElapsed}) before any `ui/initialize` arrived. What
+ *    that MEANS depends on the mount channel and is the renderer's call:
+ *    a `"ggui"` shell always handshakes, so this phase is a boot failure
+ *    there; an `"inline"` card may simply not be an App.
+ *
+ * A renderer binds to this — the failure mode must be a labeled state,
+ * never a blank page (guuey#186 audit).
+ */
+export type ViewHostPhase = "negotiating" | "connected" | "no-handshake";
+
+/** The machine's whole state. Immutable — every transition returns a new one. */
+export interface ViewHostState {
+  phase: ViewHostPhase;
+  /** `ui/notifications/initialized` seen (the App's post-handshake ack). */
+  initializedSeen: boolean;
+}
+
+export function initialViewHostState(): ViewHostState {
+  return { phase: "negotiating", initializedSeen: false };
+}
+
+/**
+ * What the glue must DO after a transition. Effects are data so the machine
+ * stays synchronous and Node-testable; the glue performs them.
+ */
+export type ViewHostEffect =
+  | { kind: "respond"; message: ViewHostOutbound }
+  | {
+      /**
+       * A `tools/call` the config accepted for relaying. The glue runs the
+       * (async) relay hook and posts {@link toolCallResponse} with the
+       * result. Only ever emitted when {@link ViewHostBehavior.toolRelay}
+       * is true — with no relay wired, the machine refuses the call
+       * in-band instead (an honest `method_not_supported`).
+       */
+      kind: "relay-tool-call";
+      id: ViewRequestId;
+      name: string;
+      arguments?: McpToolStructuredContent;
+    };
+
+/**
+ * The host identity/behavior the machine answers with. Everything here is
+ * explicit config — the machine assumes nothing about the embedder.
+ */
+export interface ViewHostBehavior {
+  hostInfo: ViewHostInfo;
+  /**
+   * The capabilities to advertise. Empty is a correct, honest default for
+   * views that ride their own live channel (ggui views do — they boot from
+   * their seeded envelope and talk to their pod directly, so the host's
+   * whole job is unblocking the handshake). Advertise ONLY what the
+   * embedder actually implements: a capability the host does not honor
+   * makes the view attribute later failures to the wrong layer.
+   */
+  hostCapabilities: McpUiHostCapabilities;
+  /** The context handed to the view in the initialize result. */
+  hostContext: McpUiHostContext;
+  /** Whether a `tools/call` relay hook is wired (see `view-host.ts`). */
+  toolRelay: boolean;
+}
+
+/** The result of feeding one inbound frame (or the timeout) to the machine. */
+export interface ViewHostTransition {
+  state: ViewHostState;
+  effects: ViewHostEffect[];
+}
+
+interface InboundEnvelope {
+  id?: ViewRequestId;
+  method: string;
+  params?: { [key: string]: unknown };
+}
+
+/** Plain-object narrowing, same idiom as `action.ts`'s `isJsonObjectLike`. */
+function isPlainObject(value: unknown): value is { [key: string]: unknown } {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Narrow untrusted postMessage data to a JSON-RPC envelope this host could
+ * answer. Anything else — other windows' chatter, the view's own non-RPC
+ * messages — is silently not ours (`undefined`), NOT an error: a shared
+ * `message` listener hears the whole page.
+ */
+function asInboundEnvelope(data: unknown): InboundEnvelope | undefined {
+  if (!isPlainObject(data)) return undefined;
+  if (data["jsonrpc"] !== "2.0") return undefined;
+  const method = data["method"];
+  if (typeof method !== "string") return undefined;
+  const id = data["id"];
+  const params = data["params"];
+  return {
+    ...(typeof id === "number" || typeof id === "string" ? { id } : {}),
+    method,
+    ...(isPlainObject(params) ? { params } : {}),
+  };
+}
+
+/** The spec-canonical answer to `ui/initialize`. Exported for the glue/tests. */
+export function initializeResult(
+  behavior: ViewHostBehavior,
+  requestedProtocolVersion: unknown,
+): McpUiInitializeResult {
+  // Echo the version the view asked for when it names one — the view is
+  // the side with a fixed runtime; the host has no version-specific
+  // behavior to defend. Absent/malformed, answer with the spec's latest.
+  const protocolVersion =
+    typeof requestedProtocolVersion === "string" && requestedProtocolVersion.length > 0
+      ? requestedProtocolVersion
+      : LATEST_PROTOCOL_VERSION;
+  return {
+    protocolVersion,
+    hostInfo: behavior.hostInfo,
+    hostCapabilities: behavior.hostCapabilities,
+    hostContext: behavior.hostContext,
+  };
+}
+
+/** Build the in-band response for a relayed `tools/call`'s settled result. */
+export function toolCallResponse(
+  id: ViewRequestId,
+  result: { [key: string]: unknown },
+): ViewHostOutbound {
+  return { jsonrpc: "2.0", id, result };
+}
+
+/**
+ * The spec-mannered farewell a detaching host posts (`ui/resource-teardown`).
+ * Sent WITHOUT an id — a host that is tearing the frame down cannot await a
+ * response, and an id-less JSON-RPC message is a notification the view may
+ * use for cleanup or ignore.
+ */
+export function teardownMessage(): ViewHostOutbound {
+  return { jsonrpc: "2.0", method: RESOURCE_TEARDOWN_METHOD, params: {} };
+}
+
+/**
+ * Feed one inbound postMessage payload to the machine.
+ *
+ * The contract, exactly:
+ *  - non-RPC data → ignored (not ours);
+ *  - notifications (no id) → consumed silently, JSON-RPC-correctly; the
+ *    `ui/notifications/initialized` ack is remembered on the state;
+ *  - `ui/initialize` → answered spec-canonically; phase → `"connected"`
+ *    (also from `"no-handshake"` — a late handshake still gets answered:
+ *    the timeout labels a state, it does not close the door);
+ *  - `tools/call` with a relay wired → `relay-tool-call` effect;
+ *  - every other REQUEST → `method_not_supported`, honestly.
+ */
+export function viewHostReceive(
+  state: ViewHostState,
+  behavior: ViewHostBehavior,
+  data: unknown,
+): ViewHostTransition {
+  const req = asInboundEnvelope(data);
+  if (req === undefined) return { state, effects: [] };
+
+  if (req.id === undefined) {
+    // A notification. Track the one the handshake defines; consume the rest.
+    if (req.method === "ui/notifications/initialized" && !state.initializedSeen) {
+      return { state: { ...state, initializedSeen: true }, effects: [] };
+    }
+    return { state, effects: [] };
+  }
+
+  if (req.method === INITIALIZE_METHOD) {
+    const result = initializeResult(behavior, req.params?.["protocolVersion"]);
+    return {
+      state: { ...state, phase: "connected" },
+      effects: [{ kind: "respond", message: { jsonrpc: "2.0", id: req.id, result } }],
+    };
+  }
+
+  if (req.method === TOOLS_CALL_METHOD && behavior.toolRelay) {
+    const name = req.params?.["name"];
+    if (typeof name === "string") {
+      const args = req.params?.["arguments"];
+      return {
+        state,
+        effects: [
+          {
+            kind: "relay-tool-call",
+            id: req.id,
+            name,
+            ...(isPlainObject(args) ? { arguments: args } : {}),
+          },
+        ],
+      };
+    }
+    // fall through: a nameless tools/call is not a call we can relay.
+  }
+
+  return {
+    state,
+    effects: [
+      {
+        kind: "respond",
+        message: {
+          jsonrpc: "2.0",
+          id: req.id,
+          error: {
+            code: METHOD_NOT_SUPPORTED,
+            message: `method_not_supported: ${req.method} — this host answers ${INITIALIZE_METHOD}${behavior.toolRelay ? ` and ${TOOLS_CALL_METHOD}` : ""} only`,
+          },
+        },
+      },
+    ],
+  };
+}
+
+/**
+ * Declare the negotiation window over. Meaningful only while
+ * `"negotiating"`: a connected view stays connected, and an already-lapsed
+ * one stays lapsed. The caller owns the clock — this machine has none.
+ */
+export function viewHostElapsed(state: ViewHostState): ViewHostState {
+  return state.phase === "negotiating" ? { ...state, phase: "no-handshake" } : state;
+}