pmx-canvas 0.6.5 → 0.7.1

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

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' };
+}