pmx-canvas 0.2.6 → 0.3.0

package/src/mcp/server.ts

@@ -20,14 +20,15 @@
  * ```
  */
 
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { canvasState, describeCanvasSchema } from '../server/index.js';
 import { AX_INTERACTION_TYPES } from '../server/ax-interaction.js';
 import { buildPendingAxActivity } from '../server/ax-state.js';
-import { isHtmlPrimitiveKind } from '../server/html-primitives.js';
-import type { HtmlPrimitiveKind } from '../server/html-primitives.js';
 import { registerOperationTools, registerCompositeTools } from '../server/operations/index.js';
 import { createCanvasAccess, refreshCanvasAccess, type CanvasAccess } from './canvas-access.js';
 import { serializeNodeForAgentContext } from '../server/agent-context.js';
@@ -36,7 +37,6 @@ import {
   getCanvasNodeTitle,
   serializeCanvasLayoutForAgent,
   serializeCanvasNode,
-  serializeCanvasNodeForAgent,
   summarizeCanvasAnnotationForContext,
 } from '../server/canvas-serialization.js';
 import { listBundledSkills, readBundledSkill } from '../server/bundled-skills.js';
@@ -46,7 +46,18 @@ let resourceNotificationServer: McpServer | null = null;
 let localResourceNotificationsStarted = false;
 let remoteResourceNotificationsBaseUrl: string | null = null;
 
-const htmlPrimitiveKindSchema = z.string().refine(isHtmlPrimitiveKind, 'Unknown HTML primitive kind');
+// Resolved from the sibling package.json so it stays accurate through bunx,
+// global npm installs, and repo-local runs (no hard-coded string, no build
+// step required) — same mechanism as --version in src/cli/index.ts.
+function readPackageVersion(): string {
+  try {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version?: string };
+    return pkg.version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
 
 function structuredSchemaDescription(): string {
   const routing = describeCanvasSchema().mcp.nodeTypeRouting;
@@ -55,10 +66,6 @@ function structuredSchemaDescription(): string {
     .join(', ');
 }
 
-// workspaceRoot / isPathInside / safeWorkspacePath removed with the
-// canvas_build_web_artifact MCP tool (plan-008 Wave 4). The webartifact.build op
-// sandboxes projectPath/outputPath via web-artifacts.ts resolveWorkspacePath.
-
 async function ensureCanvas(): Promise<CanvasAccess> {
   if (!canvas) {
     canvas = await createCanvasAccess();
@@ -215,19 +222,6 @@ function agentSafeFullLayoutPayload(layout: Awaited<ReturnType<CanvasAccess['get
   };
 }
 
-async function createdNodePayload(c: CanvasAccess, id: string, options: { full?: boolean; verbose?: boolean; includeData?: boolean } = {}): Promise<Record<string, unknown>> {
-  // Expose both `id` and a `nodeId` alias on every node-create response so
-  // agents using either key (or a cached schema) work — matching the
-  // external-app / web-artifact responses that already return both.
-  const node = await c.getNode(id);
-  if (!node) return { ok: true, id, nodeId: id };
-  if (!wantsFullPayload(options)) {
-    return { ok: true, node: compactNodePayload(node), id, nodeId: id };
-  }
-  const serialized = serializeCanvasNodeForAgent(node);
-  return { ok: true, node: serialized, ...serialized, nodeId: node.id };
-}
-
 function buildSummaryFromLayout(layout: Awaited<ReturnType<CanvasAccess['getLayout']>>, pinnedIds: string[]): Record<string, unknown> {
   const pinned = new Set(pinnedIds);
   const nodesByType: Record<string, number> = {};
@@ -252,15 +246,19 @@ function buildSummaryFromLayout(layout: Awaited<ReturnType<CanvasAccess['getLayo
 export async function startMcpServer(): Promise<void> {
   const server = new McpServer({
     name: 'pmx-canvas',
-    version: '0.1.0',
+    version: readPackageVersion(),
   });
   resourceNotificationServer = server;
 
   // ── Operation-registry tools (plan-005) ────────────────────────
-  // canvas_get_layout / canvas_get_node / canvas_add_node /
-  // canvas_update_node / canvas_remove_node are registered from the shared
-  // operation registry. Tool names and compact/full payload behavior are
-  // frozen (tests/unit/mcp-tool-freeze.test.ts, operation-parity.test.ts).
+  // Standalone tools are registered from the shared operation registry for
+  // every op not folded into a composite (registerOperationTools skips
+  // composite-folded ops — see compositeFoldedOpNames in composites.ts).
+  // canvas_get_layout / canvas_get_node / canvas_add_node / canvas_update_node /
+  // canvas_remove_node were folded into canvas_query / canvas_node and removed
+  // as standalone tools in v0.3.0; they remain reachable via their composite
+  // and canvas_batch. Remaining standalone tool names and compact/full payload
+  // behavior are frozen (tests/unit/mcp-tool-freeze.test.ts, operation-parity.test.ts).
   registerOperationTools(server, ensureCanvas);
 
   // ── Composite (action-discriminated) tools (plan-006) ───────────
@@ -268,151 +266,12 @@ export async function startMcpServer(): Promise<void> {
   // (canvas_node, canvas_render, canvas_edge, canvas_group, canvas_history,
   // canvas_view, canvas_query, plus the AX composites). Each action dispatches
   // to the same registered operation as its standalone tool, so behavior is
-  // identical. Additive in v0.2 (legacy tools still registered below); legacy
-  // removed in v0.3 per docs/api-stability.md. (canvas_snapshot composite is
-  // deferred to v0.3 — its name is still held by the legacy save-snapshot tool.)
+  // identical. The legacy single-purpose tools these composites replace are
+  // removed as of v0.3.0 per docs/api-stability.md. (canvas_snapshot composite
+  // is deferred to v0.4 — its name is still held by the legacy save-snapshot
+  // tool; the 6 snapshot standalones are deprecated in v0.3.0 and fold into it.)
   registerCompositeTools(server, ensureCanvas);
 
-  // ── canvas_add_html_node ────────────────────────────────────────
-  server.tool(
-    'canvas_add_html_node',
-    'Deprecated: use canvas_node with action "add" and type:"html". Add a normal html node: a self-contained HTML document (with optional inline <script> and CDN <script src="...">) rendered inside a sandboxed iframe (sandbox="allow-scripts"). This is the default HTML surface for reports, widgets, and bespoke visualizations. Presentation mode is opt-in: only pass presentation:true when the user explicitly asks for a deck/fullscreen presentation, or use canvas_add_html_primitive with kind="presentation". The iframe inherits live canvas theme tokens via injected CSS custom properties (both --c-* and common --color-* aliases) so authored HTML using var(--color-text-secondary), var(--color-bg), etc. renders cohesively. No same-origin access; no top-navigation; no forms. For declarative-only views with zero JS, prefer canvas_add_json_render_node. For React + shadcn + routing or multi-component apps, use canvas_build_web_artifact.',
-    {
-      html: z.string().describe('HTML document or fragment. Full <html>...</html> documents are passed through with theme styles injected into <head>; bare fragments are wrapped in a minimal document. Inline <script> and remote CDN <script src="..."> are allowed. If this is a bare path to an existing local .html/.htm file, the file contents are read and used as the HTML.'),
-      title: z.string().optional().describe('Node title shown in the canvas titlebar.'),
-      summary: z.string().optional().describe('Agent-readable semantic summary for this HTML node. If omitted, PMX derives one from visible HTML text.'),
-      agentSummary: z.string().optional().describe('Explicit agent-readable summary. Alias for summary with higher priority when both are provided.'),
-      description: z.string().optional().describe('Short description included in search and pinned/spatial context.'),
-      presentation: z.boolean().optional().describe('Marks this HTML surface as a fullscreen presentation/deck. Omit unless the user explicitly requested presentation mode.'),
-      slideTitles: z.array(z.string()).optional().describe('Agent-readable slide titles for presentation HTML.'),
-      embeddedNodeIds: z.array(z.string()).optional().describe('Canvas node IDs embedded or represented by this HTML surface.'),
-      embeddedUrls: z.array(z.string()).optional().describe('URLs embedded or represented by this HTML surface.'),
-      x: z.number().optional().describe('X position (auto-placed if omitted).'),
-      y: z.number().optional().describe('Y position (auto-placed if omitted).'),
-      width: z.number().optional().describe('Width in pixels (default: 720).'),
-      height: z.number().optional().describe('Height in pixels (default: 640).'),
-      strictSize: z.boolean().optional().describe('Keep explicit width/height fixed; iframe scrolls overflow internally.'),
-      axCapabilities: z.object({
-        enabled: z.boolean().optional(),
-        allowed: z.array(z.string()).optional().describe('AX interaction types this node may emit (e.g. ax.work.create, ax.work.update, ax.steer, ax.focus.set, ax.evidence.add, ax.event.record). Clamped to the html capability ceiling server-side; cannot escalate.'),
-      }).optional().describe('Opt this html node into AX interactions so its sandboxed UI can emit ax.* via window.PMX_AX.emit(type, payload) (and reflect live AX state). html nodes are AX-disabled by default; set { enabled: true, allowed: [...] } to turn the bridge on. Build interactive boards (work queues, review boards, inboxes) this way.'),
-      full: z.boolean().optional().describe('Return the full created node payload. Default false returns compact metadata.'),
-      verbose: z.boolean().optional().describe('Alias for full:true.'),
-    },
-    async (input) => {
-      const c = await ensureCanvas();
-      const id = await c.addHtmlNode({
-        html: input.html,
-        ...(typeof input.title === 'string' ? { title: input.title } : {}),
-        ...(input.axCapabilities ? { axCapabilities: input.axCapabilities } : {}),
-        ...(typeof input.summary === 'string' ? { summary: input.summary } : {}),
-        ...(typeof input.agentSummary === 'string' ? { agentSummary: input.agentSummary } : {}),
-        ...(typeof input.description === 'string' ? { description: input.description } : {}),
-        ...(input.presentation === true ? { presentation: true } : {}),
-        ...(Array.isArray(input.slideTitles) ? { slideTitles: input.slideTitles } : {}),
-        ...(Array.isArray(input.embeddedNodeIds) ? { embeddedNodeIds: input.embeddedNodeIds } : {}),
-        ...(Array.isArray(input.embeddedUrls) ? { embeddedUrls: input.embeddedUrls } : {}),
-        ...(typeof input.x === 'number' ? { x: input.x } : {}),
-        ...(typeof input.y === 'number' ? { y: input.y } : {}),
-        ...(typeof input.width === 'number' ? { width: input.width } : {}),
-        ...(typeof input.height === 'number' ? { height: input.height } : {}),
-        ...(input.strictSize === true ? { strictSize: true } : {}),
-      });
-      return {
-        content: [{ type: 'text', text: JSON.stringify(await createdNodePayload(c, id, input), null, 2) }],
-      };
-    },
-  );
-
-  server.tool(
-    'canvas_add_html_primitive',
-    'Deprecated: use canvas_node with action "add", type:"html", primitive:"<kind>" (and data). Create a reusable HTML communication primitive as a normal sandboxed html node. Use this instead of long markdown for side-by-side choices, implementation plans, PR review sheets, module maps, design sheets, component galleries, flowcharts, explainers, status reports, and throwaway editors with export/copy paths. Use kind="presentation" only when the user explicitly asks for a PowerPoint-like deck, pitch, briefing, workshop walkthrough, or fullscreen story.',
-    {
-      kind: htmlPrimitiveKindSchema.describe('Primitive kind. Call canvas_describe_schema and read htmlPrimitives for data shapes and examples.'),
-      title: z.string().optional().describe('Node title shown in the canvas titlebar.'),
-      data: z.record(z.string(), z.unknown()).optional().describe('Primitive-specific data payload. For kind="presentation", data may include theme:"canvas"|"midnight"|"paper"|"aurora" or a custom color object. See canvas_describe_schema.htmlPrimitives for each shape.'),
-      x: z.number().optional().describe('X position (auto-placed if omitted).'),
-      y: z.number().optional().describe('Y position (auto-placed if omitted).'),
-      width: z.number().optional().describe('Width in pixels (defaults per primitive).'),
-      height: z.number().optional().describe('Height in pixels (defaults per primitive).'),
-      strictSize: z.boolean().optional().describe('Keep explicit width/height fixed; iframe scrolls overflow internally.'),
-      full: z.boolean().optional().describe('Return the full created node payload. Default false returns compact metadata.'),
-      verbose: z.boolean().optional().describe('Alias for full:true.'),
-    },
-    async (input) => {
-      const c = await ensureCanvas();
-      const kind = input.kind as HtmlPrimitiveKind;
-      const result = await c.addHtmlPrimitive({
-        kind,
-        ...(typeof input.title === 'string' ? { title: input.title } : {}),
-        ...(input.data ? { data: input.data } : {}),
-        ...(typeof input.x === 'number' ? { x: input.x } : {}),
-        ...(typeof input.y === 'number' ? { y: input.y } : {}),
-        ...(typeof input.width === 'number' ? { width: input.width } : {}),
-        ...(typeof input.height === 'number' ? { height: input.height } : {}),
-        ...(input.strictSize === true ? { strictSize: true } : {}),
-      });
-      return {
-        content: [{
-          type: 'text',
-          text: JSON.stringify({
-            ...(await createdNodePayload(c, result.id, input)),
-            primitive: { kind: result.kind, title: result.title, htmlBytes: result.htmlBytes },
-          }, null, 2),
-        }],
-      };
-    },
-  );
-
-  // canvas_open_mcp_app + canvas_add_diagram migrated to the operation registry
-  // (plan-008 Wave 4): src/server/operations/ops/app.ts (mcpapp.open /
-  // diagram.open). Folded into the canvas_app composite.
-
-  server.tool(
-    'canvas_refresh_webpage_node',
-    'Deprecated: use canvas_node with action "update" and refresh:true. Refresh a webpage node from its persisted URL so the server re-fetches and caches the latest page text and metadata.',
-    {
-      id: z.string().describe('Webpage node ID to refresh'),
-      url: z.string().optional().describe('Optional replacement URL before refresh'),
-    },
-    async ({ id, url }) => {
-      const c = await ensureCanvas();
-      const result = await c.refreshWebpageNode(id, url);
-      return {
-        content: [{ type: 'text', text: JSON.stringify(result) }],
-        ...(result.ok ? {} : { isError: true }),
-      };
-    },
-  );
-
-  // canvas_build_web_artifact migrated to the operation registry (plan-008
-  // Wave 4): src/server/operations/ops/app.ts (webartifact.build). Folded into
-  // the canvas_app composite.
-
-  // canvas_remove_annotation migrated to the operation registry (plan-008
-  // Wave 1): src/server/operations/ops/annotation.ts.
-
-  // ── AX context and focus ───────────────────────────────────────
-  // canvas_get_ax + canvas_set_ax_focus migrated to the operation registry
-  // (plan-007 Slice B.1): src/server/operations/ops/ax-state.ts.
-
-  // canvas_record_ax_event / canvas_send_steering / canvas_get_ax_timeline
-  // migrated to the operation registry (plan-007 Slice B wave 3):
-  // src/server/operations/ops/ax-timeline.ts.
-
-  // canvas_add_work_item / canvas_update_work_item / canvas_request_approval /
-  // canvas_resolve_approval migrated to the operation registry (plan-007 Slice B
-  // wave 2): src/server/operations/ops/ax-work.ts.
-
-  // canvas_add_evidence migrated to the operation registry (plan-007 Slice B
-  // wave 3): src/server/operations/ops/ax-timeline.ts.
-
-  // canvas_add_review_annotation migrated to the operation registry (plan-007
-  // Slice B wave 2): src/server/operations/ops/ax-work.ts.
-
-  // canvas_report_host_capability migrated to the operation registry
-  // (plan-007 Slice B.1): src/server/operations/ops/ax-state.ts.
-
   server.tool(
     'canvas_ax_interaction',
     'Submit a node-originated AX interaction: a capability-gated, validated event from an eligible node that maps onto an AX operation (work item, evidence, approval, review, focus, steering, event). Returns { ok: false, code } if the node type/metadata does not allow the interaction type or the payload is invalid.',
@@ -427,18 +286,25 @@ export async function startMcpServer(): Promise<void> {
         .describe('Optional host/source label. Defaults to mcp.'),
     },
     async ({ type, sourceNodeId, payload, sourceSurface, correlationId, source }) => {
-      const c = await ensureCanvas();
-      const result = await c.submitAxInteraction(
-        {
-          type,
-          sourceNodeId,
-          ...(payload ? { payload } : {}),
-          ...(sourceSurface ? { sourceSurface } : {}),
-          ...(correlationId ? { correlationId } : {}),
-        },
-        { source: source ?? 'mcp' },
-      );
-      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      try {
+        const c = await ensureCanvas();
+        const result = await c.submitAxInteraction(
+          {
+            type,
+            sourceNodeId,
+            ...(payload ? { payload } : {}),
+            ...(sourceSurface ? { sourceSurface } : {}),
+            ...(correlationId ? { correlationId } : {}),
+          },
+          { source: source ?? 'mcp' },
+        );
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      } catch (error) {
+        return {
+          content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+          isError: true,
+        };
+      }
     },
   );
 
@@ -479,21 +345,28 @@ export async function startMcpServer(): Promise<void> {
       source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system']).optional(),
     },
     async ({ kind, title, summary, outcome, ref, nodeIds, data, reactions, source }) => {
-      const c = await ensureCanvas();
-      const result = await c.ingestActivity(
-        {
-          kind,
-          title,
-          ...(summary !== undefined ? { summary } : {}),
-          ...(outcome !== undefined ? { outcome } : {}),
-          ...(ref !== undefined ? { ref } : {}),
-          ...(nodeIds !== undefined ? { nodeIds } : {}),
-          ...(data !== undefined ? { data } : {}),
-          ...(reactions !== undefined ? { reactions } : {}),
-        },
-        { source: source ?? 'mcp' },
-      );
-      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, ...result }) }] };
+      try {
+        const c = await ensureCanvas();
+        const result = await c.ingestActivity(
+          {
+            kind,
+            title,
+            ...(summary !== undefined ? { summary } : {}),
+            ...(outcome !== undefined ? { outcome } : {}),
+            ...(ref !== undefined ? { ref } : {}),
+            ...(nodeIds !== undefined ? { nodeIds } : {}),
+            ...(data !== undefined ? { data } : {}),
+            ...(reactions !== undefined ? { reactions } : {}),
+          },
+          { source: source ?? 'mcp' },
+        );
+        return { content: [{ type: 'text', text: JSON.stringify({ ok: true, ...result }) }] };
+      } catch (error) {
+        return {
+          content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+          isError: true,
+        };
+      }
     },
   );
 
@@ -516,7 +389,7 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas_screenshot ─────────────────────────────────────────
   server.tool(
     'canvas_screenshot',
-    'Capture a screenshot from the active Bun.WebView automation session. Returns both an MCP image payload and JSON metadata. Requires an active automation session started via canvas_webview_start.',
+    'Capture a screenshot from the active Bun.WebView automation session. Returns both an MCP image payload and JSON metadata. Requires an active automation session started via canvas_webview with action "start".',
     {
       format: z.enum(['png', 'jpeg', 'webp']).optional().describe('Screenshot format (default depends on Bun; png recommended)'),
       quality: z.number().optional().describe('Optional quality for lossy formats'),
@@ -752,7 +625,7 @@ export async function startMcpServer(): Promise<void> {
     'canvas://ax-pending-steering',
     {
       description:
-        'Adapterless AX delivery surface. `pending`: undelivered steering messages to claim and act on, then mark via canvas_mark_ax_delivery. `pendingActivity`: open canvas-bound AX items awaiting the agent (open work items, pending approval gates / elicitations / mode requests) — usually created by the human in the browser; these fire ax-state-changed (resource-subscribers are also pushed canvas://ax-work). Resolve pendingActivity via its own tool, not canvas_mark_ax_delivery. Use canvas_claim_ax_delivery for the loop-safe, consumer-scoped view.',
+        'Adapterless AX delivery surface. `pending`: undelivered steering messages to claim and act on, then mark via canvas_ax_delivery { action: "mark" }. `pendingActivity`: open canvas-bound AX items awaiting the agent (open work items, pending approval gates / elicitations / mode requests) — usually created by the human in the browser; these fire ax-state-changed (resource-subscribers are also pushed canvas://ax-work). Resolve pendingActivity via its own tool, not the delivery mark action. Use canvas_ax_delivery { action: "claim" } for the loop-safe, consumer-scoped view.',
       mimeType: 'application/json',
     },
     async () => {
@@ -931,8 +804,8 @@ export async function startMcpServer(): Promise<void> {
   // ── canvas://skills ────────────────────────────────────────
   // Discoverability for the skill prompts bundled with the npm package
   // (skills/<name>/SKILL.md). Before 0.1.2 these files shipped but were
-  // invisible to agents — calling canvas_build_web_artifact without the
-  // companion `web-artifacts-builder` skill led to predictable misuse.
+  // invisible to agents — building web artifacts without the companion
+  // `web-artifacts-builder` skill led to predictable misuse.
   // The index lists every bundled skill with its frontmatter description;
   // individual skills are served verbatim at canvas://skills/<name>.
   server.resource(
@@ -943,7 +816,7 @@ export async function startMcpServer(): Promise<void> {
         'Index of agent skills bundled with this PMX Canvas install. Lists name, ' +
         'description, and per-skill URI (canvas://skills/<name>). Read a specific ' +
         'skill for workflow guidance — notably web-artifacts-builder for ' +
-        'canvas_build_web_artifact, and pmx-canvas for the broader workbench.',
+        'canvas_app { action: "build-artifact" }, and pmx-canvas for the broader workbench.',
       mimeType: 'application/json',
     },
     async () => {

package/src/server/ax-state-manager.ts

@@ -7,8 +7,9 @@
  *
  *   • Canvas-bound (`_axState`): focus, work items, approval gates, review
  *     annotations, elicitations, mode requests, policy. Snapshotted, cleared by
- *     `canvas_clear`, replaced by `restore`. Mutators record undo/redo history
- *     (via the injected `recordMutation` / `suppressed` callbacks).
+ *     `canvas_view` (`clear` action), replaced by `restore`. Mutators record
+ *     undo/redo history (via the injected `recordMutation` / `suppressed`
+ *     callbacks).
  *   • Timeline (audit-only): agent events, evidence, steering. DB-direct, NOT in
  *     `_axState`, NOT history-recorded, NOT snapshotted, retention-bounded.
  *   • Host/session: a single host-capability row in its own table.

package/src/server/bundled-skills.ts

@@ -3,9 +3,9 @@
  *
  * Skill files ship inside the npm package under `skills/<name>/SKILL.md`
  * but until 0.1.2 they were not discoverable to the agent — an agent
- * calling `canvas_build_web_artifact` had no way to find the companion
- * `skills/web-artifacts-builder/SKILL.md` prompt that documents the
- * workflow, stack choices, and gotchas.
+ * calling `canvas_app` (`build-artifact` action) had no way to find the
+ * companion `skills/web-artifacts-builder/SKILL.md` prompt that documents
+ * the workflow, stack choices, and gotchas.
  *
  * This module locates the bundled `skills/` directory relative to the
  * package root (works for both repo-local development and global npm

package/src/server/canvas-schema.ts

@@ -80,7 +80,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Freeform markdown note.',
     endpoint: '/api/canvas/node',
-    mcpTool: 'canvas_add_node',
+    mcpTool: 'canvas_node (action:"add")',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional node title.' },
       { name: 'content', type: 'string', required: false, description: 'Markdown body.' },
@@ -104,7 +104,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Compact status indicator.',
     endpoint: '/api/canvas/node',
-    mcpTool: 'canvas_add_node',
+    mcpTool: 'canvas_node (action:"add")',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Status label.' },
       { name: 'content', type: 'string', required: false, description: 'Rendered status text.' },
@@ -120,7 +120,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Agent context card container.',
     endpoint: '/api/canvas/node',
-    mcpTool: 'canvas_add_node',
+    mcpTool: 'canvas_node (action:"add")',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
       { name: 'content', type: 'string', required: false, description: 'Optional context body.' },
@@ -136,7 +136,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Structured ledger/log node.',
     endpoint: '/api/canvas/node',
-    mcpTool: 'canvas_add_node',
+    mcpTool: 'canvas_node (action:"add")',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional title.' },
       { name: 'content', type: 'string', required: false, description: 'Ledger body text.' },
@@ -152,7 +152,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Execution trace viewer.',
     endpoint: '/api/canvas/node',
-    mcpTool: 'canvas_add_node',
+    mcpTool: 'canvas_node (action:"add")',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional title.' },
       { name: 'content', type: 'string', required: false, description: 'Trace summary.' },
@@ -175,7 +175,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Workspace file viewer.',
     endpoint: '/api/canvas/node',
-    mcpTool: 'canvas_add_node',
+    mcpTool: 'canvas_node (action:"add")',
     fields: [
       { name: 'content', type: 'string', required: true, description: 'Workspace-relative or absolute file path.' },
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
@@ -193,7 +193,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Image node backed by a path, URL, or data URI.',
     endpoint: '/api/canvas/node',
-    mcpTool: 'canvas_add_node',
+    mcpTool: 'canvas_node (action:"add")',
     fields: [
       { name: 'content', type: 'string', required: true, description: 'Image path, URL, or data URI.', aliases: ['path'] },
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
@@ -219,7 +219,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Persisted webpage snapshot with server-side fetch and refresh.',
     endpoint: '/api/canvas/node',
-    mcpTool: 'canvas_add_node',
+    mcpTool: 'canvas_node (action:"add")',
     fields: [
       { name: 'url', type: 'string', required: true, description: 'HTTP(S) URL to fetch and cache.', aliases: ['content'] },
       { name: 'title', type: 'string', required: false, description: 'Optional title override.' },
@@ -314,7 +314,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Hosted iframe/app node.',
     endpoint: '/api/canvas/node',
-    mcpTool: 'canvas_open_mcp_app',
+    mcpTool: 'canvas_app (action:"open-mcp-app")',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'App title.' },
       { name: 'content', type: 'string', required: false, description: 'Optional inline content.' },
@@ -333,7 +333,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'virtual-node',
     description: 'Tool-backed hosted app opened from an external MCP server, such as Excalidraw.',
     endpoint: '/api/canvas/mcp-app/open',
-    mcpTool: 'canvas_open_mcp_app',
+    mcpTool: 'canvas_app (action:"open-mcp-app")',
     fields: [
       { name: 'toolName', type: 'string', required: true, description: 'Tool name on the external MCP server.' },
       { name: 'transport', type: '{ type: "stdio", command, args? } | { type: "http", url, headers? }', required: true, description: 'External MCP transport definition.' },
@@ -347,8 +347,8 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
       title: 'Excalidraw Diagram',
     },
     notes: [
-      'For Excalidraw specifically, prefer canvas_add_diagram because it fills in the built-in transport, toolName, and checkpoint wiring.',
-      'The CLI convenience command `external-app add --kind excalidraw` maps to this built-in Excalidraw preset; MCP canvas_open_mcp_app is the lower-level transport form.',
+      'For Excalidraw specifically, prefer canvas_app (action:"diagram") because it fills in the built-in transport, toolName, and checkpoint wiring.',
+      'The CLI convenience command `external-app add --kind excalidraw` maps to this built-in Excalidraw preset; MCP canvas_app (action:"open-mcp-app") is the lower-level transport form.',
     ],
   },
   {
@@ -356,7 +356,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Canvas group frame.',
     endpoint: '/api/canvas/group',
-    mcpTool: 'canvas_create_group',
+    mcpTool: 'canvas_group (action:"create")',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Group title.' },
       { name: 'childIds', type: 'string[]', required: false, description: 'Initial child node IDs.' },
@@ -373,7 +373,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'virtual-node',
     description: 'Native structured UI panel rendered from a validated json-render spec.',
     endpoint: '/api/canvas/json-render',
-    mcpTool: 'canvas_add_json_render_node',
+    mcpTool: 'canvas_render (action:"add-json-render")',
     fields: [
       { name: 'title', type: 'string', required: false, description: 'Optional rendered node title; inferred from the root element when omitted.' },
       { name: 'spec', type: 'JsonRenderSpec | JsonRenderElement', required: true, description: 'Complete {root, elements} json-render spec, or a legacy single bare component object with a type field.' },
@@ -406,7 +406,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'virtual-node',
     description: 'Native chart node backed by the json-render chart catalog.',
     endpoint: '/api/canvas/graph',
-    mcpTool: 'canvas_add_graph_node',
+    mcpTool: 'canvas_render (action:"add-graph")',
     fields: [
       {
         name: 'graphType',
@@ -467,7 +467,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'virtual-node',
     description: 'Bundled single-file HTML artifact that can open as an embedded canvas node.',
     endpoint: '/api/canvas/web-artifact',
-    mcpTool: 'canvas_build_web_artifact',
+    mcpTool: 'canvas_app (action:"build-artifact")',
     fields: [
       { name: 'title', type: 'string', required: true, description: 'Artifact title used for default paths.' },
       { name: 'appTsx', type: 'string', required: true, description: 'Contents for src/App.tsx. The CLI also accepts piped contents via --stdin.', aliases: ['app-file', 'app-tsx'] },
@@ -556,19 +556,36 @@ export function describeCanvasSchema(): {
     htmlPrimitives: listHtmlPrimitiveDescriptors(),
     mcp: {
       tools: [
-        'canvas_add_node',
-        'canvas_add_html_node',
-        'canvas_add_html_primitive',
-        'canvas_add_json_render_node',
-        'canvas_stream_json_render_node',
-        'canvas_add_graph_node',
-        'canvas_build_web_artifact',
-        'canvas_open_mcp_app',
-        'canvas_create_group',
-        'canvas_update_node',
-        'canvas_fit_view',
-        'canvas_describe_schema',
-        'canvas_validate_spec',
+        // 15 composites
+        'canvas_node',
+        'canvas_render',
+        'canvas_edge',
+        'canvas_group',
+        'canvas_history',
+        'canvas_view',
+        'canvas_query',
+        'canvas_webview',
+        'canvas_app',
+        'canvas_ax_state',
+        'canvas_ax_work',
+        'canvas_ax_gate',
+        'canvas_ax_timeline',
+        'canvas_ax_delivery',
+        'canvas_intent',
+        // 6 standalones
+        'canvas_batch',
+        'canvas_pin_nodes',
+        'canvas_invoke_command',
+        'canvas_ax_interaction',
+        'canvas_ingest_activity',
+        'canvas_screenshot',
+        // 6 snapshot tools (deprecated; fold into canvas_snapshot composite in v0.4)
+        'canvas_snapshot',
+        'canvas_list_snapshots',
+        'canvas_restore',
+        'canvas_delete_snapshot',
+        'canvas_gc_snapshots',
+        'canvas_diff',
       ],
       resources: ['canvas://schema'],
       nodeTypeRouting: buildMcpNodeTypeRouting(nodeTypes),

package/src/server/canvas-state.ts

@@ -571,6 +571,11 @@ class CanvasStateManager {
   private _db: import('bun:sqlite').Database | null = null;
   private _saveTimer: ReturnType<typeof setTimeout> | null = null;
 
+  /** Workspace root backing persistence and workspace-relative path resolution. */
+  get workspaceRoot(): string {
+    return this._workspaceRoot;
+  }
+
   /** Set the workspace root to enable auto-persistence. */
   setWorkspaceRoot(workspaceRoot: string): void {
     this.close();

package/src/server/code-graph.ts

@@ -113,7 +113,7 @@ function resolveImportPath(specifier: string, fromFilePath: string): string | nu
     // Check if it looks like a relative project path (contains / and no @)
     if (!specifier.includes('/') || specifier.startsWith('@')) return null;
     // For non-relative paths, try workspace-relative resolution
-    const wsRoot = process.cwd();
+    const wsRoot = canvasState.workspaceRoot;
     return tryResolveWithExtensions(resolve(wsRoot, specifier));
   }
 

package/src/server/ext-app-lookup.ts

@@ -9,9 +9,7 @@
  * Resolution order:
  *   1. The direct prefixed form (`ext-app-<toolCallId>` if not already
  *      prefixed, otherwise `toolCallId` as-is).
- *   2. The legacy `ext-app-ext-app-…` form, for canvases persisted before
- *      v0.1.4 and still on disk. Remove this fallback in v0.2.x.
- *   3. A scan of the layout for any `mcp-app` ext-app node carrying that
+ *   2. A scan of the layout for any `mcp-app` ext-app node carrying that
  *      `toolCallId` in its data.
  */
 import type { CanvasNodeState } from './canvas-state.js';
@@ -30,11 +28,6 @@ export function findCanvasExtAppNodeId(
     : `ext-app-${toolCallId}`;
   if (source.getNode(directId)) return directId;
 
-  const legacyDirectId = `ext-app-${toolCallId}`;
-  if (legacyDirectId !== directId && source.getNode(legacyDirectId)) {
-    return legacyDirectId;
-  }
-
   for (const node of source.listNodes()) {
     if (
       node.type === 'mcp-app' &&