@runsnative/mcp-server 0.6.0 → 0.7.1

package/dist/surface/marker-card.js

@@ -0,0 +1,245 @@
+/**
+ * The marker-card MCP App shell (JUNE-623) — the lasso round-trip finale.
+ *
+ * Fourth consumer of the JUNE-618 packaging seam (see gathering-card.ts for
+ * the first). Static shell: no per-call data is baked in. The host delivers
+ * the tool result (the capture's structural head) via the MCP Apps
+ * tool-result notification; the app script below renders the card
+ * client-side with DOM APIs (textContent only — a user-authored `note` can
+ * never parse as markup).
+ *
+ * Push→pull inversion (JUNE-623 comment 1, founder-normative): the pixel
+ * crop is NOT inlined in the tool result. The thumbnail slot starts empty;
+ * "Show the pixels" fetches it on demand via fetch_marker_crop.
+ */
+import { packageSurface } from './package-surface.js';
+export const MARKER_CARD_URI = 'ui://runsnative/marker-card.html';
+const CARD_CSS = `
+@layer rn-shell, primitives, semantics, themes;
+@layer rn-shell {
+  :root {
+    --run-color-text-primary: #1e293b;
+    --run-color-text-secondary: #64748b;
+    --run-color-surface-default: #ffffff;
+    --run-color-surface-subtle: #f8fafc;
+    --run-color-surface-canvas: transparent;
+    --run-color-border-default: #e2e8f0;
+    --run-color-focus-ring: #2563eb;
+    --run-font-size-s: 14px;
+    --run-font-size-m: 16px;
+  }
+}
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  color: var(--run-color-text-primary);
+  background: var(--run-color-surface-canvas);
+  padding: 12px;
+}
+.marker-card {
+  max-width: 440px;
+  border: 1px solid var(--run-color-border-default);
+  border-radius: 12px;
+  background: var(--run-color-surface-default);
+  padding: 20px;
+  display: none;
+  flex-direction: column;
+  gap: 10px;
+}
+.marker-card.is-ready { display: flex; }
+.card-inputs {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12px;
+  color: var(--run-color-text-secondary);
+  background: var(--run-color-surface-subtle);
+  border-radius: 6px;
+  padding: 8px 10px;
+  overflow-wrap: anywhere;
+}
+.card-thumb {
+  display: none;
+  max-width: 100%;
+  border-radius: 8px;
+  border: 1px solid var(--run-color-border-default);
+}
+.card-thumb.is-shown { display: block; }
+.card-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin-top: 4px; }
+.card-change-row { display: none; align-items: center; gap: 8px; }
+.card-change-row.is-shown { display: flex; }
+.card-status { font-size: 12px; color: var(--run-color-text-secondary); min-height: 1.2em; }
+#placeholder { font-size: 13px; color: var(--run-color-text-secondary); padding: 8px 2px; }
+`;
+const CARD_BODY = `
+<div id="placeholder">Waiting for the region you circled…</div>
+<article class="marker-card" id="card">
+  <run-text variant="label" as="span" size="sm" color="secondary">You circled this</run-text>
+  <run-text id="card-type" variant="title" as="h3" size="md"></run-text>
+  <run-text id="card-note" variant="body" as="p" size="sm" color="secondary"></run-text>
+  <pre class="card-inputs" id="card-inputs"></pre>
+  <img class="card-thumb" id="card-thumb" alt="The region you circled" />
+  <div class="card-actions">
+    <run-button id="spotlight-btn" variant="primary" size="sm">Show me where this is</run-button>
+    <run-button id="whatis-btn" variant="secondary" size="sm">What is this?</run-button>
+    <run-button id="pixels-btn" variant="secondary" size="sm">Show the pixels</run-button>
+  </div>
+  <div class="card-change-row" id="change-row">
+    <select id="variant-select">
+      <option value="primary">primary</option>
+      <option value="secondary">secondary</option>
+      <option value="outline">outline</option>
+      <option value="ghost">ghost</option>
+      <option value="danger">danger</option>
+      <option value="link">link</option>
+    </select>
+    <run-button id="change-btn" variant="outline" size="sm">Change it</run-button>
+  </div>
+  <div class="card-status" id="card-status"></div>
+</article>
+`;
+// Static, data-free by design — see gathering-card.ts for the rationale this
+// mirrors: everything user-authored arrives at runtime via the tool-result
+// notification and is assigned with textContent, never interpolated here.
+const CARD_APP_SCRIPT = `
+const { App } = globalThis.__MCP_APP_SDK__;
+
+let currentCapture = null;
+
+function setText(id, value) {
+  document.getElementById(id).textContent = value == null ? '' : String(value);
+}
+
+function render(payload) {
+  const capture = payload && payload.capture;
+  if (!capture) return;
+  currentCapture = capture;
+  const card = document.getElementById('card');
+  const address = capture.address || {};
+
+  setText('card-type', address.type || 'Unknown component');
+  setText('card-note', capture.note || '');
+  document.getElementById('card-inputs').textContent =
+    JSON.stringify(capture.inputs || {}, null, 2);
+
+  // "Change it" is JUNE-512's write surface — run-button only. Omit the
+  // control entirely for other types rather than shipping a button that 422s.
+  const changeRow = document.getElementById('change-row');
+  changeRow.classList.toggle('is-shown', address.type === 'run-button');
+
+  document.getElementById('pixels-btn').disabled = !capture.has_crop;
+
+  document.getElementById('placeholder').style.display = 'none';
+  card.classList.add('is-ready');
+}
+
+const app = new App({ name: 'runsnative-marker-card', version: '1.0.0' }, {});
+
+// Register before connect() so no notification is missed.
+app.ontoolresult = (params) => {
+  if (params && params.isError) {
+    setText('placeholder', 'Could not load the marker capture — see the conversation for details.');
+    return;
+  }
+  render(params && params.structuredContent);
+};
+
+document.getElementById('spotlight-btn').addEventListener('click', async () => {
+  const status = document.getElementById('card-status');
+  const address = currentCapture && currentCapture.address;
+  const instanceId = address && address.instanceId;
+  if (!instanceId) {
+    status.textContent = 'This capture has no addressable instance.';
+    return;
+  }
+  status.textContent = 'Pointing your tab at the element you circled…';
+  try {
+    const result = await app.callServerTool({
+      name: 'spotlight',
+      arguments: { target: 'instance:' + instanceId, message: "Here's the element you circled." },
+    });
+    status.textContent = result && result.isError
+      ? 'No linked tab — open runsnative.org to see it live.'
+      : 'Watch your linked tab — the ring is landing on the element.';
+  } catch (e) {
+    status.textContent = 'No linked tab — open runsnative.org to see it live.';
+  }
+});
+
+document.getElementById('whatis-btn').addEventListener('click', async () => {
+  const status = document.getElementById('card-status');
+  const address = currentCapture && currentCapture.address;
+  if (!address || !address.type) {
+    status.textContent = 'No component type on this capture.';
+    return;
+  }
+  status.textContent = 'Asking about ' + address.type + '…';
+  try {
+    const result = await app.callServerTool({ name: 'get_component', arguments: { name: address.type } });
+    status.textContent = result && result.isError
+      ? 'Could not look up that component.'
+      : 'See the conversation for ' + address.type + \"'s contract.\";
+  } catch (e) {
+    status.textContent = 'Could not look up that component.';
+  }
+});
+
+document.getElementById('pixels-btn').addEventListener('click', async () => {
+  const status = document.getElementById('card-status');
+  if (!currentCapture || !currentCapture.has_crop) {
+    status.textContent = 'No pixels were captured for this region.';
+    return;
+  }
+  status.textContent = 'Fetching the pixels…';
+  try {
+    const result = await app.callServerTool({
+      name: 'fetch_marker_crop',
+      arguments: { capture_id: currentCapture.capture_id },
+    });
+    const block = result && Array.isArray(result.content)
+      ? result.content.find((c) => c.type === 'image')
+      : null;
+    if (result && result.isError || !block) {
+      status.textContent = 'Could not fetch the pixels — they may have expired.';
+      return;
+    }
+    const thumb = document.getElementById('card-thumb');
+    thumb.src = 'data:' + (block.mimeType || 'image/png') + ';base64,' + block.data;
+    thumb.classList.add('is-shown');
+    status.textContent = '';
+  } catch (e) {
+    status.textContent = 'Could not fetch the pixels — they may have expired.';
+  }
+});
+
+document.getElementById('change-btn').addEventListener('click', async () => {
+  const status = document.getElementById('card-status');
+  const address = currentCapture && currentCapture.address;
+  const instanceId = address && address.instanceId;
+  if (!instanceId) {
+    status.textContent = 'This capture has no addressable instance.';
+    return;
+  }
+  const variant = document.getElementById('variant-select').value;
+  status.textContent = 'Sending ' + variant + ' to your tab…';
+  try {
+    const result = await app.callServerTool({
+      name: 'set_instance_variant',
+      arguments: { instance_id: instanceId, variant: variant },
+    });
+    status.textContent = result && result.isError
+      ? 'No linked tab — open runsnative.org to try it live.'
+      : 'Watch your linked tab — the button is switching to ' + variant + '.';
+  } catch (e) {
+    status.textContent = 'No linked tab — open runsnative.org to try it live.';
+  }
+});
+
+await app.connect();
+`;
+export function buildMarkerCardHtml(assets) {
+    return packageSurface({
+        title: 'The region you circled',
+        bodyHtml: CARD_BODY,
+        css: CARD_CSS,
+        appScript: CARD_APP_SCRIPT,
+    }, assets);
+}

package/dist/tools/fetch-marker-crop.js

@@ -0,0 +1,67 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { getWorkerApi, getLinkedPairId } from '../bridge-client.js';
+export const FETCH_MARKER_CROP_TOOL = {
+    name: 'fetch_marker_crop',
+    description: 'Fetch the pixel crop for a marker capture, on demand (JUNE-623 push→pull inversion). ' +
+        'render_marker_capture and get_marker_capture deliver the structural head only — call this when the ' +
+        'user\'s complaint is visual (a gap, alignment, or render fidelity issue that a component-instance ' +
+        'address alone cannot answer). Requires an active linked session; the crop must still be within its ' +
+        'capture window (~15 minutes) or this returns not-found.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            capture_id: {
+                type: 'string',
+                description: 'The capture_id from a marker-capture head (get_marker_capture or render_marker_capture).',
+            },
+        },
+        required: ['capture_id'],
+    },
+    // Copresence Protocol §5.1 (copresence-protocol-v0.1, mukadra repo) — a
+    // session-targeting READ leg like get_marker_capture: it drains a stored
+    // resource rather than enacting a command, so no allow-list `enactment`.
+    _meta: {
+        copresence: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+        },
+    },
+};
+export async function handleFetchMarkerCrop(args) {
+    const captureId = args['capture_id'];
+    if (typeof captureId !== 'string' || !captureId.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'capture_id must be a non-empty string');
+    }
+    const pairId = getLinkedPairId();
+    if (!pairId) {
+        throw new McpError(ErrorCode.InvalidParams, 'No linked session. Call link_session with the pairing code first, or open runsnative.org and start the pairing flow.');
+    }
+    const res = await getWorkerApi(`/session/${pairId}/captures/${encodeURIComponent(captureId.trim())}/crop`);
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'Crop not found — it may have expired, or the linked session was re-linked. Re-circle the region if you still need it.');
+    }
+    if (res.status === 410) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session revoked or expired. Re-link with link_session.');
+    }
+    if (res.status === 409) {
+        throw new McpError(ErrorCode.InvalidParams, 'No live tab detected. Open runsnative.org, ensure the tab is active, then retry.');
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Worker error ${res.status}: ${body}`);
+    }
+    const buffer = await res.arrayBuffer();
+    const bytes = new Uint8Array(buffer);
+    let binary = '';
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    const b64 = btoa(binary);
+    return {
+        content: [{ type: 'image', data: b64, mimeType: 'image/png' }],
+    };
+}

package/dist/tools/get-marker-capture.js

@@ -1,14 +1,15 @@
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { getWorkerApi, getLinkedPairId } from '../bridge-client.js';
-const CROP_PREFIX = 'data:image/png;base64,';
 export const GET_MARKER_CAPTURE_TOOL = {
     name: 'get_marker_capture',
     description: 'Fetch pending marker captures from the linked runsnative.org tab — regions the user circled ' +
         'with the marker overlay. Use when the user says they marked, circled, or pointed at something ' +
         'on the site, or asks "can you see what I selected?". Each capture carries the resolved ' +
-        'component-instance address (usable with set_instance_variant), its render inputs, an optional ' +
-        'user note, and the pixel crop as an image so you see exactly what they saw. Single delivery: a ' +
-        'capture is returned once. Requires an active linked session (call link_session first).',
+        'component-instance address (usable with set_instance_variant), its render inputs, and an ' +
+        'optional user note — the structural head only (JUNE-623 push→pull inversion). Pixels are NOT ' +
+        'inlined: when `has_crop` is true and the complaint is visual (not structural), call ' +
+        'fetch_marker_crop with the capture_id to see the region. Single delivery: a capture head is ' +
+        'returned once. Requires an active linked session (call link_session first).',
     inputSchema: {
         type: 'object',
         properties: {},
@@ -68,18 +69,9 @@ export async function handleGetMarkerCapture(_args) {
                 inputs: cap.inputs,
                 note: cap.note,
                 created_at: cap.created_at,
+                has_crop: cap.has_crop,
             }, null, 2),
         });
-        // The pixel crop is co-equal with the structural address (design doc
-        // §3.4) — deliver it as an image block so the agent SEES the region,
-        // not a reference to it.
-        if (cap.crop && cap.crop.startsWith(CROP_PREFIX)) {
-            content.push({
-                type: 'image',
-                data: cap.crop.slice(CROP_PREFIX.length),
-                mimeType: 'image/png',
-            });
-        }
     }
     if (data.truncated) {
         content.push({

package/dist/tools/render-marker-capture.js

@@ -0,0 +1,83 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { getWorkerApi, getLinkedPairId } from '../bridge-client.js';
+import { componentsBundle, iframeRuntime } from '../surface/assets.js';
+import { buildMarkerCardHtml, MARKER_CARD_URI } from '../surface/marker-card.js';
+import { SURFACE_MIME_TYPE } from '../surface/package-surface.js';
+export const RENDER_MARKER_CAPTURE_TOOL = {
+    name: 'render_marker_capture',
+    description: "Render the user's most recent marker capture — a region they circled with the marker overlay on " +
+        'the linked runsnative.org tab — as a live MCP App card in this conversation (JUNE-623). The card is ' +
+        'a HANDLE, not a picture: it carries live actions targeting the captured instance ("Show me where " +' +
+        '"this is", "Change it", "What is this?"), plus an on-demand pixel fetch. Use when the user says they ' +
+        'circled or marked something and you want to hand them (and yourself) a live surface instead of raw ' +
+        'JSON. Requires an active linked session (call link_session first).',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+    _meta: {
+        ui: { resourceUri: MARKER_CARD_URI },
+        // Legacy key for hosts predating _meta.ui (ext-apps compatibility shim).
+        'ui/resourceUri': MARKER_CARD_URI,
+    },
+};
+export const MARKER_CARD_RESOURCE = {
+    uri: MARKER_CARD_URI,
+    name: 'Marker Capture Card',
+    description: 'Self-contained MCP App shell that renders a marker capture as a live RunsNative card with ' +
+        'spotlight/change/introspect actions. The pixel crop is fetched on demand, never inlined.',
+    mimeType: SURFACE_MIME_TYPE,
+};
+export async function readMarkerCardResource() {
+    const html = buildMarkerCardHtml({
+        componentsBundle: componentsBundle(),
+        iframeRuntime: iframeRuntime(),
+    });
+    return {
+        contents: [{ uri: MARKER_CARD_URI, mimeType: SURFACE_MIME_TYPE, text: html }],
+    };
+}
+export async function handleRenderMarkerCapture() {
+    const pairId = getLinkedPairId();
+    if (!pairId) {
+        throw new McpError(ErrorCode.InvalidParams, 'No linked session. Call link_session with the pairing code first, or open runsnative.org and start the pairing flow.');
+    }
+    const res = await getWorkerApi(`/session/${pairId}/captures`);
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session not found or expired. Re-link with link_session.');
+    }
+    if (res.status === 410) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session revoked or expired. Re-link with link_session.');
+    }
+    if (res.status === 409) {
+        throw new McpError(ErrorCode.InvalidParams, 'No live tab detected. Open runsnative.org, ensure the tab is active, then retry.');
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Worker error ${res.status}: ${body}`);
+    }
+    const data = (await res.json());
+    const captures = data.captures ?? [];
+    if (captures.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'No pending marker captures. Ask the user to arm the marker overlay and circle a region on the linked tab.',
+                },
+            ],
+        };
+    }
+    // Head endpoint returns oldest-first — the most recent pending capture is last.
+    const capture = captures[captures.length - 1];
+    return {
+        content: [
+            {
+                type: 'text',
+                text: 'Rendered the region the user circled as a live card in the conversation.',
+            },
+        ],
+        structuredContent: { capture },
+    };
+}

package/dist/tools/render-surface.js

@@ -0,0 +1,215 @@
+/**
+ * render_surface / surface_event tools (JUNE-793) — the MCP-host leg of the
+ * agent-surface runtime. Together they close the engine's render → suspend →
+ * resume loop at the user:
+ *
+ *  - `render_surface { route }` — the RENDER leg. Calls the engine gateway's
+ *    `surfaces/query` (threading the linked-session `agent_session_id`),
+ *    retains the pairing keys, and returns the `SurfaceSpec` for the agent-
+ *    surface MCP-App shell to mount.
+ *  - `surface_event { event_type, payload }` — the RESUME leg. Posts the
+ *    retained keys + the user's typed payload to `surfaces/{name}/event`,
+ *    handling the terminal ack, the chained successor, and the governor
+ *    rejection ("surface no longer active") distinctly.
+ *
+ * The active surface is held module-level for the MCP server process lifetime
+ * (one surface in flight at a time), mirroring bridge-client's `_linkedPairId`.
+ * The transport is injectable so tests exercise the full loop with a stub —
+ * no engine required.
+ */
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { getLinkedPairId } from '../bridge-client.js';
+import { componentsBundle, iframeRuntime } from '../surface/assets.js';
+import { AGENT_SURFACE_URI, buildAgentSurfaceHtml } from '../surface/agent-surface.js';
+import { SURFACE_MIME_TYPE } from '../surface/package-surface.js';
+import { engineGatewayTransport } from '../surface/engine-gateway-transport.js';
+let _surfaceHostClientModule;
+/** Lazy, memoized load of the surface-host-client runtime classes. */
+async function loadSurfaceHostClient() {
+    if (!_surfaceHostClientModule) {
+        _surfaceHostClientModule = await import('../surface/surface-host-client.js');
+    }
+    return _surfaceHostClientModule;
+}
+// ---------------------------------------------------------------------------
+// Module-level state — one active surface per MCP server process, and an
+// injectable transport (default: the engine gateway over HTTP).
+// ---------------------------------------------------------------------------
+let _transport = engineGatewayTransport;
+let _session = null;
+/** Test seam — swap the engine transport for a stub. */
+export function _setSurfaceTransport(t) {
+    _transport = t;
+}
+/** Test seam — reset transport + active surface between tests. */
+export function _resetSurfaceHost() {
+    _transport = engineGatewayTransport;
+    _session = null;
+}
+/** The session identity threaded on both legs: the linked pair, or an env override. */
+function currentAgentSessionId() {
+    const linked = getLinkedPairId();
+    if (linked)
+        return linked;
+    const env = process.env['MUKADRA_AGENT_SESSION_ID']?.trim();
+    return env ? env : undefined;
+}
+// ---------------------------------------------------------------------------
+// Tool + resource definitions
+// ---------------------------------------------------------------------------
+export const RENDER_SURFACE_TOOL = {
+    name: 'render_surface',
+    description: 'Render an agent surface at a route: ask the Mukadra engine what component to render there, ' +
+        'mount it as a live MCP App in this conversation, and suspend for the user to interact. The ' +
+        "user's typed response is posted back with surface_event, and the agent continues. Use when an " +
+        'agent reasoning step needs a user pick that a component surface can capture (the render → ' +
+        'suspend → resume loop). Requires a linked session so the resume is governed (resumable); ' +
+        'without one the surface renders non-resumable (one-shot).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            route: {
+                type: 'string',
+                description: "The surface route to resolve (e.g. '/pick/customer'). Matched by the engine's surface catalog.",
+            },
+        },
+        required: ['route'],
+    },
+    _meta: {
+        ui: { resourceUri: AGENT_SURFACE_URI },
+        'ui/resourceUri': AGENT_SURFACE_URI,
+    },
+};
+export const SURFACE_EVENT_TOOL = {
+    name: 'surface_event',
+    description: 'Post the user\'s response to the active surface back to the engine (the resume leg). Called by ' +
+        'the surface shell when the user interacts; resolves the suspended agent step. Returns the ' +
+        'outcome: done (agent continues), chained (a successor surface to render), or expired (the ' +
+        'surface is no longer active).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            event_type: { type: 'string', description: "Interaction type, e.g. 'submit', 'click', 'cancel'. Defaults to 'submit'." },
+            payload: { description: "The user's typed response, shaped by the surface's response contract." },
+        },
+        required: [],
+    },
+};
+export const AGENT_SURFACE_RESOURCE = {
+    uri: AGENT_SURFACE_URI,
+    name: 'Agent Surface',
+    description: 'Self-contained MCP App shell that mounts whatever component the engine surfaces at a route and ' +
+        'posts the user response back. Spec arrives via the tool-result notification; nothing external is loaded.',
+    mimeType: SURFACE_MIME_TYPE,
+};
+export async function readAgentSurfaceResource() {
+    const html = buildAgentSurfaceHtml({
+        componentsBundle: componentsBundle(),
+        iframeRuntime: iframeRuntime(),
+    });
+    return { contents: [{ uri: AGENT_SURFACE_URI, mimeType: SURFACE_MIME_TYPE, text: html }] };
+}
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+export async function handleRenderSurface(args) {
+    const route = typeof args['route'] === 'string' ? args['route'].trim() : '';
+    if (!route) {
+        throw new McpError(ErrorCode.InvalidParams, 'render_surface requires a non-empty "route".');
+    }
+    const { SurfaceHostSession } = await loadSurfaceHostClient();
+    const session = new SurfaceHostSession({
+        transport: _transport,
+        agentSessionId: currentAgentSessionId(),
+    });
+    const outcome = await session.render(route);
+    if (outcome.status === 'not_found') {
+        // No declared surface matches this route (render-leg 404). Distinct from a
+        // governor rejection, which can only happen on the resume leg.
+        throw new McpError(ErrorCode.InvalidParams, `No surface is declared at route "${route}". Check the route, or the agent's surface catalog.`);
+    }
+    // Retain the active surface for the subsequent surface_event call.
+    _session = session;
+    const resumableNote = outcome.resumable
+        ? 'The surface is governed (resumable) — interact, and surface_event resumes the agent.'
+        : 'No linked session — this surface is NON-RESUMABLE (one-shot); link a session first to enable resume.';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Rendered surface "${outcome.surfaceName}" (${outcome.spec.component}) at route "${route}". ` +
+                    resumableNote,
+            },
+        ],
+        structuredContent: {
+            spec: outcome.spec,
+            surface_instance_id: outcome.surfaceInstanceId,
+            correlation_id: outcome.correlationId,
+            resumable: outcome.resumable,
+        },
+    };
+}
+export async function handleSurfaceEvent(args) {
+    if (!_session || !_session.hasActiveSurface) {
+        throw new McpError(ErrorCode.InvalidParams, 'No active surface to respond to. Render one first with render_surface.');
+    }
+    const eventType = typeof args['event_type'] === 'string' && args['event_type'].trim() ? args['event_type'].trim() : 'submit';
+    const payload = args['payload'];
+    let outcome;
+    try {
+        outcome = await _session.submit(eventType, payload);
+    }
+    catch (e) {
+        // Already loaded — reaching here requires an active _session, which only
+        // handleRenderSurface (which loads the module first) can have set.
+        const { SurfaceHostStateError } = await loadSurfaceHostClient();
+        if (e instanceof SurfaceHostStateError) {
+            // Non-resumable (session-less) surface, or ordering violation — a clean
+            // host-side signal, not a crash.
+            _session = null;
+            throw new McpError(ErrorCode.InvalidParams, e.message);
+        }
+        throw e;
+    }
+    switch (outcome.status) {
+        case 'done':
+            _session = null;
+            return {
+                content: [{ type: 'text', text: 'Response accepted — the agent is continuing.' }],
+                structuredContent: { status: 'done', correlation_id: outcome.correlationId },
+            };
+        case 'chained':
+            // Successor surface parked by the engine (same correlation_id). The shell
+            // re-mounts spec and loops.
+            return {
+                content: [
+                    { type: 'text', text: `Rendered the next surface (${outcome.spec.component}). Waiting for the user's response.` },
+                ],
+                structuredContent: {
+                    status: 'chained',
+                    spec: outcome.spec,
+                    surface_instance_id: outcome.surfaceInstanceId,
+                    correlation_id: outcome.correlationId,
+                },
+            };
+        case 'expired':
+            // Governor rejection — expired / cross-session / already-resolved. This
+            // is the "surface no longer active" state, distinct from a 404.
+            _session = null;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'That surface is no longer active (it expired or was already resolved). Render it again to continue.',
+                    },
+                ],
+                structuredContent: { status: 'expired' },
+            };
+        case 'not_found':
+            _session = null;
+            return {
+                content: [{ type: 'text', text: 'That surface is no longer available (unknown surface or route).' }],
+                structuredContent: { status: 'not_found' },
+            };
+    }
+}

package/dist/tools/search-docs.js

@@ -1,7 +1,7 @@
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 export const SEARCH_DOCS_TOOL = {
     name: 'search_docs',
-    description: 'Lexical search across all RunsNative component documentation, foundations, and exercises. ' +
+    description: 'Lexical search across all RunsNative component documentation, foundations, exercises, and composition patterns (recipes). ' +
         'Useful when you do not know the exact component name — for example, searching "focus ring token" ' +
         'or "which component handles multi-select". Returns scored results with excerpts.',
     inputSchema: {