@runsnative/mcp-server 0.6.0 → 0.7.1

package/README.md

@@ -75,9 +75,53 @@ Paste that URL into Claude's "Add custom skill" dialog, or add it to your agent'
 | `link_session` | Pair the agent with a logged-in runsnative.org tab (consent-gated) |
 | `navigate` / `set_theme` | Drive the linked tab: change routes, switch themes |
 | `set_instance_variant` | Change a component instance in the linked tab by marker-capture handle |
-| `get_marker_capture` | Receive regions circled with the marker overlay |
+| `get_marker_capture` | Receive regions circled with the marker overlay — structural head only, pixels not inlined |
+| `render_marker_capture` | Render the most recent marker capture as a live MCP App card with spotlight/change/introspect actions (JUNE-623) |
+| `fetch_marker_crop` | Fetch a marker capture's pixel crop on demand — the lazy-pixel pull |
 | `render_gathering` | Render the user's latest Convene gathering as a live, branded MCP App card in the conversation (JUNE-618) |
 
+## Marker capture: push→pull pixel economics (JUNE-623)
+
+`get_marker_capture` and `render_marker_capture` deliver a capture's **structural head** by
+default — the resolved component-instance address, render inputs, and note — and never inline
+the pixel crop. The agent fetches pixels only when the complaint is visual, via
+`fetch_marker_crop`. The rationale (JUNE-623, founder-normative): the user already sees the real
+thing on their screen — the screenshot-paste ritual was always for the agent's benefit, so let
+the consumer of the information decide its own input-token budget.
+
+The three-way comparison below is computed, not eyeballed — reproduce it with the formulas
+below rather than trusting the numbers as given.
+
+| Path | What's sent | Tokens |
+|---|---|---|
+| (a) Copy-paste screenshot | Full-viewport image, no structural data | **~1,366** |
+| (b) Lasso, crop fetched | Structural head (JSON) **+** the fetched crop image | **~150** |
+| (c) Lasso, metadata-only | Structural head (JSON) only — `fetch_marker_crop` never called | **~98** |
+
+Methodology:
+- **Image tokens** use Claude's documented vision approximation, `tokens ≈ (width_px × height_px) / 750`.
+  - (a) assumes a full-viewport screenshot at a common desktop capture size, 1280×800 → `(1280×800)/750 ≈ 1366`.
+  - (b) assumes a tight marker-overlay crop around the circled element, 320×120 → `(320×120)/750 ≈ 52`.
+- **Text tokens** use the standard ~4-characters-per-token approximation, applied to the actual
+  JSON `get_marker_capture` / `render_marker_capture` emit for a capture head:
+  ```json
+  {
+    "capture_id": "8f3a2b1c-4d5e-4a6b-9c7d-1e2f3a4b5c6d",
+    "address": { "type": "run-button", "path": "main>section>run-button", "index": 2, "instanceId": "a1b2c3d4-e5f6-4789-abcd-0123456789ab" },
+    "inputs": { "data-run-skin": "default", "data-run-mode": "light" },
+    "note": "make this one pop",
+    "created_at": "2026-07-13T14:22:00.000Z",
+    "has_crop": true
+  }
+  ```
+  391 characters → `391/4 ≈ 98` tokens.
+- (b) = 98 (head) + 52 (crop) ≈ 150. (c) = 98 (head only).
+
+Both lasso paths beat the copy-paste screenshot on tokens; metadata-only is the largest win
+(~93% fewer tokens than the screenshot) and is exact — the agent already has the machine-readable
+address, whereas OCR-from-pixels for a structural change ("make this secondary") is a lossy
+detour on top of the token cost.
+
 ## Environment variables
 
 | Variable | Default | Description |

package/dist/content.js

@@ -3,12 +3,19 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 const VALID_TABS = ['usage', 'style', 'code', 'accessibility'];
-// Content store root — same directory the dotorg-site reads from.
-// fileURLToPath handles Windows drive letters correctly (avoids /C:/C:/ doubling).
-const CONTENT_ROOT = fileURLToPath(new URL('../../../content', import.meta.url));
+// Content store roots. fileURLToPath handles Windows drive letters correctly
+// (avoids /C:/C:/ doubling).
+//
+// JUNE-656 moved the .org site's content store (components, foundations,
+// recipes) into domains/runsnative-org/state/data/content. The shared kernel
+// (exercises, changelog) stays at repo-root content/ because sibling package
+// release/deploy pipelines consume it too. Mirrors the same split in
+// packages/mcp-api-worker/scripts/upload-content-to-kv.ts.
+const DOMAIN_CONTENT_ROOT = fileURLToPath(new URL('../../../domains/runsnative-org/state/data/content', import.meta.url));
+const SHARED_CONTENT_ROOT = fileURLToPath(new URL('../../../content', import.meta.url));
 export function validateContentRoot() {
-    if (!existsSync(CONTENT_ROOT)) {
-        throw new Error(`Content store not found at ${CONTENT_ROOT}. ` +
+    if (!existsSync(DOMAIN_CONTENT_ROOT)) {
+        throw new Error(`Content store not found at ${DOMAIN_CONTENT_ROOT}. ` +
             `Run from the runsnative repo root or set RUNSNATIVE_CONTENT_ROOT.`);
     }
 }
@@ -19,7 +26,7 @@ export async function getComponent(name, tab) {
     if (!isValidTab(tab)) {
         throw new RangeError(`Unknown tab "${tab}". Valid tabs: ${VALID_TABS.join(', ')}.`);
     }
-    const filePath = join(CONTENT_ROOT, 'components', name, `${tab}.md`);
+    const filePath = join(DOMAIN_CONTENT_ROOT, 'components', name, `${tab}.md`);
     if (!existsSync(filePath)) {
         throw new RangeError(`Component "${name}" has no "${tab}" tab. ` +
             `Check content/components/${name}/${tab}.md exists and status is "ready".`);
@@ -47,7 +54,7 @@ export function parseFrontmatter(raw) {
     return result;
 }
 export async function listComponentMeta(includeDrafts = false) {
-    const componentsDir = join(CONTENT_ROOT, 'components');
+    const componentsDir = join(DOMAIN_CONTENT_ROOT, 'components');
     if (!existsSync(componentsDir))
         return [];
     const entries = await readdir(componentsDir, { withFileTypes: true });
@@ -75,7 +82,7 @@ export async function listComponentMeta(includeDrafts = false) {
     return results.sort((a, b) => a.name.localeCompare(b.name));
 }
 export async function getFoundation(name) {
-    const filePath = join(CONTENT_ROOT, 'foundations', `${name}.md`);
+    const filePath = join(DOMAIN_CONTENT_ROOT, 'foundations', `${name}.md`);
     if (!existsSync(filePath)) {
         throw new RangeError(`Foundation "${name}" not found. ` +
             `Check content/foundations/${name}.md exists.`);
@@ -83,7 +90,7 @@ export async function getFoundation(name) {
     return readFile(filePath, 'utf8');
 }
 export async function listFoundations() {
-    const foundationsDir = join(CONTENT_ROOT, 'foundations');
+    const foundationsDir = join(DOMAIN_CONTENT_ROOT, 'foundations');
     if (!existsSync(foundationsDir))
         return [];
     const entries = await readdir(foundationsDir);
@@ -139,7 +146,7 @@ export async function searchDocs(query, limit = 5) {
     const queryTokens = tokenize(query);
     const candidates = [];
     // Index component tabs
-    const componentsDir = join(CONTENT_ROOT, 'components');
+    const componentsDir = join(DOMAIN_CONTENT_ROOT, 'components');
     if (existsSync(componentsDir)) {
         const componentDirs = await readdir(componentsDir, { withFileTypes: true });
         for (const dir of componentDirs) {
@@ -164,7 +171,7 @@ export async function searchDocs(query, limit = 5) {
         }
     }
     // Index foundations
-    const foundationsDir = join(CONTENT_ROOT, 'foundations');
+    const foundationsDir = join(DOMAIN_CONTENT_ROOT, 'foundations');
     if (existsSync(foundationsDir)) {
         const entries = await readdir(foundationsDir);
         for (const entry of entries) {
@@ -183,12 +190,46 @@ export async function searchDocs(query, limit = 5) {
             }
         }
     }
+    // Index exercises (content/exercises/<name>/index.md + steps/*.md)
+    const exercisesDir = join(SHARED_CONTENT_ROOT, 'exercises');
+    if (existsSync(exercisesDir)) {
+        const exDirs = await readdir(exercisesDir, { withFileTypes: true });
+        for (const dir of exDirs) {
+            if (!dir.isDirectory())
+                continue;
+            const indexPath = join(exercisesDir, dir.name, 'index.md');
+            if (!existsSync(indexPath))
+                continue;
+            let text = await readFile(indexPath, 'utf8');
+            const stepsDir = join(exercisesDir, dir.name, 'steps');
+            if (existsSync(stepsDir)) {
+                for (const step of (await readdir(stepsDir)).filter(f => f.endsWith('.md')).sort()) {
+                    text += '\n' + await readFile(join(stepsDir, step), 'utf8');
+                }
+            }
+            const score = scoreDoc(text, queryTokens);
+            if (score > 0) {
+                candidates.push({ type: 'exercise', name: dir.name, excerpt: excerpt(text, query), score });
+            }
+        }
+    }
+    // Index recipes / composition patterns (content/recipes/*.md)
+    const recipesDir = join(DOMAIN_CONTENT_ROOT, 'recipes');
+    if (existsSync(recipesDir)) {
+        for (const entry of (await readdir(recipesDir)).filter(f => f.endsWith('.md') && f !== '_index.md')) {
+            const text = await readFile(join(recipesDir, entry), 'utf8');
+            const score = scoreDoc(text, queryTokens);
+            if (score > 0) {
+                candidates.push({ type: 'recipe', name: entry.replace(/\.md$/, ''), excerpt: excerpt(text, query), score });
+            }
+        }
+    }
     return candidates
         .sort((a, b) => b.score - a.score)
         .slice(0, limit);
 }
 export async function listRecipeMeta() {
-    const recipesDir = join(CONTENT_ROOT, 'recipes');
+    const recipesDir = join(DOMAIN_CONTENT_ROOT, 'recipes');
     if (!existsSync(recipesDir))
         return [];
     const entries = await readdir(recipesDir);
@@ -205,14 +246,14 @@ export async function listRecipeMeta() {
         results.push({
             name,
             title: fm['title'] ?? name,
-            group: fm['recipe-group'] ?? '',
+            group: fm['group'] ?? '',
             status: fm['status'] ?? 'unknown',
         });
     }
     return results.sort((a, b) => a.name.localeCompare(b.name));
 }
 export async function getRecipe(name) {
-    const filePath = join(CONTENT_ROOT, 'recipes', `${name}.md`);
+    const filePath = join(DOMAIN_CONTENT_ROOT, 'recipes', `${name}.md`);
     if (!existsSync(filePath)) {
         const available = (await listRecipeMeta()).map(r => r.name).join(', ');
         throw new RangeError(`Recipe "${name}" not found. Available patterns: ${available || 'none'}.`);
@@ -239,7 +280,7 @@ function extractSection(text, heading) {
     return '';
 }
 export async function listExerciseMeta(includeDrafts = false) {
-    const exercisesDir = join(CONTENT_ROOT, 'exercises');
+    const exercisesDir = join(SHARED_CONTENT_ROOT, 'exercises');
     if (!existsSync(exercisesDir))
         return [];
     const entries = await readdir(exercisesDir, { withFileTypes: true });
@@ -268,7 +309,7 @@ export async function listExerciseMeta(includeDrafts = false) {
     return results.sort((a, b) => a.name.localeCompare(b.name));
 }
 export async function getExerciseDetail(name) {
-    const exercisesDir = join(CONTENT_ROOT, 'exercises');
+    const exercisesDir = join(SHARED_CONTENT_ROOT, 'exercises');
     const indexPath = join(exercisesDir, name, 'index.md');
     if (!existsSync(indexPath)) {
         throw new RangeError(`Exercise "${name}" not found. Check content/exercises/${name}/index.md exists.`);
@@ -299,7 +340,7 @@ export async function getExerciseDetail(name) {
     };
 }
 export async function getExerciseStep(name, step) {
-    const exercisesDir = join(CONTENT_ROOT, 'exercises');
+    const exercisesDir = join(SHARED_CONTENT_ROOT, 'exercises');
     const stepsDir = join(exercisesDir, name, 'steps');
     if (!existsSync(stepsDir)) {
         throw new RangeError(`Exercise "${name}" not found.`);

package/dist/server.js

@@ -17,12 +17,24 @@ import { GET_COMPOSITION_PATTERN_TOOL, handleGetCompositionPattern } from './too
 import { GET_EMPHASIS_SCALE_TOOL, handleGetEmphasisScale } from './tools/get-emphasis-scale.js';
 import { GET_COMPLETENESS_MAP_TOOL, handleGetCompletenessMap } from './tools/get-completeness-map.js';
 import { LINK_SESSION_TOOL, handleLinkSession } from './tools/link-session.js';
-import { SET_THEME_TOOL, handleSetTheme } from './tools/set-theme.js';
-import { APPLY_INFERRED_THEME_TOOL, handleApplyInferredTheme } from './tools/apply-inferred-theme.js';
-import { NAVIGATE_TOOL, handleNavigate } from './tools/navigate.js';
-import { SET_INSTANCE_VARIANT_TOOL, handleSetInstanceVariant } from './tools/set-instance-variant.js';
-import { SPOTLIGHT_TOOL, handleSpotlight } from './tools/spotlight.js';
+import { SET_SITE_CONTENT_TOOL, handleSetSiteContent } from './tools/set-site-content.js';
+import { handleSetTheme } from './tools/set-theme.js';
+import { handleSetSkin } from './tools/set-skin.js';
+import { handleSetMode } from './tools/set-mode.js';
+import { handleSetContrast } from './tools/set-contrast.js';
+import { handleApplyInferredTheme } from './tools/apply-inferred-theme.js';
+import { handleNavigate } from './tools/navigate.js';
+import { handleSetInstanceVariant } from './tools/set-instance-variant.js';
+import { handleSpotlight } from './tools/spotlight.js';
+// Session-enact tools register via the single-source list (JUNE-739) so the
+// registration surface and the reconciliation tests read the same array.
+import { SESSION_ENACT_TOOLS } from './tools/session-tools.js';
 import { GET_MARKER_CAPTURE_TOOL, handleGetMarkerCapture } from './tools/get-marker-capture.js';
+import { RENDER_MARKER_CAPTURE_TOOL, MARKER_CARD_RESOURCE, handleRenderMarkerCapture, readMarkerCardResource, } from './tools/render-marker-capture.js';
+import { MARKER_CARD_URI } from './surface/marker-card.js';
+import { FETCH_MARKER_CROP_TOOL, handleFetchMarkerCrop } from './tools/fetch-marker-crop.js';
+import { RENDER_SURFACE_TOOL, SURFACE_EVENT_TOOL, AGENT_SURFACE_RESOURCE, handleRenderSurface, handleSurfaceEvent, readAgentSurfaceResource, } from './tools/render-surface.js';
+import { AGENT_SURFACE_URI } from './surface/agent-surface.js';
 import { createProvider } from './provider.js';
 import { RemoteContentProvider } from './remote-provider.js';
 /**
@@ -61,12 +73,13 @@ export async function createRunsnativeServer() {
             GET_EMPHASIS_SCALE_TOOL,
             GET_COMPLETENESS_MAP_TOOL,
             LINK_SESSION_TOOL,
-            SET_THEME_TOOL,
-            APPLY_INFERRED_THEME_TOOL,
-            NAVIGATE_TOOL,
-            SET_INSTANCE_VARIANT_TOOL,
-            SPOTLIGHT_TOOL,
+            SET_SITE_CONTENT_TOOL,
+            ...SESSION_ENACT_TOOLS,
             GET_MARKER_CAPTURE_TOOL,
+            RENDER_MARKER_CAPTURE_TOOL,
+            FETCH_MARKER_CROP_TOOL,
+            RENDER_SURFACE_TOOL,
+            SURFACE_EVENT_TOOL,
         ],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -101,8 +114,16 @@ export async function createRunsnativeServer() {
                 return handleGetCompletenessMap();
             case 'link_session':
                 return handleLinkSession(request.params.arguments ?? {});
+            case 'set_site_content':
+                return handleSetSiteContent(request.params.arguments ?? {});
             case 'set_theme':
                 return handleSetTheme(request.params.arguments ?? {});
+            case 'set_skin':
+                return handleSetSkin(request.params.arguments ?? {});
+            case 'set_mode':
+                return handleSetMode(request.params.arguments ?? {});
+            case 'set_contrast':
+                return handleSetContrast(request.params.arguments ?? {});
             case 'apply_inferred_theme':
                 return handleApplyInferredTheme(request.params.arguments ?? {});
             case 'navigate':
@@ -113,6 +134,14 @@ export async function createRunsnativeServer() {
                 return handleSpotlight(request.params.arguments ?? {});
             case 'get_marker_capture':
                 return handleGetMarkerCapture(request.params.arguments ?? {});
+            case 'render_marker_capture':
+                return handleRenderMarkerCapture();
+            case 'fetch_marker_crop':
+                return handleFetchMarkerCrop(request.params.arguments ?? {});
+            case 'render_surface':
+                return handleRenderSurface(request.params.arguments ?? {});
+            case 'surface_event':
+                return handleSurfaceEvent(request.params.arguments ?? {});
             default:
                 throw new Error(`Unknown tool: ${request.params.name}`);
         }
@@ -121,12 +150,16 @@ export async function createRunsnativeServer() {
     // host reads the resource and renders it in a sandboxed iframe; each document
     // is fully self-contained (bundle + runtime + CSS inlined by the seam).
     server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-        resources: [GATHERING_CARD_RESOURCE],
+        resources: [GATHERING_CARD_RESOURCE, MARKER_CARD_RESOURCE, AGENT_SURFACE_RESOURCE],
     }));
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         switch (request.params.uri) {
             case GATHERING_CARD_URI:
                 return readGatheringCardResource();
+            case MARKER_CARD_URI:
+                return readMarkerCardResource();
+            case AGENT_SURFACE_URI:
+                return readAgentSurfaceResource();
             default:
                 throw new Error(`Unknown resource: ${request.params.uri}`);
         }

package/dist/surface/agent-surface.js

@@ -0,0 +1,183 @@
+/**
+ * The agent-surface MCP-App shell (JUNE-793) — the generic host-side render
+ * target for the Mukadra engine's suspend/resume Surface protocol.
+ *
+ * Unlike the hand-authored gathering-card / marker-card shells (which each
+ * render ONE known component), this shell mounts whatever `SurfaceSpec` the
+ * engine returns (`component` ref + `props`) and closes the render → interact →
+ * resume loop for ANY surface. That is the mechanism this ticket proves —
+ * authoring a specific surface example is deliberately out of scope (JUNE-793).
+ *
+ * Static shell, data-free by design (same seam invariant as gathering-card):
+ * the per-instance spec arrives at runtime via the MCP Apps tool-result
+ * notification and is rendered client-side with DOM APIs; nothing user- or
+ * engine-authored is interpolated into markup here.
+ *
+ * Host ↔ component resume-leg convention: a surface component signals the
+ * user's typed response by dispatching a `surface:submit` CustomEvent whose
+ * `detail` is the payload. The shell forwards it to the engine via the
+ * `surface_event` server tool. A fallback submit control is always present so
+ * the loop is walkable even before a component emits that event.
+ */
+import { packageSurface } from './package-surface.js';
+export const AGENT_SURFACE_URI = 'ui://runsnative/agent-surface.html';
+const SURFACE_CSS = `
+/* Shell defaults in the lowest layer so injected token-engine CSS always wins. */
+@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-border-default: #e2e8f0;
+    --run-color-focus-ring: #2563eb;
+  }
+}
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  color: var(--run-color-text-primary);
+  padding: 12px;
+}
+#placeholder { font-size: 13px; color: var(--run-color-text-secondary); padding: 8px 2px; }
+.surface-frame {
+  max-width: 480px;
+  border: 1px solid var(--run-color-border-default);
+  border-radius: 12px;
+  background: var(--run-color-surface-default);
+  padding: 16px;
+  display: none;
+  flex-direction: column;
+  gap: 12px;
+}
+.surface-frame.is-ready { display: flex; }
+.surface-ref { font-size: 11px; color: var(--run-color-text-secondary); letter-spacing: 0.02em; }
+.surface-mount { display: flex; flex-direction: column; gap: 8px; }
+.surface-fallback { display: flex; gap: 8px; align-items: center; }
+.surface-fallback input {
+  flex: 1; padding: 6px 8px; font: inherit;
+  border: 1px solid var(--run-color-border-default); border-radius: 6px;
+}
+.surface-status { font-size: 12px; color: var(--run-color-text-secondary); min-height: 1.2em; }
+.surface-status.is-expired { color: #b45309; }
+`;
+const SURFACE_BODY = `
+<div id="placeholder">Waiting for a surface…</div>
+<section class="surface-frame" id="frame" aria-live="polite">
+  <div class="surface-ref" id="surface-ref"></div>
+  <div class="surface-mount" id="mount"></div>
+  <div class="surface-fallback">
+    <input id="fallback-input" type="text" placeholder="Your response…" aria-label="Surface response" />
+    <run-button id="submit-btn" variant="primary" size="sm">Submit</run-button>
+  </div>
+  <div class="surface-status" id="status"></div>
+</section>
+`;
+// Data-free by design: the spec and its props arrive via the tool-result
+// notification and are applied with DOM APIs only. A surface component signals
+// its response by dispatching `surface:submit` (detail = payload); the shell
+// also carries a plain fallback control so the loop is always walkable.
+const SURFACE_APP_SCRIPT = `
+const { App } = globalThis.__MCP_APP_SDK__;
+
+// ComponentRef '<ns>:<name>@<ver>' → the '<name>' tag, sanitized to the safe
+// custom-element charset so a hostile spec can never break out of the tag.
+function tagFromRef(ref) {
+  const name = String(ref == null ? '' : ref).split(':').pop().split('@')[0];
+  const safe = name.replace(/[^a-z0-9-]/gi, '').toLowerCase();
+  return safe && safe.includes('-') ? safe : null;
+}
+
+let mounted = null;
+
+function mountSpec(spec) {
+  const frame = document.getElementById('frame');
+  const mount = document.getElementById('mount');
+  mount.textContent = '';
+  document.getElementById('surface-ref').textContent = spec && spec.component ? String(spec.component) : '';
+
+  const tag = spec && tagFromRef(spec.component);
+  if (tag) {
+    const el = document.createElement(tag);
+    const props = spec && spec.props && typeof spec.props === 'object' ? spec.props : {};
+    for (const [k, v] of Object.entries(props)) {
+      if (v == null) continue;
+      // Primitive props ride as attributes; richer props as element properties.
+      if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+        el.setAttribute(k, String(v));
+      } else {
+        try { el[k] = v; } catch (_) { /* read-only prop — skip */ }
+      }
+    }
+    // The component's own submit gesture: dispatch surface:submit(detail=payload).
+    el.addEventListener('surface:submit', (e) => submit(e && e.detail));
+    mount.appendChild(el);
+    mounted = el;
+  } else {
+    // Unknown/undeclared component — render the ref so the surface is never
+    // blank (the real component arrives when a specific surface is authored).
+    const note = document.createElement('div');
+    note.className = 'surface-ref';
+    note.textContent = 'Surface component not available in this host bundle.';
+    mount.appendChild(note);
+  }
+
+  document.getElementById('placeholder').style.display = 'none';
+  document.getElementById('status').className = 'surface-status';
+  document.getElementById('status').textContent = '';
+  frame.classList.add('is-ready');
+}
+
+async function submit(payload) {
+  const status = document.getElementById('status');
+  status.className = 'surface-status';
+  status.textContent = 'Sending your response…';
+  try {
+    const result = await app.callServerTool({
+      name: 'surface_event',
+      arguments: { event_type: 'submit', payload: payload },
+    });
+    const sc = result && result.structuredContent;
+    const kind = sc && sc.status;
+    if (kind === 'chained' && sc.spec) {
+      mountSpec(sc.spec);            // successor surface — render and loop.
+    } else if (kind === 'expired') {
+      status.className = 'surface-status is-expired';
+      status.textContent = 'This surface is no longer active. Ask the agent to render it again.';
+    } else if (kind === 'not_found') {
+      status.textContent = 'That surface is no longer available.';
+    } else {
+      status.textContent = 'Response sent — the agent is continuing.';
+    }
+  } catch (e) {
+    status.textContent = 'Could not send your response — see the conversation.';
+  }
+}
+
+const app = new App({ name: 'runsnative-agent-surface', version: '1.0.0' }, {});
+
+app.ontoolresult = (params) => {
+  if (params && params.isError) {
+    document.getElementById('placeholder').textContent =
+      'Could not load the surface — see the conversation for details.';
+    return;
+  }
+  const sc = params && params.structuredContent;
+  if (sc && sc.spec) mountSpec(sc.spec);
+};
+
+document.getElementById('submit-btn').addEventListener('click', () => {
+  const input = document.getElementById('fallback-input');
+  submit({ value: input.value });
+});
+
+await app.connect();
+`;
+export function buildAgentSurfaceHtml(assets) {
+    return packageSurface({
+        title: 'Agent Surface — RunsNative',
+        bodyHtml: SURFACE_BODY,
+        css: SURFACE_CSS,
+        appScript: SURFACE_APP_SCRIPT,
+    }, assets);
+}

package/dist/surface/engine-gateway-transport.js

@@ -0,0 +1,82 @@
+// trim(): trailing whitespace from setx/cmd wrappers silently corrupts URLs and
+// the Authorization header (KUKAMANGA-wide env-read rule; see bridge-client.ts).
+const ENGINE_URL = (process.env['MUKADRA_ENGINE_URL'] ?? 'http://127.0.0.1:8100').trim();
+const ENGINE_TOKEN = process.env['MUKADRA_ENGINE_TOKEN']?.trim();
+/** The agent whose gateway hosts the surfaces (forms `{id}` in the path). */
+const AGENT_ID = (process.env['MUKADRA_AGENT_ID'] ?? 'runsnative-org').trim();
+function authHeaders(extra = {}) {
+    const headers = { ...extra };
+    if (ENGINE_TOKEN)
+        headers['Authorization'] = `Bearer ${ENGINE_TOKEN}`;
+    return headers;
+}
+/**
+ * Read a gateway short-circuit error out of a non-OK response body. The engine
+ * returns typed errors (`{ kind, stage, ... }`); the `stage` discriminant is
+ * what the host uses to separate a governor rejection from a dispatch 404. When
+ * the body is not the expected shape, fall back to a dispatch-stage error so an
+ * unparseable failure is never mistaken for an expired-surface state.
+ */
+async function readGatewayError(res, fallbackRoute) {
+    let body = null;
+    try {
+        body = await res.json();
+    }
+    catch {
+        body = null;
+    }
+    const b = (body ?? {});
+    const stage = typeof b['stage'] === 'string' ? b['stage'] : 'dispatch';
+    const kind = typeof b['kind'] === 'string' ? b['kind'] : 'surface_not_found';
+    return {
+        kind,
+        stage,
+        route: typeof b['route'] === 'string' ? b['route'] : fallbackRoute,
+        correlation_id: typeof b['correlation_id'] === 'string' ? b['correlation_id'] : undefined,
+        message: typeof b['message'] === 'string' ? b['message'] : `engine responded ${res.status}`,
+    };
+}
+/** The default transport, targeting the Mukadra engine gateway over HTTP. */
+export const engineGatewayTransport = {
+    async queryRoute(route, ctx) {
+        const url = `${ENGINE_URL}/agents/${encodeURIComponent(AGENT_ID)}/surfaces/query?route=${encodeURIComponent(route)}`;
+        const headers = authHeaders();
+        // Session identity as a header, never a URL param (privacy rule).
+        if (ctx.agentSessionId)
+            headers['X-Agent-Session-Id'] = ctx.agentSessionId;
+        if (ctx.correlationId)
+            headers['X-Correlation-ID'] = ctx.correlationId;
+        let res;
+        try {
+            res = await fetch(url, { method: 'GET', headers });
+        }
+        catch (e) {
+            return { ok: false, error: { kind: 'transport_error', stage: 'dispatch', route, message: String(e) } };
+        }
+        if (!res.ok) {
+            return { ok: false, error: await readGatewayError(res, route) };
+        }
+        const value = (await res.json());
+        return { ok: true, value };
+    },
+    async postEvent(surfaceName, req) {
+        const url = `${ENGINE_URL}/agents/${encodeURIComponent(AGENT_ID)}/surfaces/${encodeURIComponent(surfaceName)}/event`;
+        const headers = authHeaders({ 'Content-Type': 'application/json' });
+        if (req.correlation_id)
+            headers['X-Correlation-ID'] = req.correlation_id;
+        let res;
+        try {
+            res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(req) });
+        }
+        catch (e) {
+            return { ok: false, error: { kind: 'transport_error', stage: 'dispatch', message: String(e) } };
+        }
+        if (!res.ok) {
+            return { ok: false, error: await readGatewayError(res) };
+        }
+        const value = (await res.json());
+        return { ok: true, value };
+    },
+};
+/** The agent id the transport targets — exported for host-side messaging/tests. */
+export const ENGINE_AGENT_ID = AGENT_ID;

package/dist/surface/gathering-card.js

@@ -60,7 +60,7 @@ const CARD_BODY = `
 <div id="placeholder">Waiting for your gathering…</div>
 <article class="gathering-card" id="card">
   <div class="card-host-bar">
-    <run-text id="card-brand" variant="label" as="span" size="sm" color="theme"></run-text>
+    <run-text id="card-brand" variant="label" as="span" size="sm" color="brand"></run-text>
     <run-badge variant="info" size="sm" pill>Yours</run-badge>
   </div>
   <run-text id="card-title" variant="title" as="h3" size="md"></run-text>