pmx-canvas 0.1.36 → 0.2.1

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/ax-html-control-surface.md

@@ -0,0 +1,93 @@
+# AX HTML Control Surface — a blessed, copy-paste-safe recipe
+
+A canvas `html` node can be a live **AX control surface**: it emits AX interactions
+(create work, request approval, steer the agent, …) and reflects the current AX board
+back, all from inside the sandboxed iframe. The bridge is already injected for you —
+you do **not** need to read `axToken` from the URL or hand-post `pmx-canvas-ax`
+messages. Just opt the node in and use `window.PMX_AX`.
+
+## Opt in
+
+```js
+// MCP / SDK
+canvas_add_html_node({
+  title: "AX Control Room",
+  html: "<!-- see below -->",
+  axCapabilities: { enabled: true, allowed: ["ax.work.create", "ax.steer"] },
+});
+// HTTP: POST /api/canvas/node  { type:"html", title, html, axCapabilities }  (top-level html + axCapabilities both accepted)
+```
+
+Without `axCapabilities.enabled = true`, `window.PMX_AX` is **not** injected — the node
+renders but can't emit. `allowed` narrows what it may emit (never escalates the type's
+ceiling). Flip an existing node on with `canvas_node({ action: "update", id, axCapabilities: { enabled: true, allowed: [...] } })`.
+
+## Three footguns (this is why a hand-rolled node looks "inert")
+
+1. **The iframe is sandboxed opaque-origin** (no `allow-same-origin`). `localStorage`,
+   `sessionStorage`, and `document.cookie` **throw** — and an uncaught throw at script
+   start aborts the whole script, so the node renders blank/inert. Keep state in plain
+   JS variables (or `window.PMX_AX.state`); if you must touch storage, wrap it in
+   `try/catch`.
+2. **`window.PMX_AX.emit(type, payload)` is async.** It returns a Promise that resolves
+   with the result once the canvas acks it. `await` it (or `.then` / `window.PMX_AX.on('ack', cb)`).
+   Reading a result synchronously gets you `undefined`.
+3. **`ax.steer` is recorded, not delivered.** A successful emit (`{ ok: true }`) means
+   the steer was **queued** on the timeline — it does **not** wake or notify the active
+   agent. A cooperating host adapter must drain the delivery queue and call its native
+   send to create a visible turn (host-owned). Otherwise the steer is picked up on the
+   human's next turn. Label steering buttons honestly ("Queued for the agent's next turn").
+
+## Drop-in template (work + steer, with ack + live reflection)
+
+```html
+<style>
+  body { font: 13px system-ui; margin: 0; padding: 12px; }
+  button { cursor: pointer; }
+  #s { margin-left: 8px; color: #6b7280; }
+  ul { padding-left: 18px; }
+</style>
+<button id="add">+ Work item</button>
+<button id="steer">Steer agent</button>
+<span id="s"></span>
+<ul id="q"></ul>
+<script>
+  // In-memory only — NO localStorage/sessionStorage/cookies (sandboxed: they throw).
+  const $ = (id) => document.getElementById(id);
+  const flash = (msg) => { $('s').textContent = msg; setTimeout(() => { $('s').textContent = ''; }, 1500); };
+
+  function render(state) {
+    const items = (state && state.workItems) || [];
+    $('q').innerHTML = items.map((w) => '<li>[' + w.status + '] ' + w.title + '</li>').join('');
+  }
+
+  $('add').onclick = async () => {
+    const r = await window.PMX_AX.emit('ax.work.create', { title: 'New task' });
+    flash(r && r.ok ? 'queued ✓' : ('failed: ' + (r && (r.error || r.code))));
+  };
+  $('steer').onclick = async () => {
+    const r = await window.PMX_AX.emit('ax.steer', { message: 'Prioritize the auth refactor' });
+    // Honest: recorded/queued, NOT delivered to the live agent.
+    flash(r && r.ok ? 'queued for next turn ✓' : 'failed');
+  };
+
+  // Reflect: seeded once at load, then live via the pmx-ax-update event.
+  render(window.PMX_AX && window.PMX_AX.state);
+  window.addEventListener('pmx-ax-update', (e) => render(e.detail));
+</script>
+```
+
+## API surface (injected by PMX when opted in)
+
+- `window.PMX_AX.emit(type, payload) → Promise<{ ok, primitive?, status?, code?, error? }>`
+  — `ok:true` on accept; `ok:false` with `code`/`error` on reject; falls back to an
+  `ax-ack-timeout` result after 10s so `await` never hangs.
+- `window.PMX_AX.on('ack', (result, interaction) => …)` — also fires a `pmx-ax-ack`
+  CustomEvent; use instead of `await` if you prefer a listener.
+- `window.PMX_AX.state` — compact board snapshot `{ focus, workItems, approvalGates,
+  reviewAnnotations, elicitations, modeRequests, policy }` (human review text redacted).
+- `pmx-ax-update` window event — fires with the fresh snapshot on every AX change.
+
+Allowed `type`s are gated per node capability (see the node-capability matrix in
+`SKILL.md`). Emits are clamped to the surface's own node; the server re-validates every
+interaction — the bridge is convenience, not a trust boundary.

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,8 +80,6 @@ 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:
@@ -89,31 +88,31 @@ Codex agents should treat PMX AX context as host-native working 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_get_ax` returns both persisted AX state and agent-ready context.
+- `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_claim_ax_delivery` (steering + `pendingActivity`) and act/ack explicitly. The
+`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_await_approval` / `canvas_await_elicitation` /
-  `canvas_await_mode` (they long-poll PMX until the human resolves the gate in the
-  Browser or the timeout elapses) instead of looping on `canvas_get_ax`.
+- **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

@@ -52,20 +52,36 @@ panel.
 ### 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:
+items, approval gates, and the compact `delivery` lead block) 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. Read steering from **`delivery.pendingSteering`**
+(the compact, count-bearing block — newest-first, capped at 10), not the full
+`timeline.pendingSteering`. 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_mark_ax_delivery`), or it re-injects every gated turn.
+3. The agent must **act on injected `delivery.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
+To be robust to the char clip, prefer injecting that compact loop-safe lead block from
 `GET /api/canvas/ax/context?consumer=copilot` (`delivery.pendingSteering` +
-`delivery.pendingActivity`) **above** the full dump.
+`delivery.totalPending` / `delivery.omittedPending` + `delivery.pendingActivity`)
+**above** the full dump. When `omittedPending > 0`, drain the full FIFO backlog from
+`canvas_ax_delivery { action: "claim", consumer: "copilot" }` (oldest-first).
+
+#### Waking the agent from a canvas steer (#59) — adapter-owned
+
+Recording a browser-origin `ax.steer` does **not** wake the active session by itself
+(report #59); PMX only queues it (the `ok:true` emit ack = "recorded", not "delivered").
+To make a canvas **Steer** button actually create a visible turn, the adapter must, on
+its own cadence (e.g. an SSE subscription or poll), **drain**
+`canvas_ax_delivery { action: "claim", consumer: "copilot" }`, call the host's native
+send (`copilotSession.send` / the working `send_instruction` path) with each steer, then
+`canvas_ax_delivery { action: "mark" }` it (loop-safe). This wake is intentionally
+host-owned — PMX never imports the host SDK. Until the adapter wires it, a steering
+button must be labeled "queued for the agent's next turn", not "steer now".
 
 ### Closing the loop (optional, recommended)
 
@@ -74,9 +90,8 @@ To be robust to the char clip, prefer injecting the compact loop-safe lead block
   `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_await_approval` / `canvas_await_elicitation` /
-  `canvas_await_mode` (or surface a native modal and await the PMX result) so an
-  approval gate actually blocks the agent until the human resolves it.
+- **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
@@ -158,5 +173,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);
 }