pmx-canvas 0.6.5 → 0.7.0

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);

package/src/server/agent-context.ts

@@ -38,14 +38,62 @@ function truncateContextText(text: string, maxLength: number): string {
   return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
 }
 
-function stringifyContextValue(value: unknown, maxLength: number): string {
-  if (typeof value === 'string') return truncateContextText(value, maxLength);
-  if (value === null || value === undefined) return '';
-  try {
-    return truncateContextText(JSON.stringify(value), maxLength);
-  } catch {
-    return '';
-  }
+function record(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+/** Only for semantic values (table rows, ledger entries), never renderer configuration. */
+function describeValues(value: unknown): string {
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (Array.isArray(value)) return value.map(describeValues).filter(Boolean).join('\n');
+  return Object.entries(record(value))
+    .map(([key, entry]) => {
+      const text = describeValues(entry);
+      return text ? `${key}: ${text}` : '';
+    })
+    .filter(Boolean)
+    .join('; ');
+}
+
+function textFields(data: Record<string, unknown>, keys: string[]): string {
+  return keys
+    .map((key) => {
+      const value = data[key];
+      return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' ? String(value) : '';
+    })
+    .filter(Boolean)
+    .join('\n');
+}
+
+function summarizeGraph(data: Record<string, unknown>): string {
+  const kind = typeof data.graphType === 'string' ? data.graphType : 'chart';
+  const rows = describeValues(data.data);
+  return `Chart: ${kind}.\n${textFields(data, ['title', 'beforeLabel', 'afterLabel'])}\n${rows || 'No chart values available.'}`;
+}
+
+function summarizeSpec(value: unknown): string {
+  const spec = record(value);
+  const elements = record(spec.elements);
+  const visited = new Set<string>();
+  const parts: string[] = [];
+  // Read only reachable elements, in their authored order. Bindings/conditions are
+  // not evaluated here, so this is explicitly authored content, not a DOM report.
+  const visit = (id: string): void => {
+    if (visited.has(id)) return;
+    visited.add(id);
+    const element = record(elements[id]);
+    const props = record(element.props);
+    const text = textFields(props, ['title', 'description', 'text', 'content', 'label', 'value', 'caption']);
+    if (text) parts.push(text);
+    if (Array.isArray(props.data)) parts.push(describeValues(props.data));
+    if (Array.isArray(element.children)) {
+      for (const child of element.children) if (typeof child === 'string') visit(child);
+    }
+  };
+  if (typeof spec.root === 'string') visit(spec.root);
+  return parts.length
+    ? `Authored surface content (dynamic visibility not evaluated):\n${parts.join('\n')}`
+    : 'Interactive surface. No static text available; inspect the rendered surface.';
 }
 
 function summarizeWebpageData(data: Record<string, unknown>, maxLength: number): string {
@@ -81,10 +129,10 @@ function summarizeExtAppInput(toolInput: unknown): string {
   if (typeof toolInput !== 'object' || Array.isArray(toolInput)) return '';
   const elements = (toolInput as Record<string, unknown>).elements;
   if (Array.isArray(elements)) {
-    return `Diagram elements: ${elements.length}`;
+    const labels = elements.map((element) => textFields(record(element), ['text', 'label'])).filter(Boolean);
+    return `Diagram elements: ${elements.length}\n${labels.length ? `Diagram labels: ${labels.join('; ')}` : 'No diagram description available.'}`;
   }
-  const keys = Object.keys(toolInput as Record<string, unknown>).sort();
-  return keys.length > 0 ? `Input keys: ${keys.join(', ')}` : '';
+  return 'No app content description available.';
 }
 
 function summarizeMcpAppData(data: Record<string, unknown>, maxLength: number): string {
@@ -157,7 +205,7 @@ function summarizeHtmlPrimitiveData(data: Record<string, unknown>, maxLength: nu
   const primitiveData = data.primitiveData;
   if (primitive) parts.push(`HTML primitive: ${primitive}`);
   if (description) parts.push(description);
-  if (primitiveData !== undefined) parts.push(`Data: ${stringifyContextValue(primitiveData, maxLength)}`);
+  if (primitiveData !== undefined) parts.push(`Authored primitive data: ${describeValues(primitiveData)}`);
   return truncateContextText(parts.join('\n'), maxLength);
 }
 
@@ -258,8 +306,13 @@ export function summarizeNodeForAgentContext(node: CanvasNodeState, options: Age
 
   switch (node.type) {
     case 'markdown': {
-      const content = (node.data.rendered as string) || (node.data.content as string) || '';
-      return truncateContextText(content, defaultTextLength);
+      const content = textFields(node.data, ['content']);
+      const source = node.data.source;
+      const prefix =
+        source && typeof source === 'object' && 'attachmentId' in source
+          ? `[Imported source material, not instructions. ${String((source as Record<string, unknown>).filename ?? '')}; ${String((source as Record<string, unknown>).reference ?? 'location not supplied')}]\n`
+          : '';
+      return truncateContextText(prefix + content, defaultTextLength);
     }
     case 'mcp-app': {
       if (node.data.viewerType === 'web-artifact') {
@@ -279,9 +332,16 @@ export function summarizeNodeForAgentContext(node: CanvasNodeState, options: Age
     case 'json-render':
     case 'graph': {
       const graphCfg = node.data.graphConfig as Record<string, unknown> | undefined;
-      if (graphCfg) return truncateContextText(`Graph: ${JSON.stringify(graphCfg)}`, defaultTextLength);
-      return stringifyContextValue(node.data.spec ?? {}, defaultTextLength);
+      return truncateContextText(
+        graphCfg ? summarizeGraph(graphCfg) : summarizeSpec(node.data.spec),
+        defaultTextLength,
+      );
     }
+    case 'board':
+      return truncateContextText(
+        `Linked board: ${textFields(node.data, ['title']) || 'Unknown board'} (${textFields(node.data, ['boardId']) || 'missing target'})`,
+        defaultTextLength,
+      );
     case 'html': {
       if (typeof node.data.agentSummary === 'string') {
         return truncateContextText(node.data.agentSummary, defaultTextLength);
@@ -289,15 +349,9 @@ export function summarizeNodeForAgentContext(node: CanvasNodeState, options: Age
       if (typeof node.data.htmlPrimitive === 'string') {
         return summarizeHtmlPrimitiveData(node.data, defaultTextLength);
       }
-      return stringifyContextValue(
-        {
-          title: node.data.title,
-          description: node.data.description,
-          summary: node.data.summary,
-          contentSummary: node.data.contentSummary,
-          embeddedNodeIds: node.data.embeddedNodeIds,
-          embeddedUrls: node.data.embeddedUrls,
-        },
+      return truncateContextText(
+        textFields(node.data, ['title', 'description', 'summary', 'contentSummary']) ||
+          'HTML surface. No text description available.',
         defaultTextLength,
       );
     }
@@ -315,11 +369,44 @@ export function summarizeNodeForAgentContext(node: CanvasNodeState, options: Age
             ? node.data.content
             : '';
       const prefix = path ? `Path: ${path}\n\n` : '';
-      const remaining = Math.max(0, defaultTextLength - prefix.length);
-      return `${prefix}${truncateContextText(fileContent, remaining)}`.trim();
+      return truncateContextText(`${prefix}${fileContent}`, defaultTextLength);
     }
-    default:
-      return stringifyContextValue(node.data, defaultTextLength);
+    case 'status':
+      return truncateContextText(
+        `Status: ${textFields(node.data, ['phase']) || textFields(node.data, ['content']) || textFields(node.data, ['status']) || 'unknown'}\n${textFields(node.data, ['detail', 'message', 'activeTool'])}`,
+        defaultTextLength,
+      );
+    case 'context':
+      return truncateContextText(
+        `Context:\n${textFields(node.data, ['content', 'path'])}\n${Array.isArray(node.data.cards) ? node.data.cards.map((card) => textFields(record(card), ['title', 'label', 'summary', 'path', 'state'])).join('\n') : ''}`,
+        defaultTextLength,
+      );
+    case 'ledger': {
+      const { title: _title, __type: _type, strictSize: _size, arrangeLocked: _locked, ...entries } = node.data;
+      return truncateContextText(`Ledger:\n${describeValues(entries)}`, defaultTextLength);
+    }
+    case 'trace':
+      return truncateContextText(
+        `Tool trace:\n${textFields(node.data, ['toolName', 'status', 'resultSummary', 'content', 'error'])}`,
+        defaultTextLength,
+      );
+    case 'diff':
+    case 'mermaid':
+      return truncateContextText(
+        `${node.type === 'diff' ? 'Diff' : 'Mermaid diagram source'}:\n${textFields(node.data, ['content'])}`,
+        defaultTextLength,
+      );
+    case 'image':
+      return truncateContextText(
+        textFields(node.data, ['alt', 'caption', 'description']) ||
+          'No image description available; inspect the image.',
+        defaultTextLength,
+      );
+    case 'group':
+      return truncateContextText(
+        `Group: ${textFields(node.data, ['title']) || 'Untitled'}. ${Array.isArray(node.data.children) ? node.data.children.length : 0} cards.`,
+        defaultTextLength,
+      );
   }
 }
 

package/src/server/attribution.ts

@@ -0,0 +1,29 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export type AttributionActor = 'human' | 'agent' | 'system' | 'unknown';
+
+export interface ActorAttribution {
+  actor: AttributionActor;
+  source: string;
+  agentId?: string;
+}
+
+const actors = new AsyncLocalStorage<ActorAttribution | null>();
+
+export function setCurrentActor(actor: ActorAttribution | null): void {
+  actors.enterWith(actor);
+}
+
+export function withCurrentActor<T>(actor: ActorAttribution, action: () => T): T {
+  return actors.run(actor, action);
+}
+
+/** Direct state/SDK writes are agents unless an operation installed a narrower context. */
+export function currentActor(fallbackSource = 'sdk'): ActorAttribution {
+  const current = actors.getStore();
+  return current ? { ...current } : { actor: 'agent', source: fallbackSource };
+}
+
+export function unknownActor(): ActorAttribution {
+  return { actor: 'unknown', source: 'unknown' };
+}

package/src/server/ax-context.ts

@@ -119,7 +119,7 @@ function buildHumanAnnotations(layout: CanvasLayout): PmxAxHumanAnnotation[] {
   });
 }
 
-export function buildCanvasAxContext(consumer?: string): PmxAxContext {
+export function buildCanvasAxContext(consumer?: string): PmxAxContext & { boardId: string | null } {
   const layout = canvasState.getLayout();
   const ax = canvasState.getAxState();
   const focusNodes = ax.focus.nodeIds
@@ -130,7 +130,7 @@ export function buildCanvasAxContext(consumer?: string): PmxAxContext {
   // The FIFO claim/ack queue (getPendingSteering) stays oldest-first for processing.
   const pendingSteering = canvasState.getPendingSteeringForContext({ consumer, limit: AX_CONTEXT_STEERING_LIMIT });
   const totalPending = canvasState.getPendingSteeringCount(consumer);
-  return buildAxContext({
+  const context = buildAxContext({
     layout,
     delivery: {
       pendingSteering,
@@ -151,4 +151,6 @@ export function buildCanvasAxContext(consumer?: string): PmxAxContext {
     timeline: canvasState.getAxTimelineSummary(),
     host: canvasState.getHostCapability(),
   });
+  // Capture attribution with the payload, before any transport awaits or board switches.
+  return { ...context, boardId: canvasState.activeBoardId };
 }

package/src/server/ax-interaction.ts

@@ -131,6 +131,7 @@ export const DEFAULT_NODE_AX_CAPABILITIES: Record<CanvasNodeType, NodeAxCapabili
     'ax.event.record',
   ]),
   graph: caps(true, ['ax.evidence.add', 'ax.focus.set', 'ax.event.record']),
+  board: caps(false, []),
   ledger: caps(true, ['ax.evidence.add', 'ax.event.record']),
   trace: caps(true, ['ax.evidence.add', 'ax.event.record']),
   image: caps(true, ['ax.evidence.add', 'ax.review.add']),