pmx-canvas 0.6.4 → 0.7.0

package/src/client/types.ts

@@ -14,6 +14,7 @@ export interface CanvasNodeState {
     | 'webpage'
     | 'json-render'
     | 'graph'
+    | 'board'
     | 'prompt'
     | 'response'
     | 'status'
@@ -74,6 +75,7 @@ export const TYPE_LABELS: Record<CanvasNodeState['type'], string> = {
   webpage: 'WEB',
   'json-render': 'UI',
   graph: 'GRAPH',
+  board: 'BOARD',
   prompt: 'ASK',
   response: 'ANS',
   status: 'STATUS',

package/src/json-render/server.ts

@@ -149,7 +149,7 @@ function bundleDir(): string {
   return candidates[candidates.length - 1];
 }
 
-function escapeInlineScriptSource(source: string): string {
+export function escapeInlineScriptSource(source: string): string {
   return source.replace(/<\/script/gi, '<\\/script');
 }
 
@@ -542,6 +542,35 @@ export function normalizeAndValidateJsonRenderSpec(spec: unknown): JsonRenderSpe
   return propsValidation.data as JsonRenderSpec;
 }
 
+/** shadcn 0.21 ignores these props unless the renderer supplies a two-way binding. */
+export function jsonRenderFormWarnings(spec: JsonRenderSpec): string[] {
+  const bindingOnlyProps: Record<string, string> = {
+    Input: 'value',
+    Textarea: 'value',
+    Select: 'value',
+    Radio: 'value',
+    Slider: 'value',
+    ToggleGroup: 'value',
+    ButtonGroup: 'selected',
+    Tabs: 'value',
+  };
+  const warnings: string[] = [];
+  for (const [key, rawElement] of Object.entries(spec.elements)) {
+    const element = asRecord(rawElement);
+    const type = typeof element?.type === 'string' ? element.type : '';
+    const prop = bindingOnlyProps[type];
+    if (!prop) continue;
+    const value = asRecord(element?.props)?.[prop];
+    if (value === undefined || value === null) continue;
+    const expression = asRecord(value);
+    if (hasString(expression?.$bindState) || hasString(expression?.$bindItem)) continue;
+    warnings.push(
+      `elements.${key}.props.${prop}: ${type} ignores an unbound ${prop} (including literal values and $state expressions). Use { "$bindState": "/form/field" } and seed spec.state.form.field with the initial value; inside a repeat use $bindItem with seeded item data.${type === 'Tabs' ? ' For an uncontrolled initial tab, use defaultValue instead.' : ''}`,
+    );
+  }
+  return warnings;
+}
+
 export function normalizeGraphType(value: string): GraphChartType {
   const normalized = value.toLowerCase().replace(/[-_\s]/g, '');
   return GRAPH_TYPE_ALIASES[normalized] ?? 'LineChart';
@@ -927,6 +956,20 @@ export function createJsonRenderNodeData(
   };
 }
 
+/** The viewer bundle's script and stylesheet, as the viewer document inlines them. */
+export async function readJsonRenderBundle(): Promise<{ js: string; css: string }> {
+  await ensureJsonRenderBundle();
+  const dir = bundleDir();
+  const jsPath = join(dir, 'index.js');
+  const cssPath = join(dir, 'index.css');
+  return {
+    js: existsSync(jsPath)
+      ? readFileSync(jsPath, 'utf-8')
+      : 'document.body.innerHTML = "<pre>json-render bundle missing</pre>";',
+    css: existsSync(cssPath) ? readFileSync(cssPath, 'utf-8') : '',
+  };
+}
+
 export async function buildJsonRenderViewerHtml(options: {
   title: string;
   spec: JsonRenderSpec;
@@ -946,14 +989,7 @@ export async function buildJsonRenderViewerHtml(options: {
   const sanitizeAxValue = (v?: string): string =>
     typeof v === 'string' ? v.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 80) : '';
   try {
-    await ensureJsonRenderBundle();
-    const dir = bundleDir();
-    const jsPath = join(dir, 'index.js');
-    const cssPath = join(dir, 'index.css');
-    const jsBundle = existsSync(jsPath)
-      ? readFileSync(jsPath, 'utf-8')
-      : 'document.body.innerHTML = "<pre>json-render bundle missing</pre>";';
-    const cssBundle = existsSync(cssPath) ? readFileSync(cssPath, 'utf-8') : '';
+    const { js: jsBundle, css: cssBundle } = await readJsonRenderBundle();
     const boot = [
       `window.__PMX_CANVAS_JSON_RENDER_SPEC__ = ${JSON.stringify(options.spec)};`,
       ...(options.theme ? [`window.__PMX_CANVAS_JSON_RENDER_THEME__ = ${JSON.stringify(options.theme)};`] : []),

package/src/mcp/canvas-access.ts

@@ -1,15 +1,9 @@
 import { realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, resolve } from 'node:path';
-import {
-  createCanvas,
-  canvasState,
-  type CanvasEdge,
-  type CanvasLayout,
-  type CanvasNodeState,
-  type PmxCanvas,
-} from '../server/index.js';
+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';
 
 // openMcpApp / addDiagram / buildWebArtifact / refreshWebpageNode / addHtmlNode /
@@ -54,8 +48,8 @@ export interface CanvasAccess {
   readonly remoteBaseUrl: string | null;
   /** Operation-registry invoker (plan-005): local in-process or HTTP, matching the access mode. */
   invoker(): OperationInvoker;
-  getLayout(): Promise<CanvasLayout>;
-  getNode(id: string): Promise<CanvasNodeState | undefined>;
+  getLayout(board?: string): Promise<CanvasLayout>;
+  getNode(id: string, board?: string): Promise<CanvasNodeState | undefined>;
   getAxState(): Promise<AxStateResult>;
   getAxContext(options?: { consumer?: string }): Promise<AxContextResult>;
   getAxTimeline(query?: GetAxTimelineQuery): Promise<GetAxTimelineResult>;
@@ -72,7 +66,10 @@ export interface CanvasAccess {
   ingestActivity(input: IngestActivityInput, options?: { source?: PmxAxSource }): Promise<IngestActivityResult>;
   getPolicy(): Promise<GetPolicyResult>;
   getHistory(): Promise<HistoryResult>;
-  getPinnedNodeIds(): Promise<string[]>;
+  getPinnedNodeIds(board?: string): Promise<string[]>;
+  prepareContextRead(board?: string): Promise<{ boardId: string | null; pinnedNodeIds: string[] }>;
+  /** Record a context read the agent made through this MCP server (plan-011). */
+  recordContextRead(read: ContextReadInput): Promise<void>;
   runBatch(operations: RunBatchInput): Promise<RunBatchResult>;
   getCodeGraph(): Promise<CodeGraphResult>;
   // canvas_screenshot (still hand-written — binary payload) is the only webview
@@ -99,11 +96,15 @@ class LocalCanvasAccess implements CanvasAccess {
     return this.operationInvoker;
   }
 
-  async getLayout(): Promise<CanvasLayout> {
-    return this.canvas.getLayout();
+  async getLayout(board?: string): Promise<CanvasLayout> {
+    return board
+      ? ((await this.operationInvoker.invoke('layout.get', { board, includeBlobs: true })) as CanvasLayout)
+      : this.canvas.getLayout();
   }
 
-  async getNode(id: string): Promise<CanvasNodeState | undefined> {
+  async getNode(id: string, board?: string): Promise<CanvasNodeState | undefined> {
+    if (board)
+      return (await this.operationInvoker.invoke('node.get', { id, board, includeBlobs: true })) as CanvasNodeState;
     return this.canvas.getNode(id);
   }
 
@@ -162,10 +163,23 @@ class LocalCanvasAccess implements CanvasAccess {
     return this.canvas.getHistory();
   }
 
-  async getPinnedNodeIds(): Promise<string[]> {
+  async getPinnedNodeIds(board?: string): Promise<string[]> {
+    if (board) {
+      const result = (await this.operationInvoker.invoke('pinned-context.get', { board })) as { nodeIds?: string[] };
+      return result.nodeIds ?? [];
+    }
     return Array.from(canvasState.contextPinnedNodeIds);
   }
 
+  async prepareContextRead(board?: string): Promise<{ boardId: string | null; pinnedNodeIds: string[] }> {
+    const boardId = board ?? canvasState.activeBoardId;
+    return { boardId, pinnedNodeIds: boardId ? await this.getPinnedNodeIds(boardId) : [] };
+  }
+
+  async recordContextRead(read: ContextReadInput): Promise<void> {
+    canvasState.recordContextRead(read, read.boardId === undefined ? canvasState.activeBoardId : read.boardId);
+  }
+
   async runBatch(operations: RunBatchInput): Promise<RunBatchResult> {
     return await this.canvas.runBatch(operations);
   }
@@ -202,7 +216,12 @@ class RemoteCanvasAccess implements CanvasAccess {
   private async requestJson<T>(method: string, path: string, body?: unknown): Promise<T> {
     const response = await fetch(`${this.remoteBaseUrl}${path}`, {
       method,
-      headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
+      // These fetches serve the agent's MCP reads, which this server records
+      // itself — the daemon must not record them a second time (plan-011).
+      headers: {
+        'x-pmx-proxied-read': '1',
+        ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+      },
       body: body === undefined ? undefined : JSON.stringify(body),
     });
     const text = await response.text();
@@ -227,12 +246,16 @@ class RemoteCanvasAccess implements CanvasAccess {
     return parsed as T;
   }
 
-  async getLayout(): Promise<CanvasLayout> {
-    return await this.requestJson<CanvasLayout>('GET', '/api/canvas/state?includeBlobs=true');
+  async getLayout(board?: string): Promise<CanvasLayout> {
+    const params = new URLSearchParams({ includeBlobs: 'true' });
+    if (board) params.set('board', board);
+    return await this.requestJson<CanvasLayout>('GET', `/api/canvas/state?${params}`);
   }
 
-  async getNode(id: string): Promise<CanvasNodeState | undefined> {
-    const response = await fetch(`${this.remoteBaseUrl}/api/canvas/node/${encodeURIComponent(id)}?includeBlobs=true`);
+  async getNode(id: string, board?: string): Promise<CanvasNodeState | undefined> {
+    const params = new URLSearchParams({ includeBlobs: 'true' });
+    if (board) params.set('board', board);
+    const response = await fetch(`${this.remoteBaseUrl}/api/canvas/node/${encodeURIComponent(id)}?${params}`);
     if (response.status === 404) return undefined;
     const text = await response.text();
     let parsed: unknown;
@@ -346,11 +369,25 @@ class RemoteCanvasAccess implements CanvasAccess {
     return response.reviewAnnotations ?? [];
   }
 
-  async getPinnedNodeIds(): Promise<string[]> {
-    const response = await this.requestJson<{ nodeIds?: string[] }>('GET', '/api/canvas/pinned-context');
+  async getPinnedNodeIds(board?: string): Promise<string[]> {
+    const qs = board ? `?board=${encodeURIComponent(board)}` : '';
+    const response = await this.requestJson<{ nodeIds?: string[] }>('GET', `/api/canvas/pinned-context${qs}`);
     return Array.isArray(response.nodeIds) ? response.nodeIds : [];
   }
 
+  async prepareContextRead(board?: string): Promise<{ boardId: string | null; pinnedNodeIds: string[] }> {
+    let boardId = board;
+    if (!boardId) {
+      const boards = await this.requestJson<{ activeBoardId?: string | null }>('GET', '/api/canvas/boards');
+      boardId = boards.activeBoardId ?? undefined;
+    }
+    return { boardId: boardId ?? null, pinnedNodeIds: boardId ? await this.getPinnedNodeIds(boardId) : [] };
+  }
+
+  async recordContextRead(read: ContextReadInput): Promise<void> {
+    await this.requestJson('POST', '/api/canvas/ax/context-reads', read);
+  }
+
   async runBatch(operations: RunBatchInput): Promise<RunBatchResult> {
     return await this.requestJson<RunBatchResult>('POST', '/api/canvas/batch', { operations });
   }

package/src/mcp/context-uri-template.ts

@@ -0,0 +1,28 @@
+import { UriTemplate } from '@modelcontextprotocol/sdk/shared/uriTemplate.js';
+
+/** SDK v1 matches {?a,b} as two required, ordered parameters, unlike its expansion. */
+export class ContextUriTemplate extends UriTemplate {
+  constructor() {
+    super('canvas://context{?budget,consumer,since}');
+  }
+
+  override match(uri: string): Record<string, string> | null {
+    if (!URL.canParse(uri)) return null;
+    const url = new URL(uri);
+    if (
+      url.protocol !== 'canvas:' ||
+      url.host !== 'context' ||
+      url.pathname ||
+      url.hash ||
+      url.username ||
+      url.password
+    )
+      return null;
+    const variables: Record<string, string> = {};
+    for (const [key, value] of url.searchParams) {
+      if (!['budget', 'consumer', 'since'].includes(key) || key in variables) return null;
+      variables[key] = value;
+    }
+    return variables;
+  }
+}

package/src/mcp/server.ts

@@ -23,7 +23,7 @@
 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 { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { AX_SOURCES } from '../server/operations/ops/ax-shared.js';
@@ -31,6 +31,8 @@ import { canvasState, describeCanvasSchema, stopCanvasServer } from '../server/i
 import { AX_INTERACTION_TYPES } from '../server/ax-interaction.js';
 import { buildPendingAxActivity } from '../server/ax-state.js';
 import { registerOperationTools, registerCompositeTools } from '../server/operations/index.js';
+import { agentSourceLabel } from '../server/operations/invoker.js';
+import { contextReadFromPayload } from '../server/context-reads.js';
 import { createCanvasAccess, refreshCanvasAccess, type CanvasAccess } from './canvas-access.js';
 import { serializeNodeForAgentContext } from '../server/agent-context.js';
 import { buildSpatialContext, findNeighborhoods } from '../server/spatial-analysis.js';
@@ -42,6 +44,7 @@ import {
 } from '../server/canvas-serialization.js';
 import { listBundledSkills, readBundledSkill } from '../server/bundled-skills.js';
 import { registerSkillExtension } from './skills.js';
+import { ContextUriTemplate } from './context-uri-template.js';
 
 let canvas: CanvasAccess | null = null;
 let resourceNotificationServer: McpServer | null = null;
@@ -102,7 +105,9 @@ function sendCanvasResourceNotifications(type: 'nodes' | 'pins' | 'ax' | 'ax-tim
       server.server.sendResourceUpdated({ uri: 'canvas://ax-delivery' });
     }
     server.server.sendResourceUpdated({ uri: 'canvas://layout' });
+    server.server.sendResourceUpdated({ uri: 'canvas://boards' });
     server.server.sendResourceUpdated({ uri: 'canvas://summary' });
+    server.server.sendResourceUpdated({ uri: 'canvas://context' });
     server.server.sendResourceUpdated({ uri: 'canvas://spatial-context' });
     server.server.sendResourceUpdated({ uri: 'canvas://history' });
     server.server.sendResourceUpdated({ uri: 'canvas://code-graph' });
@@ -223,6 +228,36 @@ export async function startMcpServer(): Promise<void> {
   resourceNotificationServer = server;
   registerSkillExtension(server);
 
+  /**
+   * Records what the agent actually received from a context resource or
+   * prompt (plan-011). Instrumentation must never fail the read itself.
+   */
+  async function recordContextRead(
+    c: CanvasAccess,
+    channel: 'mcp-resource' | 'mcp-prompt',
+    resource: string,
+    text: string,
+    target: { boardId: string | null; pinnedNodeIds: string[] },
+  ): Promise<void> {
+    try {
+      const read = contextReadFromPayload(
+        {
+          channel,
+          resource,
+          source: agentSourceLabel('mcp'),
+          consumer: server.server.getClientVersion()?.name ?? null,
+          agentId: null,
+          pinnedNodeIds: target.pinnedNodeIds,
+          boardId: target.boardId,
+        },
+        text,
+      );
+      await c.recordContextRead(read);
+    } catch (error) {
+      console.error('[pmx-canvas mcp] recording a context read failed:', error);
+    }
+  }
+
   // ── Operation-registry tools (plan-005) ────────────────────────
   // Standalone tools are registered from the shared operation registry for
   // every op not folded into a composite (registerOperationTools skips
@@ -478,8 +513,10 @@ export async function startMcpServer(): Promise<void> {
     },
     async () => {
       const c = await ensureCanvas();
-      const pinnedIds = new Set(await c.getPinnedNodeIds());
-      const layout = await c.getLayout();
+      const readTarget = await c.prepareContextRead();
+      const board = readTarget.boardId ?? undefined;
+      const pinnedIds = new Set(readTarget.pinnedNodeIds);
+      const layout = await c.getLayout(board);
 
       const pinnedNodes = layout.nodes.filter((n) => pinnedIds.has(n.id));
       const pinnedEdges = layout.edges.filter((e) => pinnedIds.has(e.from) && pinnedIds.has(e.to));
@@ -510,12 +547,41 @@ export async function startMcpServer(): Promise<void> {
         })),
       };
 
+      const text = JSON.stringify(context, null, 2);
+      await recordContextRead(c, 'mcp-resource', 'canvas://pinned-context', text, readTarget);
       return {
         contents: [
           {
             uri: 'canvas://pinned-context',
             mimeType: 'application/json',
-            text: JSON.stringify(context, null, 2),
+            text,
+          },
+        ],
+      };
+    },
+  );
+
+  server.resource(
+    'context',
+    new ResourceTemplate(new ContextUriTemplate(), { list: undefined }),
+    {
+      description:
+        'Budgeted cross-board context brief. budget is a maximum number of UTF-16 characters; consumer selects a durable board-scoped delivery cursor, while since requests an explicit revision.',
+      mimeType: 'application/json',
+    },
+    async (uri) => {
+      const c = await ensureCanvas();
+      const input: Record<string, unknown> = {};
+      if (uri.searchParams.has('consumer')) input.consumer = uri.searchParams.get('consumer');
+      if (uri.searchParams.has('budget')) input.budget = uri.searchParams.get('budget');
+      if (uri.searchParams.has('since')) input.since = uri.searchParams.get('since');
+      const document = await c.invoker().invoke('context.get', input);
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: 'application/json',
+            text: JSON.stringify(document),
           },
         ],
       };
@@ -555,12 +621,17 @@ export async function startMcpServer(): Promise<void> {
     async () => {
       const c = await ensureCanvas();
       const context = await c.getAxContext({ consumer: 'mcp' });
+      const text = JSON.stringify(context, null, 2);
+      await recordContextRead(c, 'mcp-resource', 'canvas://ax-context', text, {
+        boardId: context.boardId,
+        pinnedNodeIds: context.pinned.nodeIds,
+      });
       return {
         contents: [
           {
             uri: 'canvas://ax-context',
             mimeType: 'application/json',
-            text: JSON.stringify(context, null, 2),
+            text,
           },
         ],
       };
@@ -678,11 +749,16 @@ export async function startMcpServer(): Promise<void> {
     async () => {
       const c = await ensureCanvas();
       const context = await c.getAxContext({ consumer: 'mcp' });
+      const text = `Current PMX Canvas context:\n\n${JSON.stringify(context, null, 2)}`;
+      await recordContextRead(c, 'mcp-prompt', 'pmx-current-context', text, {
+        boardId: context.boardId,
+        pinnedNodeIds: context.pinned.nodeIds,
+      });
       return {
         messages: [
           {
             role: 'user',
-            content: { type: 'text', text: `Current PMX Canvas context:\n\n${JSON.stringify(context, null, 2)}` },
+            content: { type: 'text', text },
           },
         ],
       };
@@ -700,19 +776,40 @@ export async function startMcpServer(): Promise<void> {
     },
     async () => {
       const c = await ensureCanvas();
-      const layout = agentSafeFullLayoutPayload(await c.getLayout());
+      const readTarget = await c.prepareContextRead();
+      const layout = agentSafeFullLayoutPayload(await c.getLayout(readTarget.boardId ?? undefined));
+      const text = JSON.stringify(layout, null, 2);
+      await recordContextRead(c, 'mcp-resource', 'canvas://layout', text, readTarget);
       return {
         contents: [
           {
             uri: 'canvas://layout',
             mimeType: 'application/json',
-            text: JSON.stringify(layout, null, 2),
+            text,
           },
         ],
       };
     },
   );
 
+  server.resource(
+    'canvas-boards',
+    'canvas://boards',
+    {
+      description:
+        'The boards in this workspace with their categories, most recently opened first, and which one the ' +
+        'human has open (activeBoardId; null = Home). Your writes go to the open board; ask the human to open another.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const c = await ensureCanvas();
+      const boards = await c.invoker().invoke('board.list', {});
+      return {
+        contents: [{ uri: 'canvas://boards', mimeType: 'application/json', text: JSON.stringify(boards, null, 2) }],
+      };
+    },
+  );
+
   server.resource(
     'canvas-summary',
     'canvas://summary',
@@ -724,12 +821,19 @@ export async function startMcpServer(): Promise<void> {
     },
     async () => {
       const c = await ensureCanvas();
+      const readTarget = await c.prepareContextRead();
+      const text = JSON.stringify(
+        buildSummaryFromLayout(await c.getLayout(readTarget.boardId ?? undefined), readTarget.pinnedNodeIds),
+        null,
+        2,
+      );
+      await recordContextRead(c, 'mcp-resource', 'canvas://summary', text, readTarget);
       return {
         contents: [
           {
             uri: 'canvas://summary',
             mimeType: 'application/json',
-            text: JSON.stringify(buildSummaryFromLayout(await c.getLayout(), await c.getPinnedNodeIds()), null, 2),
+            text,
           },
         ],
       };
@@ -750,19 +854,22 @@ export async function startMcpServer(): Promise<void> {
     },
     async () => {
       const c = await ensureCanvas();
-      const layout = await c.getLayout();
+      const readTarget = await c.prepareContextRead();
+      const layout = await c.getLayout(readTarget.boardId ?? undefined);
       const spatial = buildSpatialContext(
         layout.nodes,
         layout.edges,
-        new Set(await c.getPinnedNodeIds()),
+        new Set(readTarget.pinnedNodeIds),
         layout.annotations ?? [],
       );
+      const text = JSON.stringify(spatial, null, 2);
+      await recordContextRead(c, 'mcp-resource', 'canvas://spatial-context', text, readTarget);
       return {
         contents: [
           {
             uri: 'canvas://spatial-context',
             mimeType: 'application/json',
-            text: JSON.stringify(spatial, null, 2),
+            text,
           },
         ],
       };
@@ -898,10 +1005,10 @@ export async function startMcpServer(): Promise<void> {
   const shutdown = (): void => {
     try {
       stopCanvasServer();
-    } catch {
-      // Exit regardless — a failed cleanup must not resurrect the orphan.
+      process.exit(0);
+    } catch (error) {
+      console.error('Shutdown refused: canvas changes could not be saved. Fix persistence and retry shutdown.', error);
     }
-    process.exit(0);
   };
   server.server.onclose = shutdown;
   process.stdin.on('end', shutdown);