pmx-canvas 0.1.35 → 0.2.0

package/skills/pmx-canvas/evals/evals.json

@@ -93,7 +93,7 @@
       "assertions": [
         {
           "name": "reads-pinned-context",
-          "description": "Reads the canvas://pinned-context MCP resource (not just canvas_get_layout)",
+          "description": "Reads the canvas://pinned-context MCP resource (not just canvas_query action:layout)",
           "type": "output_check"
         },
         {
@@ -135,7 +135,7 @@
       "id": 6,
       "name": "status-dashboard-updates",
       "prompt": "I'm running a deployment pipeline. Create a dashboard on the canvas showing: Build (passing), Unit Tests (running), Integration Tests (queued), Deploy to Staging (queued). Then update it - unit tests just passed and integration tests are now running.",
-      "expected_output": "Creates status nodes with semantic colors, arranges as grid dashboard, then updates nodes in place using canvas_update_node (not delete+recreate) to reflect new state.",
+      "expected_output": "Creates status nodes with semantic colors, arranges as grid dashboard, then updates nodes in place using canvas_node action:update (not delete+recreate) to reflect new state.",
       "assertions": [
         {
           "name": "initial-dashboard",
@@ -144,7 +144,7 @@
         },
         {
           "name": "updates-in-place",
-          "description": "Uses canvas_update_node to change status (not remove+add)",
+          "description": "Uses canvas_node action:update to change status (not remove+add)",
           "type": "output_check"
         },
         {

package/skills/pmx-canvas/references/codex-app-adapter.md

@@ -21,9 +21,9 @@ tools, resources, and `canvas://ax-context`; use the CLI only as a fallback or f
 
 - Opens the live PMX workbench in the Codex in-app Browser.
 - Uses MCP tools/resources for all agent-side operations.
-- Reads `canvas://ax-context` or `canvas_get_ax` for pinned and focused context.
-- Sets AX focus through `canvas_set_ax_focus` with `source: "codex"` when the focus change comes
-  from Codex-hosted steering.
+- Reads `canvas://ax-context` or `canvas_ax_state { action: "get" }` for pinned and focused context.
+- Sets AX focus through `canvas_ax_state { action: "set-focus" }` with `source: "codex"` when the
+  focus change comes from Codex-hosted steering.
 - Keeps all persistent PMX state in `.pmx-canvas/canvas.db`; Codex does not own canvas state.
 
 ## Setup
@@ -70,7 +70,8 @@ in the Codex in-app Browser, usually `http://127.0.0.1:4313/workbench` or
    inspect rendered artifacts.
 4. Use MCP tools for agent operations: create/update nodes, pin nodes, read layout, and read AX
    context.
-5. When Codex wants to mark the current attention target, call:
+5. When Codex wants to mark the current attention target, call
+   `canvas_ax_state { action: "set-focus", … }` with:
 
 ```json
 {
@@ -79,27 +80,39 @@ in the Codex in-app Browser, usually `http://127.0.0.1:4313/workbench` or
 }
 ```
 
-against `canvas_set_ax_focus`.
-
 ## Context Contract
 
 Codex agents should treat PMX AX context as host-native working context:
 
 - `canvas://pinned-context` is the explicit human-curated node set.
-- `canvas://ax-context` combines pins, focus, and surface metadata.
-- `canvas_get_ax` returns both persisted AX state and agent-ready context.
+- `canvas://ax-context` combines pins, focus, and surface metadata, plus a compact
+  loop-safe `delivery: { pendingSteering, pendingActivity }` lead block
+  (`GET /api/canvas/ax/context?consumer=codex` filters out Codex-originated items).
+- `canvas_ax_state { action: "get" }` returns both persisted AX state and agent-ready context.
 - Focus is a current attention target, not a command to ignore the rest of the repository.
 
+The adapterless MCP+Browser path is poll-based: there is no automatic prompt injection,
+so a board click does not wake the current turn. Codex agents poll
+`canvas_ax_delivery { action: "claim" }` (steering + `pendingActivity`) and act/ack explicitly. The
+loop-closing surfaces work over MCP today even without a dedicated extension:
+
+- **Self-report work** with `canvas_ingest_activity` (the board auto-reacts: a failed
+  tool → a blocked work item + review + evidence). Automatic forwarding of Codex's own
+  tool hooks would need a Codex adapter; manual ingestion works now.
+- **Block on a decision** with `canvas_ax_gate { kind, action: "await", id }` (it long-polls PMX
+  until the human resolves the gate in the Browser or the timeout elapses) instead of looping on
+  `canvas_ax_state { action: "get" }`.
+
 ## Live-Test Checklist
 
 1. Open `http://127.0.0.1:4313/workbench` in the Codex in-app Browser first so the user can see
    all later canvas mutations.
 2. Confirm the PMX MCP server is configured for the workspace.
-3. Call `canvas_get_ax` and confirm it returns `ok: true`.
+3. Call `canvas_ax_state { action: "get" }` and confirm it returns `ok: true`.
 4. Add or reuse a node, then pin it from the browser or with `canvas_pin_nodes`.
 5. Read `canvas://ax-context` and confirm the pinned node appears.
-6. Call `canvas_set_ax_focus` with `source: "codex"` and a real node ID.
-7. Read `canvas_get_ax` again and confirm `state.focus.source` is `codex`.
+6. Call `canvas_ax_state { action: "set-focus", source: "codex" }` with a real node ID.
+7. Read `canvas_ax_state { action: "get" }` again and confirm `state.focus.source` is `codex`.
 8. Refresh the browser and confirm the workbench still shows the same state.
 
 ## Adapter Boundary

package/skills/pmx-canvas/references/github-copilot-app-adapter.md

@@ -48,6 +48,36 @@ panel.
 - Reads `/api/canvas/ax/context` and injects pinned/focused context from
   `onUserPromptSubmitted`.
 - Exposes adapter actions for status, AX context refresh, AX focus, and explicit session steering.
+
+### Agent behavior — steering is gated, not pushed
+
+`onUserPromptSubmitted` injects the whole `/api/canvas/ax/context` (pins, focus, work
+items, approval gates, and `timeline.pendingSteering`) as hidden context — but only
+when the **pin/focus gate is open** (`pinned.count > 0 || focus.nodeIds.length > 0`),
+and it is clipped to a char budget. Three consequences the adapter/agent must honor:
+
+1. A steering board must **stay pinned** (or its button must also emit `ax.focus.set`
+   on the board node) to hold the gate open.
+2. A sandbox button click does **not** wake a turn — a human message does. The click
+   only enqueues the steer.
+3. The agent must **act on injected `pendingSteering` / `pendingActivity` and then ack**
+   (`canvas_ax_delivery { action: "mark" }`), or it re-injects every gated turn.
+
+To be robust to the char clip, prefer injecting the compact loop-safe lead block from
+`GET /api/canvas/ax/context?consumer=copilot` (`delivery.pendingSteering` +
+`delivery.pendingActivity`) **above** the full dump.
+
+### Closing the loop (optional, recommended)
+
+- **Forward tool/session hooks** (`onPreToolUse` / `onPostToolUse` /
+  `onPostToolUseFailure` / `onSessionStart` / `onSessionEnd` / `onErrorOccurred`) to
+  `POST /api/canvas/ax/activity` (`canvas_ingest_activity`) so the board reflects the
+  agent's real work automatically (a failed tool → a blocked work item + review +
+  evidence).
+- **Await gates** with `canvas_ax_gate { kind, action: "await", id }` (or surface a native modal
+  and await the PMX result) so an approval gate actually blocks the agent until the human resolves it.
+
+See [`docs/ax-host-adapter-contract.md`](../../../docs/ax-host-adapter-contract.md).
 - Keeps all persistent PMX state in `.pmx-canvas/canvas.db`; the extension does not own canvas
   state.
 
@@ -127,5 +157,5 @@ global instruction to ignore the rest of the repository.
 For non-Copilot agents, use the same core primitives directly:
 
 - HTTP: `/api/canvas/ax`, `/api/canvas/ax/context`, `/api/canvas/ax/focus`
-- MCP: `canvas://ax`, `canvas://ax-context`, `canvas_get_ax`, `canvas_set_ax_focus`
+- MCP: `canvas://ax`, `canvas://ax-context`, `canvas_ax_state { action: "get" }`, `canvas_ax_state { action: "set-focus" }`
 - CLI: `pmx-canvas ax status|context|focus`

package/src/cli/agent.ts

@@ -15,6 +15,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { openUrlInExternalBrowser, wrapCanvasAutomationScript } from '../server/server.js';
+import { HttpOperationInvoker, OperationError } from '../server/operations/index.js';
 import { DEFAULT_EXCALIDRAW_ELEMENTS } from '../server/diagram-presets.js';
 import {
   ALL_SEMANTIC_WATCH_EVENT_TYPES,
@@ -158,6 +159,26 @@ async function api(
   return json;
 }
 
+// Operation-registry invoker (plan-005): node CRUD, layout reads, edge,
+// pin/search/history/undo/redo, and snapshot commands build their HTTP request
+// from the shared route table instead of hand-written paths.
+// Error handling mirrors api(): operation failures and connection failures
+// die with the same JSON error shape.
+async function invokeOperation(name: string, input: Record<string, unknown>): Promise<unknown> {
+  const base = getBaseUrl();
+  try {
+    return await new HttpOperationInvoker(base).invoke(name, input);
+  } catch (error) {
+    if (error instanceof OperationError) {
+      die(error.message);
+    }
+    die(
+      `Cannot connect to pmx-canvas at ${base}: ${error instanceof Error ? error.message : String(error)}`,
+      `Start the server first: pmx-canvas --no-open`,
+    );
+  }
+}
+
 // ── Flag parsing ─────────────────────────────────────────────
 
 function parseFlags(args: string[]): { positional: string[]; flags: Record<string, string | true> } {
@@ -1162,13 +1183,13 @@ cmd('node add', 'Add a node to the canvas', [
   const type = (flags.type as string) || 'markdown';
 
   if (type === 'json-render') {
-    const result = await api('POST', '/api/canvas/json-render', await buildJsonRenderRequestBody(flags));
+    const result = await invokeOperation('jsonrender.add', await buildJsonRenderRequestBody(flags));
     output(result);
     return;
   }
 
   if (type === 'graph') {
-    const result = await api('POST', '/api/canvas/graph', await buildGraphRequestBody(flags));
+    const result = await invokeOperation('graph.add', await buildGraphRequestBody(flags));
     output(result);
     return;
   }
@@ -1179,13 +1200,13 @@ cmd('node add', 'Add a node to the canvas', [
   }
 
   if (type === 'html-primitive') {
-    const result = await api('POST', '/api/canvas/node', await buildHtmlPrimitiveRequestBody(flags));
+    const result = await invokeOperation('node.add', await buildHtmlPrimitiveRequestBody(flags));
     output(result);
     return;
   }
 
   if (type === 'html' && getStringFlag(flags, 'primitive', 'kind')) {
-    const result = await api('POST', '/api/canvas/node', await buildHtmlPrimitiveRequestBody(flags));
+    const result = await invokeOperation('node.add', await buildHtmlPrimitiveRequestBody(flags));
     output(result);
     return;
   }
@@ -1245,7 +1266,7 @@ cmd('node add', 'Add a node to the canvas', [
     }
   }
 
-  const result = await api('POST', '/api/canvas/node', body);
+  const result = await invokeOperation('node.add', body);
   output(result);
 });
 
@@ -1310,7 +1331,7 @@ cmd('graph add', 'Add a graph node to the canvas', [
   const { flags } = parseFlags(args);
   if (flags.help || flags.h) return showCommandHelp('graph add');
 
-  const result = await api('POST', '/api/canvas/graph', await buildGraphRequestBody(flags));
+  const result = await invokeOperation('graph.add', await buildGraphRequestBody(flags));
   output(result);
 });
 
@@ -1383,7 +1404,7 @@ cmd('node list', 'List all nodes on the canvas', [
   const { flags } = parseFlags(args);
   if (flags.help || flags.h) return showCommandHelp('node list');
 
-  const layout = (await api('GET', '/api/canvas/state')) as { nodes: Array<Record<string, unknown>> };
+  const layout = (await invokeOperation('layout.get', {})) as { nodes: Array<Record<string, unknown>> };
   let nodes = layout.nodes;
 
   if (flags.type && flags.type !== true) {
@@ -1414,7 +1435,7 @@ cmd('node get', 'Get a node by ID', [
   const id = positional[0];
   if (!id) die('Missing node ID', 'pmx-canvas node get <node-id>');
 
-  const result = await api('GET', `/api/canvas/node/${encodeURIComponent(id)}`) as Record<string, unknown>;
+  const result = await invokeOperation('node.get', { id }) as Record<string, unknown>;
   const requestedFields = collectRequestedFields(args, flags);
   if (requestedFields.length > 0) {
     const picked = Object.fromEntries(requestedFields.map((field) => [field, resolveNodeFieldValue(result, field)]));
@@ -1496,7 +1517,7 @@ cmd('node update', 'Update a node by ID', [
   }
 
   if (x !== undefined || y !== undefined || width !== undefined || frameHeight !== undefined || arrangeLocked !== undefined) {
-    const existing = await api('GET', `/api/canvas/node/${encodeURIComponent(id)}`) as {
+    const existing = await invokeOperation('node.get', { id }) as {
       position: { x: number; y: number };
       size: { width: number; height: number };
       data: Record<string, unknown>;
@@ -1545,7 +1566,7 @@ cmd('node update', 'Update a node by ID', [
     );
   }
 
-  const result = await api('PATCH', `/api/canvas/node/${encodeURIComponent(id)}`, body);
+  const result = await invokeOperation('node.update', { id, ...body });
   output(result);
 });
 
@@ -1560,7 +1581,7 @@ cmd('node remove', 'Remove a node from the canvas', [
   const id = positional[0];
   if (!id) die('Missing node ID', 'pmx-canvas node remove <node-id>');
 
-  const result = await api('DELETE', `/api/canvas/node/${encodeURIComponent(id)}`);
+  const result = await invokeOperation('node.remove', { id });
   output(result);
 });
 
@@ -1604,7 +1625,7 @@ cmd('edge add', 'Add an edge between two nodes', [
   if (typeof flags.style === 'string') body.style = flags.style;
   if (flags.animated) body.animated = true;
 
-  const result = await api('POST', '/api/canvas/edge', body);
+  const result = await invokeOperation('edge.add', body);
   output(result);
 });
 
@@ -1629,7 +1650,7 @@ cmd('edge remove', 'Remove an edge by ID', [
   const id = positional[0];
   if (!id) die('Missing edge ID', 'pmx-canvas edge remove <edge-id>');
 
-  const result = await api('DELETE', '/api/canvas/edge', { edge_id: id });
+  const result = await invokeOperation('edge.remove', { edge_id: id });
   output(result);
 });
 
@@ -1644,7 +1665,7 @@ cmd('search', 'Search nodes by title or content', [
   const query = positional[0] || (typeof flags.query === 'string' ? flags.query : '');
   if (!query) die('Missing search query', 'pmx-canvas search "query"');
 
-  const result = await api('GET', `/api/canvas/search?q=${encodeURIComponent(query)}`);
+  const result = await invokeOperation('search', { q: query });
   output(result);
 });
 
@@ -1815,14 +1836,14 @@ cmd('pin', 'Manage context pins', [
   }
 
   if (flags.clear) {
-    const result = await api('POST', '/api/canvas/context-pins', { nodeIds: [] });
+    const result = await invokeOperation('pin.set', { nodeIds: [] });
     output(result);
     return;
   }
 
   // --set: positional args are node IDs
   if (positional.length > 0 || flags.set) {
-    const result = await api('POST', '/api/canvas/context-pins', { nodeIds: positional });
+    const result = await invokeOperation('pin.set', { nodeIds: positional });
     output(result);
     return;
   }
@@ -2314,7 +2335,7 @@ cmd('undo', 'Undo the last canvas mutation', [
   const { flags } = parseFlags(args);
   if (flags.help || flags.h) return showCommandHelp('undo');
 
-  const result = await api('POST', '/api/canvas/undo');
+  const result = await invokeOperation('canvas.undo', {});
   output(result);
 });
 
@@ -2325,7 +2346,7 @@ cmd('redo', 'Redo the last undone mutation', [
   const { flags } = parseFlags(args);
   if (flags.help || flags.h) return showCommandHelp('redo');
 
-  const result = await api('POST', '/api/canvas/redo');
+  const result = await invokeOperation('canvas.redo', {});
   output(result);
 });
 
@@ -2338,7 +2359,7 @@ cmd('history', 'Show canvas mutation history', [
   const { flags } = parseFlags(args);
   if (flags.help || flags.h) return showCommandHelp('history');
 
-  const result = await api('GET', '/api/canvas/history') as Record<string, unknown>;
+  const result = await invokeOperation('history.get', {}) as Record<string, unknown>;
   if (flags.summary) {
     output(summarizeHistoryResult(result));
     return;
@@ -2359,7 +2380,7 @@ cmd('snapshot save', 'Save a named snapshot of the current canvas', [
   if (flags.help || flags.h) return showCommandHelp('snapshot save');
 
   const name = requireFlag(flags, 'name', 'pmx-canvas snapshot save --name "my-snapshot"');
-  const result = await api('POST', '/api/canvas/snapshots', { name });
+  const result = await invokeOperation('snapshot.save', { name });
   output(result);
 });
 
@@ -2373,17 +2394,17 @@ cmd('snapshot list', 'List saved snapshots', [
   const { flags } = parseFlags(args);
   if (flags.help || flags.h) return showCommandHelp('snapshot list');
 
-  const params = new URLSearchParams();
   const limit = optionalNumberFlag(flags, 'limit', 'Use a positive integer, e.g. --limit 50');
   const query = getStringFlag(flags, 'query', 'q');
   const before = getStringFlag(flags, 'before');
   const after = getStringFlag(flags, 'after');
-  if (limit !== undefined) params.set('limit', String(limit));
-  if (query) params.set('q', query);
-  if (before) params.set('before', before);
-  if (after) params.set('after', after);
-  if (flags.all) params.set('all', 'true');
-  const result = await api('GET', `/api/canvas/snapshots${params.size > 0 ? `?${params.toString()}` : ''}`);
+  const result = await invokeOperation('snapshot.list', {
+    ...(limit !== undefined ? { limit } : {}),
+    ...(query ? { q: query } : {}),
+    ...(before ? { before } : {}),
+    ...(after ? { after } : {}),
+    ...(flags.all ? { all: true } : {}),
+  });
   output(result);
 });
 
@@ -2400,7 +2421,7 @@ cmd('snapshot gc', 'Delete old snapshots, keeping the newest N', [
   if (!dryRun && !flags.yes) {
     die('Destructive operation requires --yes flag', 'Preview with: pmx-canvas snapshot gc --keep 20 --dry-run');
   }
-  const result = await api('POST', '/api/canvas/snapshots/gc', {
+  const result = await invokeOperation('snapshot.gc', {
     ...(keep !== undefined ? { keep } : {}),
     dryRun,
   });
@@ -2417,7 +2438,7 @@ cmd('snapshot restore', 'Restore canvas from a snapshot', [
   const id = positional[0];
   if (!id) die('Missing snapshot ID or name', 'pmx-canvas snapshot restore <snapshot-id-or-name>');
 
-  const result = await api('POST', `/api/canvas/snapshots/${encodeURIComponent(id)}`);
+  const result = await invokeOperation('snapshot.restore', { id });
   output(result);
 });
 
@@ -2431,7 +2452,7 @@ cmd('snapshot delete', 'Delete a saved snapshot', [
   const id = positional[0];
   if (!id) die('Missing snapshot ID', 'pmx-canvas snapshot delete <snapshot-id>');
 
-  const result = await api('DELETE', `/api/canvas/snapshots/${encodeURIComponent(id)}`);
+  const result = await invokeOperation('snapshot.delete', { id });
   output(result);
 });
 
@@ -2439,7 +2460,7 @@ async function runSnapshotDiff(args: string[]): Promise<void> {
   const { positional, flags } = parseFlags(args);
   const snapshot = positional[0];
   if (!snapshot) die('Missing snapshot ID or name', 'pmx-canvas snapshot diff <snapshot-id-or-name>');
-  const result = await api('GET', `/api/canvas/snapshots/${encodeURIComponent(snapshot)}/diff`);
+  const result = await invokeOperation('snapshot.diff', { id: snapshot });
   output(result);
 }
 

package/src/client/nodes/ExtAppFrame.tsx

@@ -97,6 +97,66 @@ export function resolveExtAppSandbox(value: unknown): string {
     : DEFAULT_EXT_APP_SANDBOX;
 }
 
+export function buildExtAppAxBridgeScript(axToken: string, nodeId: string): string {
+  return `<script data-pmx-canvas-ax-bridge>
+(function () {
+  const PMX_AX_TOKEN = ${JSON.stringify(axToken)};
+  const PMX_AX_NODE_ID = ${JSON.stringify(nodeId)};
+  window.PMX_AX = window.PMX_AX || {};
+  const pending = new Map();
+  const ackListeners = [];
+  let seq = 0;
+  window.PMX_AX.emit = function (type, payload) {
+    seq += 1;
+    const correlationId = PMX_AX_NODE_ID + '-' + seq + '-' + (Date.now ? Date.now() : 0);
+    return new Promise(function (resolve) {
+      const timer = setTimeout(function () {
+        pending.delete(correlationId);
+        resolve({ ok: false, status: 504, code: 'ax-ack-timeout', error: 'ax-ack-timeout' });
+      }, 10000);
+      pending.set(correlationId, function (result) { clearTimeout(timer); resolve(result); });
+      window.parent.postMessage({
+        source: 'pmx-canvas-ax',
+        token: PMX_AX_TOKEN,
+        nodeId: PMX_AX_NODE_ID,
+        correlationId: correlationId,
+        interaction: { type: String(type), payload: payload && typeof payload === 'object' ? payload : {} },
+      }, '*');
+    });
+  };
+  window.PMX_AX.on = function (eventType, cb) {
+    if (eventType === 'ack' && typeof cb === 'function') ackListeners.push(cb);
+  };
+  window.addEventListener('message', function (event) {
+    const m = event.data;
+    if (!m || m.source !== 'pmx-canvas-ax-ack' || m.token !== PMX_AX_TOKEN) return;
+    const result = m.result || { ok: false };
+    const resolver = m.correlationId ? pending.get(m.correlationId) : undefined;
+    if (resolver) { pending.delete(m.correlationId); resolver(result); }
+    for (let i = 0; i < ackListeners.length; i += 1) {
+      try { ackListeners[i](result, m.interaction || null); } catch (e) {}
+    }
+    try { window.dispatchEvent(new CustomEvent('pmx-ax-ack', { detail: { result: result, interaction: m.interaction || null } })); } catch (e) {}
+  });
+})();
+</script>`;
+}
+
+export function injectExtAppAxBridgeScript(html: string, axBridgeScript: string): string {
+  if (!axBridgeScript) return html;
+  const headMatch = /<head\b[^>]*>/i.exec(html);
+  if (headMatch?.index !== undefined) {
+    const insertAt = headMatch.index + headMatch[0].length;
+    return `${html.slice(0, insertAt)}${axBridgeScript}${html.slice(insertAt)}`;
+  }
+  const bodyMatch = /<body\b[^>]*>/i.exec(html);
+  if (bodyMatch?.index !== undefined) {
+    const insertAt = bodyMatch.index + bodyMatch[0].length;
+    return `${html.slice(0, insertAt)}${axBridgeScript}${html.slice(insertAt)}`;
+  }
+  return `${axBridgeScript}${html}`;
+}
+
 function positiveDimension(value: number, fallback: number): number {
   if (Number.isFinite(value) && value > 0) return Math.round(value);
   if (Number.isFinite(fallback) && fallback > 0) return Math.round(fallback);
@@ -164,31 +224,39 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const axEnabled = axCaps?.enabled === true && typeof html === 'string' && html.length > 0;
   const axToken = useMemo(() => `ax-${crypto.randomUUID()}`, []);
   const axBridgeScript = axEnabled
-    ? `<script data-pmx-canvas-ax-bridge>window.PMX_AX={emit:function(t,p){window.parent.postMessage({source:'pmx-canvas-ax',token:${JSON.stringify(axToken)},nodeId:${JSON.stringify(nodeId)},interaction:{type:String(t),payload:p&&typeof p==='object'?p:{}}},'*');}};</script>`
+    ? buildExtAppAxBridgeScript(axToken, nodeId)
     : '';
-  const iframeDocument = useIframeDocument((html ?? '') + axBridgeScript, iframeSandbox);
+  const iframeDocument = useIframeDocument(injectExtAppAxBridgeScript(html ?? '', axBridgeScript), iframeSandbox);
 
   useEffect(() => {
     if (!axEnabled) return;
     function onAxMessage(event: MessageEvent) {
       if (event.source !== iframeRef.current?.contentWindow) return;
       const data = event.data as {
-        source?: string; token?: string; nodeId?: string;
+        source?: string; token?: string; nodeId?: string; correlationId?: string;
         interaction?: { type?: unknown; payload?: unknown };
       } | null;
       if (!data || data.source !== 'pmx-canvas-ax' || data.token !== axToken || data.nodeId !== nodeId) return;
       const interaction = data.interaction;
       if (!interaction || typeof interaction.type !== 'string') return;
+      const interactionType = interaction.type;
       void submitAxInteractionFromClient({
-        type: interaction.type,
+        type: interactionType,
         sourceNodeId: nodeId,
         sourceSurface: 'mcp-app',
         ...(interaction.payload && typeof interaction.payload === 'object'
           ? { payload: interaction.payload as Record<string, unknown> }
           : {}),
       }).then((res) => {
-        if (res.ok) showToast('context', 'AX interaction', interaction.type as string, [nodeId]);
+        if (res.ok) showToast('context', 'AX interaction', interactionType, [nodeId]);
         else showToast('remove', 'AX interaction rejected', res.error ?? res.code ?? '', [nodeId]);
+        iframeRef.current?.contentWindow?.postMessage({
+          source: 'pmx-canvas-ax-ack',
+          token: axToken,
+          ...(data.correlationId ? { correlationId: data.correlationId } : {}),
+          interaction: { type: interactionType },
+          result: res,
+        }, '*');
       });
     }
     window.addEventListener('message', onAxMessage);

package/src/client/nodes/HtmlNode.tsx

@@ -57,22 +57,31 @@ export function HtmlNode({
       // nodeId are a second gate, not the only one.
       if (event.source !== iframeRef.current?.contentWindow) return;
       const data = event.data as {
-        source?: string; token?: string; nodeId?: string;
+        source?: string; token?: string; nodeId?: string; correlationId?: string;
         interaction?: { type?: unknown; payload?: unknown };
       } | null;
       if (!data || data.source !== 'pmx-canvas-ax' || data.token !== axToken || data.nodeId !== node.id) return;
       const interaction = data.interaction;
       if (!interaction || typeof interaction.type !== 'string') return;
+      const interactionType = interaction.type;
       void submitAxInteractionFromClient({
-        type: interaction.type,
+        type: interactionType,
         sourceNodeId: node.id,
         sourceSurface: 'html-node',
         ...(interaction.payload && typeof interaction.payload === 'object'
           ? { payload: interaction.payload as Record<string, unknown> }
           : {}),
       }).then((res) => {
-        if (res.ok) showToast('context', 'AX interaction', interaction.type as string, [node.id]);
+        if (res.ok) showToast('context', 'AX interaction', interactionType, [node.id]);
         else showToast('remove', 'AX interaction rejected', res.error ?? res.code ?? '', [node.id]);
+        // Report #55: ack back to the surface so it can self-confirm (e.g. "queued ✓").
+        iframeRef.current?.contentWindow?.postMessage({
+          source: 'pmx-canvas-ax-ack',
+          token: axToken,
+          ...(data.correlationId ? { correlationId: data.correlationId } : {}),
+          interaction: { type: interactionType },
+          result: res,
+        }, '*');
       });
     }
     window.addEventListener('message', onAxMessage);

package/src/client/nodes/McpAppNode.tsx

@@ -89,22 +89,31 @@ function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boo
     function onAxMessage(event: MessageEvent) {
       if (event.source !== iframeRef.current?.contentWindow) return;
       const data = event.data as {
-        source?: string; token?: string; nodeId?: string;
+        source?: string; token?: string; nodeId?: string; correlationId?: string;
         interaction?: { type?: unknown; payload?: unknown };
       } | null;
       if (!data || data.source !== 'pmx-canvas-ax' || data.token !== axToken || data.nodeId !== node.id) return;
       const interaction = data.interaction;
       if (!interaction || typeof interaction.type !== 'string') return;
+      const interactionType = interaction.type;
       void submitAxInteractionFromClient({
-        type: interaction.type,
+        type: interactionType,
         sourceNodeId: node.id,
         sourceSurface: axSurface,
         ...(interaction.payload && typeof interaction.payload === 'object'
           ? { payload: interaction.payload as Record<string, unknown> }
           : {}),
       }).then((res) => {
-        if (res.ok) showToast('context', 'AX interaction', interaction.type as string, [node.id]);
+        if (res.ok) showToast('context', 'AX interaction', interactionType, [node.id]);
         else showToast('remove', 'AX interaction rejected', res.error ?? res.code ?? '', [node.id]);
+        // Report #55: ack back to the viewer so the surface can self-confirm.
+        iframeRef.current?.contentWindow?.postMessage({
+          source: 'pmx-canvas-ax-ack',
+          token: axToken,
+          ...(data.correlationId ? { correlationId: data.correlationId } : {}),
+          interaction: { type: interactionType },
+          result: res,
+        }, '*');
       });
     }
     window.addEventListener('message', onAxMessage);

package/src/json-render/renderer/index.tsx

@@ -121,6 +121,9 @@ function buildAxHandlers(): Record<string, (params: Record<string, unknown>) =>
   const token = window.__PMX_CANVAS_AX_TOKEN__;
   const handlers: Record<string, (params: Record<string, unknown>) => void> = {};
   if (!nodeId || !token) return handlers;
+  // Declarative json-render boards are reflect-only: a spec action is fire-and-forget
+  // and confirmation arrives as a live `pmx-ax-update` (the work item appears). There
+  // is no JS surface for a Promise-style ack here, so we don't stamp a correlationId.
   for (const type of AX_INTERACTION_HANDLER_NAMES) {
     handlers[type] = (params: Record<string, unknown>) => {
       window.parent.postMessage({