pmx-canvas 0.1.35 → 0.2.0

package/src/server/ax-state.ts

@@ -13,7 +13,7 @@ export interface PmxAxFocusState {
 // ── New enums ──────────────────────────────────────────────────────
 export type PmxAxEventKind =
   | 'prompt' | 'assistant-message' | 'tool-start' | 'tool-result'
-  | 'failure' | 'approval' | 'steering' | 'command';
+  | 'failure' | 'approval' | 'steering' | 'command' | 'note';
 export type PmxAxEvidenceKind =
   | 'logs' | 'tool-result' | 'screenshot' | 'file' | 'diff' | 'test-output';
 export type PmxAxWorkItemStatus = 'todo' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
@@ -157,6 +157,22 @@ export interface PmxAxFocusContext extends PmxAxFocusState {
   nodes: AgentContextNode[];
 }
 
+// ── Pending agent-actionable digest (open canvas-bound items) ──────
+export interface PendingAxActivityItem {
+  kind: 'work-item' | 'approval-gate' | 'elicitation' | 'mode-request';
+  id: string;
+  title: string;
+  status: string;
+  nodeIds: string[];
+  source: PmxAxSource | null;
+}
+
+// ── Delivery lead block (compact, un-truncated; for per-turn injection) ──
+export interface PmxAxDeliveryContext {
+  pendingSteering: PmxAxSteeringMessage[];
+  pendingActivity: PendingAxActivityItem[];
+}
+
 export interface PmxAxContext {
   version: 1;
   generatedAt: string;
@@ -164,6 +180,10 @@ export interface PmxAxContext {
     nodeCount: number;
     edgeCount: number;
   };
+  // Compact, loop-safe lead block of what's awaiting the agent right now
+  // (undelivered steering + open work/approvals/elicitations/mode requests).
+  // Sits ABOVE the full dump so a host adapter can inject it un-truncated.
+  delivery: PmxAxDeliveryContext;
   pinned: PmxAxPinnedContext;
   focus: PmxAxFocusContext;
   workItems: PmxAxWorkItem[];
@@ -176,6 +196,44 @@ export interface PmxAxContext {
   host: PmxAxHostCapability | null;
 }
 
+const OPEN_AX_WORK_STATUSES = new Set<PmxAxWorkItemStatus>(['todo', 'in-progress', 'blocked']);
+
+/**
+ * Open, agent-actionable canvas-bound AX items (open work items + pending approval
+ * gates / elicitations / mode requests). Unlike steering (a directive routed through
+ * the claim/ack delivery queue), these are STATE the human curates in the browser —
+ * they fire `ax-state-changed` (so resource-subscribers are pushed canvas://ax-work),
+ * but an adapterless client that only POLLS the delivery surface never saw them.
+ * Optionally excludes items the consumer itself originated (loop prevention),
+ * mirroring getPendingSteering. Shared by the MCP delivery surface and the HTTP
+ * context lead block so the digest never drifts between the two.
+ */
+export function buildPendingAxActivity(state: PmxAxState, consumer?: string): PendingAxActivityItem[] {
+  const notMine = (source: PmxAxSource | null) => !consumer || source !== consumer;
+  const out: PendingAxActivityItem[] = [];
+  for (const w of state.workItems) {
+    if (OPEN_AX_WORK_STATUSES.has(w.status) && notMine(w.source)) {
+      out.push({ kind: 'work-item', id: w.id, title: w.title, status: w.status, nodeIds: w.nodeIds, source: w.source });
+    }
+  }
+  for (const g of state.approvalGates) {
+    if (g.status === 'pending' && notMine(g.source)) {
+      out.push({ kind: 'approval-gate', id: g.id, title: g.title, status: g.status, nodeIds: g.nodeIds, source: g.source });
+    }
+  }
+  for (const e of state.elicitations) {
+    if (e.status === 'pending' && notMine(e.source)) {
+      out.push({ kind: 'elicitation', id: e.id, title: e.prompt, status: e.status, nodeIds: e.nodeIds, source: e.source });
+    }
+  }
+  for (const m of state.modeRequests) {
+    if (m.status === 'pending' && notMine(m.source)) {
+      out.push({ kind: 'mode-request', id: m.id, title: m.reason ? `${m.mode}: ${m.reason}` : `mode: ${m.mode}`, status: m.status, nodeIds: m.nodeIds, source: m.source });
+    }
+  }
+  return out;
+}
+
 const AX_SOURCES = new Set<PmxAxSource>(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system']);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -205,7 +263,34 @@ function normalizeNodeIds(value: unknown, validNodeIds?: Set<string>): string[]
   return ids;
 }
 
-const AX_EVENT_KINDS = new Set<PmxAxEventKind>(['prompt', 'assistant-message', 'tool-start', 'tool-result', 'failure', 'approval', 'steering', 'command']);
+const AX_EVENT_KINDS = new Set<PmxAxEventKind>(['prompt', 'assistant-message', 'tool-start', 'tool-result', 'failure', 'approval', 'steering', 'command', 'note']);
+
+// ── Activity ingestion (harness-forwarded tool/session events) ─────
+// A normalized activity the agent's harness forwards; the board auto-reacts.
+// The precise activity kind is preserved on the recorded event's `data.activityKind`;
+// only the (coarser) timeline event kind is constrained to PmxAxEventKind.
+export type PmxAxActivityKind =
+  | 'tool-start' | 'tool-result' | 'failure' | 'error'
+  | 'session-start' | 'session-end' | 'command' | 'note';
+const AX_ACTIVITY_KINDS = new Set<PmxAxActivityKind>([
+  'tool-start', 'tool-result', 'failure', 'error', 'session-start', 'session-end', 'command', 'note',
+]);
+const ACTIVITY_TO_EVENT_KIND: Record<PmxAxActivityKind, PmxAxEventKind> = {
+  'tool-start': 'tool-start',
+  'tool-result': 'tool-result',
+  'failure': 'failure',
+  'error': 'failure',
+  'session-start': 'assistant-message',
+  'session-end': 'assistant-message',
+  'command': 'command',
+  'note': 'assistant-message',
+};
+export function isAxActivityKind(value: unknown): value is PmxAxActivityKind {
+  return typeof value === 'string' && AX_ACTIVITY_KINDS.has(value as PmxAxActivityKind);
+}
+export function mapAxActivityKindToEventKind(kind: PmxAxActivityKind): PmxAxEventKind {
+  return ACTIVITY_TO_EVENT_KIND[kind];
+}
 
 // ── Command registry (plan-004 Phase 5) ────────────────────────
 // Named, registry-gated PMX intents — NOT arbitrary execution. Invoking a command
@@ -725,6 +810,7 @@ export function normalizeAxState(input: unknown, validNodeIds?: Set<string>): Pm
 
 export function buildAxContext(input: {
   layout: CanvasLayout;
+  delivery: PmxAxDeliveryContext;
   pinned: PmxAxPinnedContext;
   focus: PmxAxFocusState;
   focusNodes: AgentContextNode[];
@@ -744,6 +830,7 @@ export function buildAxContext(input: {
       nodeCount: input.layout.nodes.length,
       edgeCount: input.layout.edges.length,
     },
+    delivery: input.delivery,
     pinned: input.pinned,
     focus: {
       ...input.focus,

package/src/server/ax-wait.ts

@@ -0,0 +1,56 @@
+import { canvasState } from './canvas-state.js';
+
+/** Hard ceiling on a single blocking wait, regardless of the requested timeout. */
+export const AX_WAIT_MAX_MS = 120000;
+
+export interface AxWaitResult<T> {
+  /** Latest value, or null if the item does not exist / vanished mid-wait. */
+  value: T | null;
+  /** True only when the item still exists and is still pending after the wait. */
+  pending: boolean;
+}
+
+/**
+ * Block until a canvas-bound AX item resolves (its status leaves `pending`), the
+ * timeout elapses, or the request aborts — the server side of report primitive D
+ * ("gates that actually gate"). Resolves immediately when the item is already
+ * resolved, missing, or `timeoutMs <= 0` (a plain single read). Subscribes to the
+ * `ax` change channel and always disposes the listener + timer.
+ */
+export async function waitForAxResolution<T extends { status: string }>(opts: {
+  read: () => T | null;
+  isResolved: (value: T) => boolean;
+  timeoutMs: number;
+  signal?: AbortSignal;
+}): Promise<AxWaitResult<T>> {
+  const { read, isResolved } = opts;
+  const timeoutMs = Math.max(0, Math.min(opts.timeoutMs, AX_WAIT_MAX_MS));
+  const pendingOf = (v: T | null): boolean => (v ? !isResolved(v) : false);
+
+  const current = read();
+  if (!current || isResolved(current) || timeoutMs === 0 || opts.signal?.aborted) {
+    return { value: current, pending: pendingOf(current) };
+  }
+
+  return new Promise<AxWaitResult<T>>((resolve) => {
+    let done = false;
+    const finish = (): void => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      dispose();
+      opts.signal?.removeEventListener('abort', onSettle);
+      const v = read();
+      resolve({ value: v, pending: pendingOf(v) });
+    };
+    const onSettle = finish;
+    const check = (type: string): void => {
+      if (type !== 'ax') return;
+      const v = read();
+      if (!v || isResolved(v)) finish();
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    const dispose = canvasState.onChange(check);
+    opts.signal?.addEventListener('abort', onSettle, { once: true });
+  });
+}

package/src/server/canvas-operations.ts

@@ -19,7 +19,7 @@ import {
 import { mutationHistory } from './mutation-history.js';
 import { computeGroupBounds, findOpenCanvasPosition } from './placement.js';
 import { searchNodes } from './spatial-analysis.js';
-import { getCanvasNodeTitle, serializeCanvasNodeCompact, type SerializedCanvasNode } from './canvas-serialization.js';
+import { getCanvasNodeTitle } from './canvas-serialization.js';
 import { computeAutoArrange } from '../shared/auto-arrange.js';
 import {
   applyJsonRenderStreamPatches,
@@ -52,7 +52,7 @@ export function setCanvasLayoutUpdateEmitter(emitter: (() => void) | null): void
   canvasLayoutUpdateEmitter = emitter;
 }
 
-function emitCanvasLayoutUpdate(): void {
+export function emitCanvasLayoutUpdate(): void {
   canvasLayoutUpdateEmitter?.();
 }
 
@@ -125,12 +125,6 @@ interface CanvasCreateGroupInput {
   childLayout?: CanvasArrangeMode;
 }
 
-export interface CanvasBatchOperation {
-  op: string;
-  assign?: string;
-  args?: Record<string, unknown>;
-}
-
 interface CanvasNodeLookupInput {
   id?: string;
   search?: string;
@@ -1659,323 +1653,3 @@ export function fitCanvasView(options: CanvasFitViewOptions = {}): CanvasFitView
   canvasState.setViewport(viewport);
   return { ok: true, viewport: canvasState.viewport, nodeCount: targetNodes.length, bounds };
 }
-
-function isPlainRecord(value: unknown): value is Record<string, unknown> {
-  return !!value && typeof value === 'object' && !Array.isArray(value);
-}
-
-function resolveBatchRefs(value: unknown, refs: Record<string, unknown>): unknown {
-  if (typeof value === 'string' && value.startsWith('$')) {
-    const path = value.slice(1).split('.');
-    let current: unknown = refs[path[0] ?? ''];
-    if (path.length === 1 && isPlainRecord(current) && typeof current.id === 'string') return current.id;
-    for (const segment of path.slice(1)) {
-      if (!isPlainRecord(current) && !Array.isArray(current)) return undefined;
-      current = (current as Record<string, unknown>)[segment];
-    }
-    return current;
-  }
-  if (Array.isArray(value)) return value.map((item) => resolveBatchRefs(item, refs));
-  if (isPlainRecord(value)) {
-    const resolved: Record<string, unknown> = {};
-    for (const [key, child] of Object.entries(value)) {
-      resolved[key] = resolveBatchRefs(child, refs);
-    }
-    return resolved;
-  }
-  return value;
-}
-
-function serializeCreatedNode(node: CanvasNodeState): SerializedCanvasNode {
-  return serializeCanvasNodeCompact(node);
-}
-
-export async function executeCanvasBatch(
-  operations: CanvasBatchOperation[],
-): Promise<{
-  ok: boolean;
-  results: Array<Record<string, unknown>>;
-  refs: Record<string, unknown>;
-  failedIndex?: number;
-  error?: string;
-}> {
-  const refs: Record<string, unknown> = {};
-  const results: Array<Record<string, unknown>> = [];
-
-  for (let index = 0; index < operations.length; index++) {
-    const operation = operations[index];
-    const args = isPlainRecord(operation.args) ? resolveBatchRefs(operation.args, refs) : {};
-    if (!isPlainRecord(args)) {
-      return {
-        ok: false,
-        failedIndex: index,
-        error: `Operation ${index} has invalid args.`,
-        results,
-        refs,
-      };
-    }
-
-    try {
-      let result: Record<string, unknown>;
-      switch (operation.op) {
-        case 'node.add': {
-          const type = typeof args.type === 'string' ? args.type : 'markdown';
-          if (type === 'html-primitive') {
-            throw new Error('Batch html-primitive creation is not supported yet. Use node.add with type "html" and generated html, or create the primitive through MCP/HTTP/CLI first.');
-          }
-          if (type === 'webpage') {
-            const content = typeof args.url === 'string' && args.url.trim().length > 0
-              ? args.url
-              : typeof args.content === 'string'
-                ? args.content
-                : undefined;
-            const created = addCanvasNode({
-              type: 'webpage',
-              ...(typeof args.title === 'string' ? { title: args.title } : {}),
-              ...(content ? { content } : {}),
-              ...(isPlainRecord(args.data) ? { data: args.data } : {}),
-              ...(typeof args.x === 'number' ? { x: args.x } : {}),
-              ...(typeof args.y === 'number' ? { y: args.y } : {}),
-              ...(typeof args.width === 'number' ? { width: args.width } : {}),
-              ...(typeof args.height === 'number' ? { height: args.height } : {}),
-              ...(args.strictSize === true ? { strictSize: true } : {}),
-              defaultWidth: 520,
-              defaultHeight: 420,
-            });
-            const fetch = await refreshCanvasWebpageNode(created.id);
-            const refreshed = canvasState.getNode(created.id) ?? created.node;
-            result = {
-              ok: true,
-              ...serializeCreatedNode(refreshed),
-              fetch: fetch.ok
-                ? { ok: true }
-                : { ok: false, error: fetch.error ?? 'Failed to fetch webpage content.' },
-              ...(fetch.ok ? {} : { error: fetch.error }),
-            };
-          } else {
-            const data = isPlainRecord(args.data) ? args.data : {};
-            const htmlData = type === 'html'
-              ? {
-                  ...data,
-                  ...(typeof args.html === 'string' ? { html: args.html } : {}),
-                  ...(typeof args.summary === 'string' ? { summary: args.summary } : {}),
-                  ...(typeof args.agentSummary === 'string' ? { agentSummary: args.agentSummary } : {}),
-                  ...(typeof args.description === 'string' ? { description: args.description } : {}),
-                  ...(Array.isArray(args.embeddedNodeIds) ? { embeddedNodeIds: args.embeddedNodeIds } : {}),
-                  ...(Array.isArray(args.embeddedUrls) ? { embeddedUrls: args.embeddedUrls } : {}),
-                }
-              : data;
-            const created = addCanvasNode({
-              type: type as CanvasNodeState['type'],
-              ...(typeof args.title === 'string' ? { title: args.title } : {}),
-              ...(typeof args.content === 'string' ? { content: args.content } : {}),
-              ...(Object.keys(htmlData).length > 0 ? { data: htmlData } : {}),
-              ...(typeof args.x === 'number' ? { x: args.x } : {}),
-              ...(typeof args.y === 'number' ? { y: args.y } : {}),
-              ...(typeof args.width === 'number' ? { width: args.width } : {}),
-              ...(typeof args.height === 'number' ? { height: args.height } : {}),
-              ...(args.strictSize === true ? { strictSize: true } : {}),
-              defaultWidth: type === 'html'
-                ? 720
-                : type === 'markdown'
-                  ? MARKDOWN_NODE_DEFAULT_SIZE.width
-                  : type === 'mcp-app'
-                    ? MCP_APP_NODE_DEFAULT_SIZE.width
-                    : type === 'image'
-                      ? IMAGE_NODE_DEFAULT_SIZE.width
-                      : type === 'ledger'
-                        ? LEDGER_NODE_DEFAULT_SIZE.width
-                        : 360,
-              defaultHeight: type === 'html'
-                ? 640
-                : type === 'markdown'
-                  ? MARKDOWN_NODE_DEFAULT_SIZE.height
-                  : type === 'mcp-app'
-                    ? MCP_APP_NODE_DEFAULT_SIZE.height
-                    : type === 'image'
-                      ? IMAGE_NODE_DEFAULT_SIZE.height
-                      : type === 'ledger'
-                        ? LEDGER_NODE_DEFAULT_SIZE.height
-                        : 200,
-              fileMode: 'auto',
-            });
-            result = { ok: true, ...serializeCreatedNode(created.node) };
-          }
-          break;
-        }
-        case 'node.update': {
-          const id = typeof args.id === 'string' ? args.id : '';
-          const node = canvasState.getNode(id);
-          if (!node) throw new Error(`Node "${id}" not found.`);
-          const patch: Partial<CanvasNodeState> = {};
-          if (typeof args.x === 'number' || typeof args.y === 'number') {
-            patch.position = {
-              x: typeof args.x === 'number' ? args.x : node.position.x,
-              y: typeof args.y === 'number' ? args.y : node.position.y,
-            };
-          }
-          if (typeof args.width === 'number' || typeof args.height === 'number') {
-            patch.size = {
-              width: typeof args.width === 'number' ? args.width : node.size.width,
-              height: typeof args.height === 'number' ? args.height : node.size.height,
-            };
-          }
-          if (typeof args.collapsed === 'boolean') patch.collapsed = args.collapsed;
-          if (typeof args.pinned === 'boolean') patch.pinned = args.pinned;
-          if (args.dockPosition === null || args.dockPosition === 'left' || args.dockPosition === 'right') {
-            patch.dockPosition = args.dockPosition;
-          }
-          if (typeof args.title === 'string' || typeof args.content === 'string' || typeof args.arrangeLocked === 'boolean' || typeof args.strictSize === 'boolean' || isPlainRecord(args.data)) {
-            patch.data = {
-              ...node.data,
-              ...(typeof args.title === 'string' ? { title: args.title } : {}),
-              ...(typeof args.content === 'string' ? { content: args.content } : {}),
-              ...(typeof args.arrangeLocked === 'boolean' ? { arrangeLocked: args.arrangeLocked } : {}),
-              ...(typeof args.strictSize === 'boolean' ? { strictSize: args.strictSize } : {}),
-              ...(isPlainRecord(args.data) ? args.data : {}),
-            };
-          }
-          canvasState.updateNode(id, patch);
-          const updated = canvasState.getNode(id);
-          result = { ok: true, ...(updated ? serializeCreatedNode(updated) : { id }) };
-          break;
-        }
-        case 'node.remove': {
-          const id = typeof args.id === 'string' ? args.id : '';
-          const { removed } = removeCanvasNode(id);
-          if (!removed) throw new Error(`Node "${id}" not found.`);
-          result = { ok: true, id, removed: true };
-          break;
-        }
-        case 'graph.add': {
-          const created = createCanvasGraphNode({
-            graphType: String(args.graphType ?? 'line'),
-            data: Array.isArray(args.data) ? args.data.filter((item): item is Record<string, unknown> => isPlainRecord(item)) : [],
-            ...(typeof args.title === 'string' ? { title: args.title } : {}),
-            ...(typeof args.xKey === 'string' ? { xKey: args.xKey } : {}),
-            ...(typeof args.yKey === 'string' ? { yKey: args.yKey } : {}),
-            ...(typeof args.zKey === 'string' ? { zKey: args.zKey } : {}),
-            ...(typeof args.nameKey === 'string' ? { nameKey: args.nameKey } : {}),
-            ...(typeof args.valueKey === 'string' ? { valueKey: args.valueKey } : {}),
-            ...(typeof args.axisKey === 'string' ? { axisKey: args.axisKey } : {}),
-            ...(Array.isArray(args.metrics) ? { metrics: args.metrics.filter((m): m is string => typeof m === 'string') } : {}),
-            ...(Array.isArray(args.series) ? { series: args.series.filter((s): s is string => typeof s === 'string') } : {}),
-            ...(typeof args.barKey === 'string' ? { barKey: args.barKey } : {}),
-            ...(typeof args.lineKey === 'string' ? { lineKey: args.lineKey } : {}),
-            ...(args.aggregate === 'sum' || args.aggregate === 'count' || args.aggregate === 'avg'
-              ? { aggregate: args.aggregate }
-              : {}),
-            ...(typeof args.color === 'string' ? { color: args.color } : {}),
-            ...(typeof args.barColor === 'string' ? { barColor: args.barColor } : {}),
-            ...(typeof args.lineColor === 'string' ? { lineColor: args.lineColor } : {}),
-            ...(typeof args.height === 'number' ? { height: args.height } : {}),
-            ...(typeof args.x === 'number' ? { x: args.x } : {}),
-            ...(typeof args.y === 'number' ? { y: args.y } : {}),
-            ...(typeof args.width === 'number' ? { width: args.width } : {}),
-            ...(typeof args.nodeHeight === 'number' ? { heightPx: args.nodeHeight } : {}),
-            ...(args.strictSize === true ? { strictSize: true } : {}),
-          });
-          result = {
-            ok: true,
-            ...serializeCreatedNode(created.node),
-            url: created.url,
-            spec: created.spec,
-          };
-          break;
-        }
-        case 'edge.add': {
-          const added = addCanvasEdge({
-            ...(typeof args.from === 'string' ? { from: args.from } : {}),
-            ...(typeof args.to === 'string' ? { to: args.to } : {}),
-            ...(typeof args.fromSearch === 'string' ? { fromSearch: args.fromSearch } : {}),
-            ...(typeof args.toSearch === 'string' ? { toSearch: args.toSearch } : {}),
-            type: String(args.type) as CanvasEdge['type'],
-            ...(typeof args.label === 'string' ? { label: args.label } : {}),
-            ...(typeof args.style === 'string' ? { style: args.style as CanvasEdge['style'] } : {}),
-            ...(typeof args.animated === 'boolean' ? { animated: args.animated } : {}),
-          });
-          result = { ok: true, ...added };
-          break;
-        }
-        case 'group.create': {
-          const created = createCanvasGroup({
-            ...(typeof args.title === 'string' ? { title: args.title } : {}),
-            ...(Array.isArray(args.childIds) ? { childIds: args.childIds.filter((id): id is string => typeof id === 'string') } : {}),
-            ...(typeof args.x === 'number' ? { x: args.x } : {}),
-            ...(typeof args.y === 'number' ? { y: args.y } : {}),
-            ...(typeof args.width === 'number' ? { width: args.width } : {}),
-            ...(typeof args.height === 'number' ? { height: args.height } : {}),
-            ...(typeof args.color === 'string' ? { color: args.color } : {}),
-            ...(args.childLayout === 'grid' || args.childLayout === 'column' || args.childLayout === 'flow'
-              ? { childLayout: args.childLayout }
-              : {}),
-          });
-          result = { ok: true, ...serializeCreatedNode(created.node) };
-          break;
-        }
-        case 'group.add': {
-          const groupId = typeof args.groupId === 'string' ? args.groupId : '';
-          const childIds = Array.isArray(args.childIds) ? args.childIds.filter((id): id is string => typeof id === 'string') : [];
-          const ok = canvasState.groupNodes(groupId, childIds, {
-            preservePositions: args.childLayout === undefined,
-            ...(args.childLayout === 'grid' || args.childLayout === 'column' || args.childLayout === 'flow'
-              ? { layout: args.childLayout }
-              : {}),
-          });
-          if (!ok) throw new Error('Group not found or no valid children.');
-          const group = canvasState.getNode(groupId);
-          result = { ok: true, ...(group ? serializeCreatedNode(group) : { id: groupId }) };
-          break;
-        }
-        case 'group.remove': {
-          const groupId = typeof args.groupId === 'string' ? args.groupId : '';
-          const ok = canvasState.ungroupNodes(groupId);
-          if (!ok) throw new Error('Group not found or empty.');
-          result = { ok: true, groupId };
-          break;
-        }
-        case 'pin.set':
-        case 'pin.add':
-        case 'pin.remove': {
-          const ids = Array.isArray(args.nodeIds) ? args.nodeIds.filter((id): id is string => typeof id === 'string') : [];
-          result = {
-            ok: true,
-            ...setCanvasContextPins(ids, operation.op === 'pin.set' ? 'set' : operation.op === 'pin.add' ? 'add' : 'remove'),
-          };
-          break;
-        }
-        case 'snapshot.save': {
-          const snapshot = saveCanvasSnapshot(typeof args.name === 'string' ? args.name : '');
-          if (!snapshot) throw new Error('Failed to save snapshot.');
-          result = { ok: true, snapshot };
-          break;
-        }
-        case 'arrange': {
-          const layout =
-            args.layout === 'column' || args.layout === 'flow' || args.layout === 'grid'
-              ? args.layout
-              : 'grid';
-          result = { ok: true, ...arrangeCanvasNodes(layout) };
-          break;
-        }
-        default:
-          throw new Error(`Unsupported batch operation "${operation.op}".`);
-      }
-
-      results.push(result);
-      if (typeof operation.assign === 'string' && operation.assign.trim().length > 0) {
-        refs[operation.assign] = result;
-      }
-    } catch (error) {
-      return {
-        ok: false,
-        failedIndex: index,
-        error: error instanceof Error ? error.message : String(error),
-        results,
-        refs,
-      };
-    }
-  }
-
-  return { ok: true, results, refs };
-}

package/src/server/canvas-schema.ts

@@ -244,7 +244,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Sandboxed iframe node rendered from inline HTML.',
     endpoint: '/api/canvas/node',
-    mcpTool: 'canvas_add_html_node',
+    mcpTool: 'canvas_node (action:"add", type:"html")',
     fields: [
       { name: 'html', type: 'string', required: false, description: 'HTML document or fragment rendered in the sandboxed iframe.', aliases: ['content', 'stdin'] },
       { name: 'summary', type: 'string', required: false, description: 'Explicit agent-readable summary. If omitted, PMX derives one from visible HTML text.' },
@@ -281,7 +281,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'virtual-node',
     description: 'Reusable sandboxed HTML communication primitive rendered as an html node.',
     endpoint: '/api/canvas/node',
-    mcpTool: 'canvas_add_html_primitive',
+    mcpTool: 'canvas_node (action:"add", type:"html", primitive:"<kind>")',
     fields: [
       { name: 'kind', type: 'HtmlPrimitiveKind', required: true, description: 'Primitive kind. See top-level htmlPrimitives for the supported catalog.' },
       { name: 'data', type: 'record<string, unknown>', required: false, description: 'Primitive-specific JSON object payload.' },