pmx-canvas 0.1.11 → 0.1.13

package/src/mcp/server.ts

@@ -24,22 +24,18 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { isAbsolute, relative, resolve } from 'node:path';
 import { z } from 'zod';
-import {
-  createCanvas,
-  canvasState,
-  describeCanvasSchema,
-  validateStructuredCanvasPayload,
-  type PmxCanvas,
-} from '../server/index.js';
+import { canvasState, describeCanvasSchema, validateStructuredCanvasPayload } from '../server/index.js';
+import { createCanvasAccess, refreshCanvasAccess, type CanvasAccess } from './canvas-access.js';
 import { serializeNodeForAgentContext } from '../server/agent-context.js';
-import { emitPrimaryWorkbenchEvent, wrapCanvasAutomationScript } from '../server/server.js';
-import { searchNodes, buildSpatialContext, findNeighborhoods } from '../server/spatial-analysis.js';
-import { mutationHistory, diffLayouts, formatDiff } from '../server/mutation-history.js';
-import { buildCodeGraphSummary, formatCodeGraph } from '../server/code-graph.js';
-import { buildCanvasSummary, serializeCanvasLayout, serializeCanvasNode } from '../server/canvas-serialization.js';
+import { wrapCanvasAutomationScript } from '../server/server.js';
+import { buildSpatialContext, findNeighborhoods } from '../server/spatial-analysis.js';
+import { getCanvasNodeTitle, serializeCanvasLayout, serializeCanvasNode } from '../server/canvas-serialization.js';
 import { listBundledSkills, readBundledSkill } from '../server/bundled-skills.js';
 
-let canvas: PmxCanvas | null = null;
+let canvas: CanvasAccess | null = null;
+let resourceNotificationServer: McpServer | null = null;
+let localResourceNotificationsStarted = false;
+let remoteResourceNotificationsBaseUrl: string | null = null;
 
 const jsonRenderSpecSchema = z.union([
   z.object({
@@ -80,31 +76,140 @@ function safeWorkspacePath(pathLike: string): string {
   return resolved;
 }
 
-async function ensureCanvas(): Promise<PmxCanvas> {
+async function ensureCanvas(): Promise<CanvasAccess> {
   if (!canvas) {
-    const port = parseInt(process.env.PMX_CANVAS_PORT ?? '4313');
-    canvas = createCanvas({ port });
-    await canvas.start({ open: true });
+    canvas = await createCanvasAccess();
+  } else {
+    canvas = await refreshCanvasAccess(canvas);
   }
+  startResourceNotifications(canvas);
   return canvas;
 }
 
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+
+function sendCanvasResourceNotifications(type: 'nodes' | 'pins' = 'nodes'): void {
+  const server = resourceNotificationServer;
+  if (!server) return;
+  try {
+    if (type === 'pins') {
+      server.server.sendResourceUpdated({ uri: 'canvas://pinned-context' });
+    }
+    server.server.sendResourceUpdated({ uri: 'canvas://layout' });
+    server.server.sendResourceUpdated({ uri: 'canvas://summary' });
+    server.server.sendResourceUpdated({ uri: 'canvas://spatial-context' });
+    server.server.sendResourceUpdated({ uri: 'canvas://history' });
+    server.server.sendResourceUpdated({ uri: 'canvas://code-graph' });
+  } catch (error) {
+    console.debug('[mcp] resource notification failed', error);
+  }
+}
+
+function handleRemoteSseFrame(frame: string): void {
+  const eventLine = frame.split('\n').find((line) => line.startsWith('event: '));
+  const event = eventLine?.slice('event: '.length).trim() ?? '';
+  if (!event || event === 'connected' || event === 'ping') return;
+  sendCanvasResourceNotifications(event === 'context-pins-changed' ? 'pins' : 'nodes');
+}
+
+async function watchRemoteCanvasEvents(baseUrl: string): Promise<void> {
+  const decoder = new TextDecoder();
+  while (true) {
+    try {
+      const response = await fetch(`${baseUrl}/api/workbench/events`);
+      if (!response.ok || !response.body) {
+        await sleep(1_000);
+        continue;
+      }
+
+      const reader = response.body.getReader();
+      let buffer = '';
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const frames = buffer.split('\n\n');
+        buffer = frames.pop() ?? '';
+        for (const frame of frames) handleRemoteSseFrame(frame);
+      }
+    } catch (error) {
+      console.debug('[mcp] remote canvas event stream failed', error);
+    }
+    await sleep(1_000);
+  }
+}
+
+function startResourceNotifications(c: CanvasAccess): void {
+  const server = resourceNotificationServer;
+  if (!server) return;
+
+  if (c.remoteBaseUrl) {
+    if (remoteResourceNotificationsBaseUrl !== c.remoteBaseUrl) {
+      remoteResourceNotificationsBaseUrl = c.remoteBaseUrl;
+      void watchRemoteCanvasEvents(c.remoteBaseUrl);
+    }
+    return;
+  }
+
+  if (localResourceNotificationsStarted) return;
+  localResourceNotificationsStarted = true;
+
+  canvasState.onChange((type) => {
+    sendCanvasResourceNotifications(type);
+  });
+}
+
 function encodeBase64(bytes: Uint8Array): string {
   return Buffer.from(bytes).toString('base64');
 }
 
-function createdNodePayload(c: PmxCanvas, id: string): Record<string, unknown> {
-  const node = c.getNode(id);
+async function createdNodePayload(c: CanvasAccess, id: string): Promise<Record<string, unknown>> {
+  const node = await c.getNode(id);
   if (!node) return { ok: true, id };
   const serialized = serializeCanvasNode(node);
   return { ok: true, node: serialized, ...serialized };
 }
 
+function buildSummaryFromLayout(layout: Awaited<ReturnType<CanvasAccess['getLayout']>>, pinnedIds: string[]): Record<string, unknown> {
+  const pinned = new Set(pinnedIds);
+  const nodesByType: Record<string, number> = {};
+  const pinnedTitles: string[] = [];
+  for (const node of layout.nodes) {
+    const serialized = serializeCanvasNode(node);
+    nodesByType[serialized.kind] = (nodesByType[serialized.kind] ?? 0) + 1;
+    if (pinned.has(node.id)) pinnedTitles.push(getCanvasNodeTitle(node) ?? node.id);
+  }
+  return {
+    totalNodes: layout.nodes.length,
+    totalEdges: layout.edges.length,
+    nodesByType,
+    pinnedCount: pinned.size,
+    pinnedTitles,
+    viewport: layout.viewport,
+  };
+}
+
+function buildSnapshotRestoreSummary(layout: Awaited<ReturnType<CanvasAccess['getLayout']>>): Record<string, unknown> {
+  const nodesByType: Record<string, number> = {};
+  for (const node of layout.nodes) {
+    nodesByType[node.type] = (nodesByType[node.type] ?? 0) + 1;
+  }
+  return {
+    nodeCount: layout.nodes.length,
+    edgeCount: layout.edges.length,
+    nodesByType,
+    viewport: layout.viewport,
+  };
+}
+
 export async function startMcpServer(): Promise<void> {
   const server = new McpServer({
     name: 'pmx-canvas',
     version: '0.1.0',
   });
+  resourceNotificationServer = server;
 
   // ── canvas_get_layout ──────────────────────────────────────────
   server.tool(
@@ -113,7 +218,7 @@ export async function startMcpServer(): Promise<void> {
     {},
     async () => {
       const c = await ensureCanvas();
-      const layout = serializeCanvasLayout(c.getLayout());
+      const layout = serializeCanvasLayout(await c.getLayout());
       return {
         content: [{ type: 'text', text: JSON.stringify(layout, null, 2) }],
       };
@@ -127,7 +232,7 @@ export async function startMcpServer(): Promise<void> {
     { id: z.string().describe('The node ID to retrieve') },
     async ({ id }) => {
       const c = await ensureCanvas();
-      const node = c.getNode(id);
+      const node = await c.getNode(id);
       if (!node) {
         return {
           content: [{ type: 'text', text: `Node "${id}" not found.` }],
@@ -184,9 +289,9 @@ export async function startMcpServer(): Promise<void> {
       const nodeInput = input.type === 'image' && input.path && !input.content
         ? { ...input, content: input.path }
         : input;
-      const id = c.addNode(nodeInput);
+      const id = await c.addNode(nodeInput);
       return {
-        content: [{ type: 'text', text: JSON.stringify(createdNodePayload(c, id), null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(await createdNodePayload(c, id), null, 2) }],
       };
     },
   );
@@ -378,7 +483,7 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas_build_web_artifact ───────────────────────────────
   server.tool(
     'canvas_build_web_artifact',
-    'Build a bundled single-file HTML web artifact from React/Tailwind source files using the bundled web-artifacts-builder skill scripts. MCP callers pass source content in appTsx (the CLI app-file flag reads a file before calling this path). Builds commonly take 45-60s on cold workspaces; use a long client timeout. Optionally opens the generated artifact as an embedded node on the canvas. Read canvas://skills/web-artifacts-builder for the full workflow, stack, and anti-slop design guidelines before calling.',
+    'Build a bundled single-file HTML web artifact from React/Tailwind source files using the bundled web-artifacts-builder skill scripts. MCP callers pass source content in appTsx (the CLI app-file flag reads a file before calling this path). Builds can exceed default 60s MCP client timeouts on cold workspaces; set a long client timeout or retry with the same projectPath/outputPath if the client times out. Optionally opens the generated artifact as an embedded node on the canvas. Read canvas://skills/web-artifacts-builder for the full workflow, stack, and anti-slop design guidelines before calling.',
     {
       title: z.string().describe('Artifact title used for default project and output paths'),
       appTsx: z.string().describe('Contents for src/App.tsx'),
@@ -429,6 +534,7 @@ export async function startMcpServer(): Promise<void> {
               bytes: result.fileSize,
               projectPath: result.projectPath,
               openedInCanvas: result.openedInCanvas,
+              completedAt: result.completedAt,
               // `id` only present when a canvas node was actually created.
               // See the matching block in src/server/server.ts handleCanvasBuildWebArtifact.
               ...(typeof result.nodeId === 'string' ? { id: result.nodeId } : {}),
@@ -468,7 +574,7 @@ export async function startMcpServer(): Promise<void> {
     async (input) => {
       const c = await ensureCanvas();
       try {
-        const result = c.addJsonRenderNode({
+        const result = await c.addJsonRenderNode({
           ...(typeof input.title === 'string' ? { title: input.title } : {}),
           spec: input.spec,
           ...(typeof input.x === 'number' ? { x: input.x } : {}),
@@ -481,7 +587,7 @@ export async function startMcpServer(): Promise<void> {
           content: [{
             type: 'text',
             text: JSON.stringify({
-              ...createdNodePayload(c, result.id),
+              ...await createdNodePayload(c, result.id),
               url: result.url,
               spec: result.spec,
             }, null, 2),
@@ -530,7 +636,7 @@ export async function startMcpServer(): Promise<void> {
     async (input) => {
       const c = await ensureCanvas();
       try {
-        const result = c.addGraphNode({
+        const result = await c.addGraphNode({
           graphType: input.graphType,
           data: input.data,
           ...(typeof input.title === 'string' ? { title: input.title } : {}),
@@ -561,7 +667,7 @@ export async function startMcpServer(): Promise<void> {
           content: [{
             type: 'text',
             text: JSON.stringify({
-              ...createdNodePayload(c, result.id),
+              ...await createdNodePayload(c, result.id),
               url: result.url,
               spec: result.spec,
             }, null, 2),
@@ -599,7 +705,7 @@ export async function startMcpServer(): Promise<void> {
     },
     async ({ id, title, content, x, y, width, height, spec, graphType, data, xKey, yKey, chartHeight, collapsed, arrangeLocked }) => {
       const c = await ensureCanvas();
-      const node = c.getNode(id);
+      const node = await c.getNode(id);
       if (!node) {
         return {
           content: [{ type: 'text', text: `Node "${id}" not found.` }],
@@ -627,10 +733,10 @@ export async function startMcpServer(): Promise<void> {
       if (arrangeLocked !== undefined) {
         patch.arrangeLocked = arrangeLocked;
       }
-      c.updateNode(id, patch);
-      const updated = c.getNode(id);
+      await c.updateNode(id, patch);
+      const updated = await c.getNode(id);
       return {
-        content: [{ type: 'text', text: JSON.stringify(updated ? createdNodePayload(c, id) : { ok: true, id }, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(updated ? await createdNodePayload(c, id) : { ok: true, id }, null, 2) }],
       };
     },
   );
@@ -642,7 +748,7 @@ export async function startMcpServer(): Promise<void> {
     { id: z.string().describe('Node ID to remove') },
     async ({ id }) => {
       const c = await ensureCanvas();
-      c.removeNode(id);
+      await c.removeNode(id);
       return {
         content: [{ type: 'text', text: JSON.stringify({ ok: true, removed: id }) }],
       };
@@ -678,8 +784,8 @@ export async function startMcpServer(): Promise<void> {
         };
       }
       try {
-        const id = c.addEdge(input);
-        const edge = c.getLayout().edges.find((entry) => entry.id === id);
+        const id = await c.addEdge(input);
+        const edge = (await c.getLayout()).edges.find((entry) => entry.id === id);
         return {
           content: [{
             type: 'text',
@@ -702,7 +808,7 @@ export async function startMcpServer(): Promise<void> {
     { id: z.string().describe('Edge ID to remove') },
     async ({ id }) => {
       const c = await ensureCanvas();
-      c.removeEdge(id);
+      await c.removeEdge(id);
       return {
         content: [{ type: 'text', text: JSON.stringify({ ok: true, removed: id }) }],
       };
@@ -718,7 +824,7 @@ export async function startMcpServer(): Promise<void> {
     },
     async ({ layout }) => {
       const c = await ensureCanvas();
-      c.arrange(layout ?? 'grid');
+      await c.arrange(layout ?? 'grid');
       return {
         content: [{ type: 'text', text: JSON.stringify({ ok: true, layout: layout ?? 'grid' }) }],
       };
@@ -738,7 +844,7 @@ export async function startMcpServer(): Promise<void> {
     },
     async ({ id, noPan }) => {
       const c = await ensureCanvas();
-      const result = c.focusNode(id, { ...(noPan === true ? { noPan: true } : {}) });
+      const result = await c.focusNode(id, { ...(noPan === true ? { noPan: true } : {}) });
       if (!result) {
         return {
           content: [
@@ -772,7 +878,7 @@ export async function startMcpServer(): Promise<void> {
     },
     async (input) => {
       const c = await ensureCanvas();
-      const result = c.fitView({
+      const result = await c.fitView({
         ...(typeof input.width === 'number' ? { width: input.width } : {}),
         ...(typeof input.height === 'number' ? { height: input.height } : {}),
         ...(typeof input.padding === 'number' ? { padding: input.padding } : {}),
@@ -792,7 +898,7 @@ export async function startMcpServer(): Promise<void> {
     {},
     async () => {
       const c = await ensureCanvas();
-      c.clear();
+      await c.clear();
       return {
         content: [{ type: 'text', text: JSON.stringify({ ok: true, cleared: true }) }],
       };
@@ -808,8 +914,8 @@ export async function startMcpServer(): Promise<void> {
       limit: z.number().optional().describe('Max results to return (default: 10)'),
     },
     async ({ query, limit }) => {
-      await ensureCanvas();
-      const results = searchNodes(canvasState.getLayout().nodes, query);
+      const c = await ensureCanvas();
+      const results = await c.search(query);
       const capped = results.slice(0, limit ?? 10);
       return {
         content: [{
@@ -828,8 +934,9 @@ export async function startMcpServer(): Promise<void> {
     async () => {
       const c = await ensureCanvas();
       const result = await c.undo();
+      const history = await c.getHistory();
       return {
-        content: [{ type: 'text', text: JSON.stringify({ ...result, canUndo: mutationHistory.canUndo(), canRedo: mutationHistory.canRedo() }) }],
+        content: [{ type: 'text', text: JSON.stringify({ ...result, canUndo: history.canUndo, canRedo: history.canRedo }) }],
       };
     },
   );
@@ -842,8 +949,9 @@ export async function startMcpServer(): Promise<void> {
     async () => {
       const c = await ensureCanvas();
       const result = await c.redo();
+      const history = await c.getHistory();
       return {
-        content: [{ type: 'text', text: JSON.stringify({ ...result, canUndo: mutationHistory.canUndo(), canRedo: mutationHistory.canRedo() }) }],
+        content: [{ type: 'text', text: JSON.stringify({ ...result, canUndo: history.canUndo, canRedo: history.canRedo }) }],
       };
     },
   );
@@ -856,15 +964,13 @@ export async function startMcpServer(): Promise<void> {
       snapshot: z.string().describe('Snapshot name or ID to compare against'),
     },
     async ({ snapshot }) => {
-      await ensureCanvas();
-      const snapData = canvasState.getSnapshotData(snapshot);
-      if (!snapData) {
+      const c = await ensureCanvas();
+      const result = await c.diffSnapshot(snapshot);
+      if (!result.ok) {
         return { content: [{ type: 'text', text: `Snapshot "${snapshot}" not found. Use canvas_snapshot to save one first.` }], isError: true };
       }
-      const current = canvasState.getLayout();
-      const diff = diffLayouts(snapData.name, snapData, current);
       return {
-        content: [{ type: 'text', text: formatDiff(diff) }],
+        content: [{ type: 'text', text: result.text ?? '' }],
       };
     },
   );
@@ -877,7 +983,7 @@ export async function startMcpServer(): Promise<void> {
     async () => {
       const c = await ensureCanvas();
       return {
-        content: [{ type: 'text', text: JSON.stringify(c.getAutomationWebViewStatus(), null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(await c.getAutomationWebViewStatus(), null, 2) }],
       };
     },
   );
@@ -927,13 +1033,14 @@ export async function startMcpServer(): Promise<void> {
       const c = await ensureCanvas();
       try {
         const stopped = await c.stopAutomationWebView();
+        const webview = await c.getAutomationWebViewStatus();
         return {
           content: [{
             type: 'text',
             text: JSON.stringify({
               ok: true,
               stopped,
-              webview: c.getAutomationWebViewStatus(),
+              webview,
             }, null, 2),
           }],
         };
@@ -1017,7 +1124,7 @@ export async function startMcpServer(): Promise<void> {
           ...(format ? { format } : {}),
           ...(typeof quality === 'number' ? { quality } : {}),
         });
-        const status = c.getAutomationWebViewStatus();
+        const status = await c.getAutomationWebViewStatus();
         return {
           content: [
             {
@@ -1092,8 +1199,8 @@ export async function startMcpServer(): Promise<void> {
     },
     async () => {
       const c = await ensureCanvas();
-      const pinnedIds = canvasState.contextPinnedNodeIds;
-      const layout = c.getLayout();
+      const pinnedIds = new Set(await c.getPinnedNodeIds());
+      const layout = await c.getLayout();
 
       const pinnedNodes = layout.nodes.filter((n) => pinnedIds.has(n.id));
       const pinnedEdges = layout.edges.filter(
@@ -1147,7 +1254,7 @@ export async function startMcpServer(): Promise<void> {
     },
     async () => {
       const c = await ensureCanvas();
-      const layout = serializeCanvasLayout(c.getLayout());
+      const layout = serializeCanvasLayout(await c.getLayout());
       return {
         contents: [
           {
@@ -1170,13 +1277,13 @@ export async function startMcpServer(): Promise<void> {
       mimeType: 'application/json',
     },
     async () => {
-      await ensureCanvas();
+      const c = await ensureCanvas();
       return {
         contents: [
           {
             uri: 'canvas://summary',
             mimeType: 'application/json',
-            text: JSON.stringify(buildCanvasSummary(), null, 2),
+            text: JSON.stringify(buildSummaryFromLayout(await c.getLayout(), await c.getPinnedNodeIds()), null, 2),
           },
         ],
       };
@@ -1196,9 +1303,9 @@ export async function startMcpServer(): Promise<void> {
       mimeType: 'application/json',
     },
     async () => {
-      await ensureCanvas();
-      const layout = canvasState.getLayout();
-      const spatial = buildSpatialContext(layout.nodes, layout.edges, canvasState.contextPinnedNodeIds);
+      const c = await ensureCanvas();
+      const layout = await c.getLayout();
+      const spatial = buildSpatialContext(layout.nodes, layout.edges, new Set(await c.getPinnedNodeIds()));
       return {
         contents: [
           {
@@ -1222,13 +1329,13 @@ export async function startMcpServer(): Promise<void> {
       mimeType: 'text/plain',
     },
     async () => {
-      await ensureCanvas();
+      const c = await ensureCanvas();
       return {
         contents: [
           {
             uri: 'canvas://history',
             mimeType: 'text/plain',
-            text: mutationHistory.toHumanReadable(),
+            text: (await c.getHistory()).text,
           },
         ],
       };
@@ -1247,8 +1354,8 @@ export async function startMcpServer(): Promise<void> {
       mimeType: 'application/json',
     },
     async () => {
-      await ensureCanvas();
-      const summary = buildCodeGraphSummary();
+      const c = await ensureCanvas();
+      const summary = (await c.getCodeGraph()).summary;
       return {
         contents: [
           {
@@ -1339,9 +1446,9 @@ export async function startMcpServer(): Promise<void> {
     },
     async (input) => {
       const c = await ensureCanvas();
-      const id = c.createGroup(input);
+      const id = await c.createGroup(input);
       return {
-        content: [{ type: 'text', text: JSON.stringify(createdNodePayload(c, id), null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(await createdNodePayload(c, id), null, 2) }],
       };
     },
   );
@@ -1357,7 +1464,7 @@ export async function startMcpServer(): Promise<void> {
     },
     async ({ groupId, childIds, childLayout }) => {
       const c = await ensureCanvas();
-      const ok = c.groupNodes(groupId, childIds, childLayout ? { childLayout } : undefined);
+      const ok = await c.groupNodes(groupId, childIds, childLayout ? { childLayout } : undefined);
       if (!ok) {
         return { content: [{ type: 'text', text: 'Group not found or no valid children.' }], isError: true };
       }
@@ -1367,7 +1474,7 @@ export async function startMcpServer(): Promise<void> {
 
   server.tool(
     'canvas_batch',
-    'Run a batch of canvas operations with optional assigned references. Supports node.add, node.update, graph.add, edge.add, group.create, group.add, group.remove, pin.set/add/remove, snapshot.save, and arrange.',
+    'Run a non-atomic batch of canvas operations with optional assigned references. Use assign to name a result, then reference it later as "$name" for the created node id or "$name.id" for a specific result field. On failure, earlier successful operations remain applied and the response includes ok:false, failedIndex, error, results, and refs. Supports node.add, node.update, graph.add, edge.add, group.create, group.add, group.remove, pin.set/add/remove, snapshot.save, and arrange.',
     {
       operations: z.array(z.object({
         op: z.string().describe('Operation name, e.g. "node.add" or "edge.add"'),
@@ -1392,7 +1499,7 @@ export async function startMcpServer(): Promise<void> {
     async () => {
       const c = await ensureCanvas();
       return {
-        content: [{ type: 'text', text: JSON.stringify(c.validate(), null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(await c.validate(), null, 2) }],
       };
     },
   );
@@ -1406,7 +1513,7 @@ export async function startMcpServer(): Promise<void> {
     },
     async ({ groupId }) => {
       const c = await ensureCanvas();
-      const ok = c.ungroupNodes(groupId);
+      const ok = await c.ungroupNodes(groupId);
       if (!ok) {
         return { content: [{ type: 'text', text: 'Group not found or already empty.' }], isError: true };
       }
@@ -1425,9 +1532,7 @@ export async function startMcpServer(): Promise<void> {
     },
     async ({ nodeIds, mode }) => {
       const c = await ensureCanvas();
-      const result = c.setContextPins(nodeIds, mode ?? 'set');
-
-      emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+      const result = await c.setContextPins(nodeIds, mode ?? 'set');
 
       return {
         content: [{
@@ -1450,7 +1555,7 @@ export async function startMcpServer(): Promise<void> {
     },
     async (input) => {
       const c = await ensureCanvas();
-      const snapshot = c.saveSnapshot(input.name);
+      const snapshot = await c.saveSnapshot(input.name);
       if (!snapshot) {
         return { content: [{ type: 'text', text: JSON.stringify({ ok: false, error: 'Failed to save snapshot' }) }] };
       }
@@ -1466,7 +1571,7 @@ export async function startMcpServer(): Promise<void> {
     async () => {
       const c = await ensureCanvas();
       return {
-        content: [{ type: 'text', text: JSON.stringify({ snapshots: c.listSnapshots() }, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify({ snapshots: await c.listSnapshots() }, null, 2) }],
       };
     },
   );
@@ -1484,9 +1589,9 @@ export async function startMcpServer(): Promise<void> {
       if (!result.ok) {
         return { content: [{ type: 'text', text: JSON.stringify({ ok: false, error: 'Snapshot not found' }) }] };
       }
-      emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+      const layout = await c.getLayout();
       return {
-        content: [{ type: 'text', text: JSON.stringify({ ok: true, layout: serializeCanvasLayout(canvasState.getLayout()) }) }],
+        content: [{ type: 'text', text: JSON.stringify({ ok: true, restored: input.id, summary: buildSnapshotRestoreSummary(layout) }, null, 2) }],
       };
     },
   );
@@ -1500,7 +1605,7 @@ export async function startMcpServer(): Promise<void> {
     },
     async ({ id }) => {
       const c = await ensureCanvas();
-      const result = c.deleteSnapshot(id);
+      const result = await c.deleteSnapshot(id);
       if (!result.ok) {
         return { content: [{ type: 'text', text: JSON.stringify({ ok: false, error: 'Snapshot not found' }) }], isError: true };
       }
@@ -1510,24 +1615,6 @@ export async function startMcpServer(): Promise<void> {
     },
   );
 
-  // ── Resource change notifications ──────────────────────────
-  // When canvas state changes (nodes, edges, pins), notify MCP clients
-  // so they can re-read resources like canvas://pinned-context.
-  canvasState.onChange((type) => {
-    try {
-      if (type === 'pins') {
-        server.server.sendResourceUpdated({ uri: 'canvas://pinned-context' });
-      }
-      server.server.sendResourceUpdated({ uri: 'canvas://layout' });
-      server.server.sendResourceUpdated({ uri: 'canvas://summary' });
-      server.server.sendResourceUpdated({ uri: 'canvas://spatial-context' });
-      server.server.sendResourceUpdated({ uri: 'canvas://history' });
-      server.server.sendResourceUpdated({ uri: 'canvas://code-graph' });
-    } catch (error) {
-      console.debug('[mcp] resource notification failed', error);
-    }
-  });
-
   // Connect via stdio
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/src/server/canvas-operations.ts

@@ -1373,6 +1373,7 @@ function resolveBatchRefs(value: unknown, refs: Record<string, unknown>): unknow
   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];

package/src/server/canvas-schema.ts

@@ -140,11 +140,18 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional title.' },
       { name: 'content', type: 'string', required: false, description: 'Trace summary.' },
+      { name: 'toolName', type: 'string', required: false, description: 'Tool or operation label shown in the trace pill; defaults to title.' },
+      { name: 'category', type: 'string', required: false, description: 'Trace category color key: mcp, file, subagent, or other.' },
+      { name: 'status', type: 'string', required: false, description: 'Trace status: running, success, or failed.' },
+      { name: 'duration', type: 'string', required: false, description: 'Optional duration badge text.' },
+      { name: 'resultSummary', type: 'string', required: false, description: 'Short trace result summary; defaults to content.' },
+      { name: 'error', type: 'string', required: false, description: 'Short error message shown in failed traces.' },
     ],
     example: {
       type: 'trace',
       title: 'Execution Trace',
       content: 'Canvas actions and tool events.',
+      status: 'success',
     },
   },
   {
@@ -378,12 +385,16 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       { name: 'openInCanvas', type: 'boolean', required: false, description: 'Open the built artifact on the canvas (default true).' },
       { name: 'includeLogs', type: 'boolean', required: false, description: 'Include raw build stdout/stderr in the response (default false).' },
       { name: 'deps', type: 'string[]', required: false, description: 'Optional npm dependencies to add before bundling, e.g. recharts.', aliases: ['deps'] },
+      { name: 'timeoutMs', type: 'number', required: false, description: 'Build command timeout in milliseconds. This controls subprocess timeout, not the MCP client request timeout.' },
     ],
     example: {
       title: 'Dashboard Artifact',
       appTsx: 'export default function App() { return <main>Artifact</main>; }',
       indexCss: 'body { background: #123456; color: white; }',
     },
+    notes: [
+      'Cold builds can exceed default 60s MCP client timeouts; configure a longer MCP call timeout or retry with the same projectPath/outputPath if the first call times out.',
+    ],
   },
 ];