pmx-canvas 0.9.3 → 0.10.0

package/skills/pmx-canvas/SKILL.md

@@ -106,7 +106,7 @@ for the authoritative stop, viewport, persistence, reset, group-order, and captu
 
 ## Runtime prerequisites
 
-PMX Canvas 0.9.3 requires **Bun >=1.4.4**, including when installed through npm.
+PMX Canvas 0.10.0 requires **Bun >=1.4.4**, including when installed through npm.
 Check `bun --version` and ensure Bun is on the MCP host's PATH, not just your shell's;
 use an absolute executable path if needed. Install/configure only when requested.
 For pinned installation, MCP configuration, managed services, and disposable verification,
@@ -264,10 +264,15 @@ json-render, a graph, or an HTML primitive is sufficient.
 
 ## Current MCP Composites
 
-The live MCP surface is **24 tools**: the 18 composites below plus 6 standalones. This table is
+The live MCP surface is **25 tools**: the 18 composites below plus 7 standalones. This table is
 kept in sync with the server's composite registry; `tools/list` on a fresh `pmx-canvas --mcp` is
 always authoritative, independent of the installed release version.
 
+Use `canvas_help {}` to list MCP registry operation names, then `canvas_help { op: "node.add" }`
+for that operation's public tool, argument schema and guidance. Help does not start or read a
+canvas. The schema includes routing selectors and required fields; handlers still enforce
+conditional requirements. Use `tools/list` for non-registry tools such as `canvas_screenshot`.
+
 | Composite | Actions |
 |-----------|---------|
 | `canvas_import` | `list`, `read`, `submit`, `unavailable` |
@@ -303,7 +308,7 @@ Important routing:
 As of v0.3.0, the 57 legacy single-purpose tools from the v0.2 compatibility window are removed.
 The composites above plus the retained standalones are now the whole MCP surface: `canvas_batch`,
 `canvas_pin_nodes`, `canvas_screenshot`, `canvas_ax_interaction`, `canvas_ingest_activity`, and
-`canvas_invoke_command`. Snapshots are the `canvas_snapshot` composite (actions
+`canvas_invoke_command`, plus `canvas_help`. Snapshots are the `canvas_snapshot` composite (actions
 `save | list | restore | restore-node | delete | gc | diff`); the 6 legacy snapshot standalones were removed in
 v0.4.0 after their deprecated 0.3.x window.
 
@@ -683,7 +688,7 @@ Single-card and layout reads record content delivery, not incident relations.
 Graph cards and complete brief relations carry a captured `linksRevision`: reads
 acknowledge that version, not later changes. Brief delivery is qualified by source board.
 Reads never switch boards or mark full content read; pull needed cards in full separately. MCP remains
-24 tools and 15 static canvas resources, with two canvas templates (context/graph).
+25 tools and 15 static canvas resources, with two canvas templates (context/graph).
 
 Markdown saves bind `[[Board]]`, `[[Board#Card]]`, and `|alias` forms to durable
 IDs; code spans/fences are ignored. Ambiguous/missing targets never guess or

package/skills/pmx-canvas/references/full-reference.md

@@ -431,10 +431,15 @@ When you do set a color (group/graph), use this palette consistently to convey m
 ## MCP Tools Reference
 
 PMX Canvas exposes **18 action-discriminated composites** (the whole recommended surface) plus
-**6 first-class standalones** — 24 tools total. The composites fold the older
+**7 first-class standalones** — 25 tools total. The composites fold the older
 single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) discriminator —
 **field names are unchanged**; only the tool name + the `action`/`kind` selector differ.
 
+`canvas_help {}` lists MCP registry operation names. `canvas_help { op: "node.add" }`
+returns that operation's public tool, description and JSON argument schema, including
+routing selectors and required fields. It does not start or read a canvas. Handlers still
+enforce conditional requirements. Non-registry tools use `tools/list` instead.
+
 > **Legacy single-purpose tools were removed in v0.3.0.** The old names (`canvas_add_node`,
 > `canvas_update_node`, `canvas_request_approval`, `canvas_add_work_item`, …) are no longer
 > registered — use the composites below and fresh MCP `tools/list` for the installed runtime's
@@ -531,7 +536,7 @@ AX excerpts and annotation anchors, including `canvas://ax-context` and
 or brief relation entry instead.
 Single-card and layout reads record content delivery, not incident relations.
 Reads never switch boards or record full content reads. Pull cards in full
-when needed. Counts stay 24 tools, 15 static canvas resources; there are now two
+when needed. Counts are 25 tools, 15 static canvas resources; there are now two
 canvas templates, context and graph, besides the skill file template.
 
 Markdown save resolves `[[Board]]`, `[[Board#Card]]`, and `|alias` forms into
@@ -1124,11 +1129,39 @@ Use native `json-render` and `graph` nodes when the output should stay fully ins
 
 Spec elements support an `on` map (`on.press`, `on.change`, …) binding events to actions (`{ action, params }`) — built-in actions (`setState`, `pushState`, …) or, when named after an AX interaction type, a capability-gated AX emit. e.g. a Button with `on: { press: { action: 'ax.work.create', params: { title: '…' } } }` lets a human turn a panel control into a tracked work item; the viewer forwards it to the canvas, which validates and submits it server-side (clamped to the node's own id). See **Node AX Interactions** above.
 
+## MCP results and cancellation (0.10)
+
+The 25-tool catalog remains on MCP SDK v1. Each tool advertises `outputSchema`
+and effect annotations. Help returns `structuredContent.result` with operation
+metadata (or the name list); it records no content reads. Registry-dispatched tools expose
+`structuredContent.result = { operation, outcome, data }`, where `outcome` is
+`success`, `error` or `partial`; `data` matches the existing compact text JSON,
+or `{message}` for prose. Exceptions use `operation: null`; they do not prove no
+writes occurred. Interaction, activity-ingestion and screenshot tools instead
+use direct structured objects matching their schemas. Check `isError` and domain
+outcomes. A composite's annotations cover all its actions, not just reads.
+
+Cancellation releases supported AX waits, aborts webpage fetches before late
+content writes, and stops subsequent batch operations. Completed writes remain;
+batch partial results retain `results` and `refs`. A created webpage can remain
+with `fetch.cancelled: true`. External app builds/runtime calls and local WebView
+captures are not interruptible mid-call. After a disconnect, inspect state before
+retrying because the response may not arrive. `_meta.progressToken` enables batch
+and supported AX wait progress notifications, including through the daemon connection. Without
+a token, calls return their normal result without progress notifications.
+
 ## MCP Resources
 
 These resources give you read access to canvas intelligence. Read them to understand
 what the human has set up and what they're focusing on.
 
+As of 0.10, live resource updates require `resources/subscribe` on each connection.
+Subscribe to the exact URI you read, including context/graph query parameters;
+`resources/unsubscribe` stops it, and reconnecting requires a new subscription.
+Notifications invalidate cached data but do not deliver content, record a read, or
+advance a consumer cursor. Explicit `resources/read` remains available without
+subscriptions. Static schema and bundled skills do not support subscriptions.
+
 | Resource | What it provides |
 |----------|-----------------|
 | `canvas://context{?budget,consumer,since}` | Budgeted cross-board map brief with optional durable consumer cursor |

package/skills/pmx-canvas/references/installing-pmx-canvas.md

@@ -4,7 +4,7 @@ Use this reference when the `pmx-canvas` skill is installed but the `pmx-canvas`
 
 ## Prerequisites and version
 
-The examples pin **PMX Canvas 0.9.3**, which requires **Bun >=1.4.4** even when
+The examples pin **PMX Canvas 0.10.0**, which requires **Bun >=1.4.4** even when
 installed through npm: the CLI runs through Bun, not Node. Check `bun --version`
 first. If missing or older, follow the [Bun installation instructions](https://bun.sh/docs/installation)
 with the user's authorization. Ensure Bun is on the MCP host's PATH as well as the
@@ -22,11 +22,11 @@ in `SKILL.md`. Do not pair newer checkout guidance with an older runtime unknowi
 ## Install from npm
 
 ```bash
-npm install -g pmx-canvas@0.9.3
+npm install -g pmx-canvas@0.10.0
 pmx-canvas --version
 ```
 
-Without a global install, use `bunx pmx-canvas@0.9.3` in place of `pmx-canvas` in
+Without a global install, use `bunx pmx-canvas@0.10.0` in place of `pmx-canvas` in
 the commands below. Do not use unpinned `bunx pmx-canvas` for a version-specific check.
 
 ## Choose the workspace and target
@@ -96,7 +96,7 @@ discards empty env values, remove `PMX_CANVAS_URL` from its launch environment i
   "mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas@0.9.3", "--mcp"],
+      "args": ["pmx-canvas@0.10.0", "--mcp"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
         "PMX_CANVAS_PORT": "14313",
@@ -140,7 +140,7 @@ Amp executes, not only on the user's laptop. Merge this into that workspace's
   "amp.mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas@0.9.3", "--mcp"],
+      "args": ["pmx-canvas@0.10.0", "--mcp"],
       "includeTools": ["canvas_*"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
@@ -174,8 +174,8 @@ The agent must not run this approval itself or move the command to global settin
 `--mcp-config` to bypass workspace trust. Approval authorizes execution of this MCP
 command; it is not a new Canvas import consent or permission to mutate arbitrary boards.
 After approval, reload MCP connections (`reload_mcp` in Amp) and require `connected`.
-Discover `canvas` tools with `tool_search`; for the full unfiltered 0.9.3 server there
-are 24 tools. If still absent, inspect the server status, command/PATH and target instead
+Discover `canvas` tools with `tool_search`; the full unfiltered 0.10.0 server has 25 tools,
+including `canvas_help`. If still absent, inspect the server status, command/PATH and target instead
 of reinstalling blindly. See [Amp MCP documentation](https://ampcode.com/docs/customize/mcp).
 
 ### Verify native tools, then steering

package/src/client/canvas/ToolRail.tsx

@@ -97,6 +97,8 @@ function RailButton({
 }) {
   const [hint, setHint] = useState<{ left: number; top: number } | null>(null);
   const show = (e: Event) => {
+    // Closing the menu restores focus before it unmounts; that must not reopen the hint.
+    if (menuOpen) return;
     const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
     setHint({ left: rect.right + 10, top: rect.top + rect.height / 2 });
   };

package/src/mcp/canvas-access.ts

@@ -2,7 +2,6 @@ import { realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, resolve } from 'node:path';
 import { createCanvas, canvasState, type CanvasLayout, type CanvasNodeState, type PmxCanvas } from '../server/index.js';
-import type { PmxAxSource } from '../server/ax-state.js';
 import type { ContextReadInput } from '../server/context-reads.js';
 import { HttpOperationInvoker, LocalOperationInvoker, type OperationInvoker } from '../server/operations/index.js';
 
@@ -14,13 +13,9 @@ import { HttpOperationInvoker, LocalOperationInvoker, type OperationInvoker } fr
 // not CanvasAccess. The public SDK PmxCanvas methods are unchanged.
 type AxStateResult = ReturnType<PmxCanvas['getAxState']>;
 type AxContextResult = ReturnType<PmxCanvas['getAxContext']>;
-type SubmitAxInteractionInput = Parameters<PmxCanvas['submitAxInteraction']>[0];
-type SubmitAxInteractionResult = ReturnType<PmxCanvas['submitAxInteraction']>;
 type GetPendingSteeringResult = ReturnType<PmxCanvas['getPendingSteering']>;
 type ListElicitationsResult = ReturnType<PmxCanvas['listElicitations']>;
 type ListModeRequestsResult = ReturnType<PmxCanvas['listModeRequests']>;
-type IngestActivityInput = Parameters<PmxCanvas['ingestActivity']>[0];
-type IngestActivityResult = ReturnType<PmxCanvas['ingestActivity']>;
 type GetPolicyResult = ReturnType<PmxCanvas['getPolicy']>;
 type GetAxTimelineQuery = Parameters<PmxCanvas['getAxTimeline']>[0];
 type GetAxTimelineResult = ReturnType<PmxCanvas['getAxTimeline']>;
@@ -56,14 +51,9 @@ export interface CanvasAccess {
   listWorkItems(): Promise<ListWorkItemsResult>;
   listApprovalGates(): Promise<ListApprovalGatesResult>;
   listReviewAnnotations(): Promise<ListReviewAnnotationsResult>;
-  submitAxInteraction(
-    input: SubmitAxInteractionInput,
-    options?: { source?: PmxAxSource },
-  ): Promise<SubmitAxInteractionResult>;
   getPendingSteering(options?: { consumer?: string; limit?: number }): Promise<GetPendingSteeringResult>;
   listElicitations(): Promise<ListElicitationsResult>;
   listModeRequests(): Promise<ListModeRequestsResult>;
-  ingestActivity(input: IngestActivityInput, options?: { source?: PmxAxSource }): Promise<IngestActivityResult>;
   getPolicy(): Promise<GetPolicyResult>;
   getHistory(): Promise<HistoryResult>;
   getPinnedNodeIds(board?: string): Promise<string[]>;
@@ -75,7 +65,7 @@ export interface CanvasAccess {
   // canvas_screenshot (still hand-written — binary payload) is the only webview
   // tool left on CanvasAccess; it needs the status + screenshot accessors.
   getAutomationWebViewStatus(): Promise<AutomationWebViewStatus>;
-  screenshotAutomationWebView(options?: AutomationScreenshotOptions): Promise<Uint8Array>;
+  screenshotAutomationWebView(options?: AutomationScreenshotOptions, signal?: AbortSignal): Promise<Uint8Array>;
 }
 
 class LocalCanvasAccess implements CanvasAccess {
@@ -123,13 +113,6 @@ class LocalCanvasAccess implements CanvasAccess {
     return this.canvas.getAxTimeline(query);
   }
 
-  async submitAxInteraction(
-    input: SubmitAxInteractionInput,
-    options?: { source?: PmxAxSource },
-  ): Promise<SubmitAxInteractionResult> {
-    return this.canvas.submitAxInteraction(input, { source: options?.source ?? 'mcp' });
-  }
-
   async getPendingSteering(options?: { consumer?: string; limit?: number }): Promise<GetPendingSteeringResult> {
     return this.canvas.getPendingSteering(options);
   }
@@ -142,10 +125,6 @@ class LocalCanvasAccess implements CanvasAccess {
     return this.canvas.listModeRequests();
   }
 
-  async ingestActivity(input: IngestActivityInput, options?: { source?: PmxAxSource }): Promise<IngestActivityResult> {
-    return this.canvas.ingestActivity(input, { source: options?.source ?? 'mcp' });
-  }
-
   async getPolicy(): Promise<GetPolicyResult> {
     return this.canvas.getPolicy();
   }
@@ -299,23 +278,6 @@ class RemoteCanvasAccess implements CanvasAccess {
     return await this.requestJson<GetAxTimelineResult>('GET', `/api/canvas/ax/timeline${qs}`);
   }
 
-  async submitAxInteraction(
-    input: SubmitAxInteractionInput,
-    options?: { source?: PmxAxSource },
-  ): Promise<SubmitAxInteractionResult> {
-    // The interaction endpoint returns its structured outcome (ok/code/error) in
-    // the body for both accepted and rejected interactions, so read the body
-    // regardless of HTTP status rather than throwing on a denial.
-    const response = await fetch(`${this.remoteBaseUrl}/api/canvas/ax/interaction`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ ...input, source: options?.source ?? 'mcp' }),
-    });
-    const body = await response.json().catch(() => null);
-    if (body && typeof body === 'object') return body as SubmitAxInteractionResult;
-    throw new Error(`Remote canvas interaction failed with HTTP ${response.status}`);
-  }
-
   async getPendingSteering(options?: { consumer?: string; limit?: number }): Promise<GetPendingSteeringResult> {
     const params = new URLSearchParams();
     if (options?.consumer) params.set('consumer', options.consumer);
@@ -338,13 +300,6 @@ class RemoteCanvasAccess implements CanvasAccess {
     return r.modeRequests ?? [];
   }
 
-  async ingestActivity(input: IngestActivityInput, options?: { source?: PmxAxSource }): Promise<IngestActivityResult> {
-    return await this.requestJson<IngestActivityResult>('POST', '/api/canvas/ax/activity', {
-      ...input,
-      source: options?.source ?? 'mcp',
-    });
-  }
-
   async getPolicy(): Promise<GetPolicyResult> {
     const r = await this.requestJson<{ policy?: GetPolicyResult }>('GET', '/api/canvas/ax/policy');
     if (!r.policy) throw new Error('Remote canvas did not return a policy.');
@@ -404,11 +359,15 @@ class RemoteCanvasAccess implements CanvasAccess {
     return await this.requestJson<AutomationWebViewStatus>('GET', '/api/workbench/webview');
   }
 
-  async screenshotAutomationWebView(options: AutomationScreenshotOptions = {}): Promise<Uint8Array> {
+  async screenshotAutomationWebView(
+    options: AutomationScreenshotOptions = {},
+    signal?: AbortSignal,
+  ): Promise<Uint8Array> {
     const response = await fetch(`${this.remoteBaseUrl}/api/workbench/webview/screenshot`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(options),
+      signal,
     });
     if (!response.ok) {
       const text = await response.text();

package/src/mcp/resource-subscriptions.ts

@@ -0,0 +1,181 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import {
+  ErrorCode,
+  McpError,
+  SubscribeRequestSchema,
+  UnsubscribeRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { canvasState } from '../server/canvas-state.js';
+import { onWorkbenchEvent } from '../server/server.js';
+import type { CanvasAccess } from './canvas-access.js';
+import { ContextUriTemplate } from './context-uri-template.js';
+
+const liveResources = new Set(
+  [
+    'layout',
+    'boards',
+    'summary',
+    'context',
+    'graph',
+    'spatial-context',
+    'history',
+    'code-graph',
+    'pinned-context',
+    'ax',
+    'ax-context',
+    'ax-timeline',
+    'ax-work',
+    'ax-pending-steering',
+    'ax-delivery',
+  ].map((name) => `canvas://${name}`),
+);
+const contextTemplate = new ContextUriTemplate();
+const graphTemplate = new ContextUriTemplate('graph', ['focus', 'depth']);
+
+// A context-status-changed read receipt must never trigger another read forever.
+const resourceEvents = new Set([
+  'context-pins-changed',
+  'boards-changed',
+  'knowledge-changed',
+  'ax-state-changed',
+  'ax-event-created',
+  'canvas-layout-update',
+  'canvas-viewport-update',
+  'canvas-camera-move',
+  'canvas-tour-step',
+  'canvas-tour-exit',
+  // These events synchronize node data inside server.ts.
+  'workbench-open',
+  'ext-app-open',
+  'ext-app-update',
+  'ext-app-result',
+  'context-cards',
+  'context-usage',
+  'aux-open',
+  'aux-close',
+  'canvas-status',
+  'execution-phase',
+  'canvas-response-start',
+  'canvas-response-delta',
+  'canvas-response-complete',
+]);
+
+function isLiveResource(uri: string): boolean {
+  return liveResources.has(uri) || contextTemplate.match(uri) !== null || graphTemplate.match(uri) !== null;
+}
+
+/** One subscription set and event source per MCP connection. Notifications are not reads. */
+export function registerResourceSubscriptions(server: McpServer, getCanvas: () => Promise<CanvasAccess>) {
+  const subscriptions = new Set<string>();
+  let disposeSource: (() => void) | undefined;
+  let source: string | null | undefined;
+  let closed = false;
+
+  function notify(): void {
+    // Broad invalidation is intentional: context projections span pins, nodes and AX.
+    for (const uri of subscriptions) {
+      void server.server.sendResourceUpdated({ uri }).catch((error: unknown) => {
+        if (!closed) console.error('[mcp] resource notification failed:', error);
+      });
+    }
+  }
+
+  async function watchRemote(baseUrl: string, signal: AbortSignal): Promise<void> {
+    while (!signal.aborted) {
+      try {
+        const response = await fetch(`${baseUrl}/api/workbench/events`, { signal });
+        if (!response.ok || !response.body) throw new Error(`Canvas event stream: HTTP ${response.status}`);
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+          // Reconnecting may have missed a change. Invalidate subscribed URIs only.
+          notify();
+          while (!signal.aborted) {
+            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) {
+              const event = frame
+                .split('\n')
+                .find((line) => line.startsWith('event:'))
+                ?.slice(6)
+                .trim();
+              if (event && resourceEvents.has(event)) notify();
+            }
+          }
+        } finally {
+          await reader.cancel().catch(() => {});
+          reader.releaseLock();
+        }
+      } catch (error) {
+        if (signal.aborted) return;
+        console.error('[mcp] canvas event stream disconnected:', error);
+      }
+      try {
+        await delay(1_000, undefined, { signal });
+      } catch {
+        return;
+      }
+    }
+  }
+
+  function attach(canvas: CanvasAccess): void {
+    if (closed || subscriptions.size === 0 || source === canvas.remoteBaseUrl) return;
+    disposeSource?.();
+    source = canvas.remoteBaseUrl;
+    if (source) {
+      const controller = new AbortController();
+      disposeSource = () => controller.abort();
+      void watchRemote(source, controller.signal);
+    } else {
+      const disposeState = canvasState.onChange(notify);
+      // Library-only writes do not change the active board's state.
+      const disposeEvents = onWorkbenchEvent((event) => {
+        if (resourceEvents.has(event)) notify();
+      });
+      disposeSource = () => {
+        disposeState();
+        disposeEvents();
+      };
+    }
+  }
+
+  function dispose(): void {
+    closed = true;
+    subscriptions.clear();
+    disposeSource?.();
+    disposeSource = undefined;
+    source = undefined;
+  }
+
+  server.server.registerCapabilities({ resources: { subscribe: true } });
+  server.server.setRequestHandler(SubscribeRequestSchema, async ({ params }, extra) => {
+    if (!isLiveResource(params.uri))
+      throw new McpError(ErrorCode.InvalidParams, `Resource does not support subscriptions: ${params.uri}`);
+    const canvas = await getCanvas();
+    extra.signal.throwIfAborted();
+    if (closed) throw new McpError(ErrorCode.InternalError, 'Connection closed');
+    subscriptions.add(params.uri);
+    attach(canvas);
+    return {};
+  });
+  server.server.setRequestHandler(UnsubscribeRequestSchema, ({ params }) => {
+    subscriptions.delete(params.uri);
+    if (subscriptions.size === 0) {
+      disposeSource?.();
+      disposeSource = undefined;
+      source = undefined;
+    }
+    return {};
+  });
+  const onclose = server.server.onclose;
+  server.server.onclose = () => {
+    dispose();
+    onclose?.();
+  };
+  return { attach, dispose };
+}