pmx-canvas 0.6.4 → 0.7.0

package/src/server/index.ts

@@ -1,4 +1,6 @@
 import { EventEmitter } from 'node:events';
+import { derivedTour, type Tour } from '../shared/tour.js';
+export type { Tour, TourStop } from '../shared/tour.js';
 import { agentPresence } from './agent-presence.js';
 import { checkFenceTarget, type FenceTarget } from './scope-fence.js';
 import type { AgentPhase, AgentPresence, AgentPresenceSnapshot } from '../shared/agent-presence.js';
@@ -35,7 +37,11 @@ import type {
   PmxAxWorkItem,
   PmxAxWorkItemStatus,
 } from './ax-state.js';
-import type { AxTimelineQuery } from './canvas-db.js';
+import type { AxTimelineQuery, CanvasBoard } from './canvas-db.js';
+import type { Attachment, DocumentImport, ImportSection } from './document-import.js';
+import { workbenchToken } from './workbench-auth.js';
+import type { BackupFile, BackupStatus } from './backup.js';
+import type { ExportManifest } from './board-export.js';
 import { onFileNodeChanged } from './file-watcher.js';
 import { findOpenCanvasPosition, computeGroupBounds } from './placement.js';
 import { searchNodes, buildSpatialContext } from './spatial-analysis.js';
@@ -547,6 +553,16 @@ export class PmxCanvas extends EventEmitter {
     );
   }
 
+  getTour(): Tour {
+    return canvasState.getTour() ?? derivedTour(canvasState.getLayout().nodes);
+  }
+
+  setTour(tour: Tour | null): void {
+    assertInsideFence('tour.set', { boardWide: true });
+    canvasState.setTour(tour);
+    emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+  }
+
   clear(): void {
     assertInsideFence('canvas.clear', { boardWide: true });
     for (const node of canvasState.getLayout().nodes) {
@@ -588,7 +604,7 @@ export class PmxCanvas extends EventEmitter {
     return canvasState.getAxState();
   }
 
-  getAxContext(options?: { consumer?: string }): PmxAxContext {
+  getAxContext(options?: { consumer?: string }): PmxAxContext & { boardId: string | null } {
     return buildCanvasAxContext(options?.consumer);
   }
 
@@ -670,6 +686,218 @@ export class PmxCanvas extends EventEmitter {
     return canvasState.getAxTimeline(query);
   }
 
+  // ── Boards (plan 012) ─────────────────────────────────────────
+  // The SDK is the embedding host, so it may open and delete boards like the
+  // human's workbench. SDK writes made while no board is open (Home) land on a
+  // new board; open one first to write to an existing board.
+
+  listBoards(): { activeBoardId: string | null; boards: CanvasBoard[] } {
+    return { activeBoardId: canvasState.activeBoardId, boards: canvasState.listBoards() };
+  }
+
+  listImports(boardId?: string): DocumentImport[] {
+    return canvasState.listDocumentImports(boardId);
+  }
+  readImport(
+    id: string,
+  ): { import: DocumentImport; attachment: Attachment; downloadPath: string; bytes?: Uint8Array } | null {
+    const job = canvasState.getDocumentImport(id);
+    if (!job) return null;
+    const attachment = canvasState.getAttachment(job.attachmentId);
+    if (!attachment) return null;
+    const bytes =
+      attachment.size <= 2 * 1024 * 1024 ? (canvasState.readAttachmentBytes(attachment.id) ?? undefined) : undefined;
+    return {
+      import: job,
+      attachment,
+      downloadPath: `/api/canvas/attachments/${attachment.id}/bytes`,
+      ...(bytes ? { bytes } : {}),
+    };
+  }
+  async submitImport(
+    id: string,
+    sections: ImportSection[],
+    agentDescription: string,
+    warnings?: string[],
+  ): Promise<DocumentImport> {
+    const result = (await executeOperation(
+      'import.submit',
+      { id, sections, agentDescription, warnings },
+      { source: 'sdk' },
+    )) as { import: DocumentImport };
+    return result.import;
+  }
+  async markImportUnavailable(id: string, reason: string): Promise<DocumentImport> {
+    const result = (await executeOperation('import.unavailable', { id, reason }, { source: 'sdk' })) as {
+      import: DocumentImport;
+    };
+    return result.import;
+  }
+
+  attachDocument(input: { boardId: string; name: string; mime?: string; bytes: Uint8Array; x?: number; y?: number }): {
+    attachment: Attachment;
+    import: DocumentImport;
+    nodeId: string;
+  } {
+    if (canvasState.activeBoardId !== input.boardId) throw new Error('The captured target board is not active.');
+    assertInsideFence('node.add', createTarget(input));
+    const attachment = canvasState.storeAttachment({ ...input, mime: input.mime ?? 'application/octet-stream' });
+    if (!attachment) throw new Error('Board not found.');
+    const { id: nodeId, node } = addCanvasNode({
+      type: 'file',
+      title: input.name,
+      data: { attachmentId: attachment.id, mime: attachment.mime, size: attachment.size },
+      x: input.x,
+      y: input.y,
+      defaultWidth: 440,
+      defaultHeight: 360,
+      fileMode: 'auto',
+    });
+    const job = canvasState.createDocumentImport(attachment.id, { x: node.position.x, y: node.position.y + 400 });
+    if (!job) throw new Error('Could not create import.');
+    emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    return {
+      attachment,
+      import: job,
+      nodeId,
+    };
+  }
+
+  async requestImport(id: string, consent: true, trustedHumanToken: string): Promise<DocumentImport> {
+    if (trustedHumanToken !== workbenchToken) throw new Error('A trusted human token is required.');
+    const result = (await executeOperation(
+      'import.request',
+      { id, consent },
+      { source: 'sdk', fromWorkbench: true, humanAuthor: true },
+    )) as { import: DocumentImport };
+    return result.import;
+  }
+
+  async cancelImport(id: string, trustedHumanToken: string): Promise<DocumentImport> {
+    if (trustedHumanToken !== workbenchToken) throw new Error('A trusted human token is required.');
+    const result = (await executeOperation(
+      'import.cancel',
+      { id },
+      { source: 'sdk', fromWorkbench: true, humanAuthor: true },
+    )) as { import: DocumentImport };
+    return result.import;
+  }
+
+  async commitImport(id: string, trustedHumanToken: string): Promise<{ import: DocumentImport; nodeIds: string[] }> {
+    if (trustedHumanToken !== workbenchToken) throw new Error('A trusted human token is required.');
+    return (await executeOperation(
+      'import.commit',
+      { id },
+      { source: 'sdk', fromWorkbench: true, humanAuthor: true },
+    )) as { import: DocumentImport; nodeIds: string[] };
+  }
+
+  async createBoard(name: string, category?: string): Promise<CanvasBoard> {
+    const result = (await executeOperation(
+      'board.create',
+      { name, ...(category ? { category } : {}) },
+      { source: 'sdk' },
+    )) as {
+      board: CanvasBoard;
+    };
+    return result.board;
+  }
+
+  /** Rename a board and/or file it under a category (`category: null` removes it). */
+  async updateBoard(id: string, patch: { name?: string; category?: string | null }): Promise<void> {
+    await executeOperation('board.update', { id, ...patch }, { source: 'sdk' });
+  }
+
+  async setBoardReadme(id: string, readmeNodeId: string | null): Promise<void> {
+    await executeOperation('board.update', { id, readmeNodeId }, { source: 'sdk' });
+  }
+
+  async createBoardFrom(input: {
+    sourceBoardId: string;
+    name: string;
+    category?: string;
+    nodeIds?: string[];
+    includeReadme?: boolean;
+    includeStructure?: boolean;
+    preview?: boolean;
+  }): Promise<Record<string, unknown>> {
+    return (await executeOperation('board.create-from', input, { source: 'sdk' })) as Record<string, unknown>;
+  }
+
+  async searchLibrary(query: string, limit?: number): Promise<Record<string, unknown>> {
+    return (await executeOperation('search', { q: query, scope: 'library', limit }, { source: 'sdk' })) as Record<
+      string,
+      unknown
+    >;
+  }
+
+  /** Budgeted cross-board brief. Budget is measured in UTF-16 characters. */
+  async getContextBrief(
+    options: { consumer?: string; since?: number; budget?: number } = {},
+  ): Promise<Record<string, unknown>> {
+    return (await executeOperation('context.get', options, { source: 'sdk' })) as Record<string, unknown>;
+  }
+
+  /** Open a board, or Home with null. */
+  async openBoard(id: string | null): Promise<void> {
+    await executeOperation(
+      'board.open',
+      { id },
+      { source: 'sdk', fromWorkbench: true, humanAuthor: true, suppressAutoGhost: true },
+    );
+  }
+
+  async deleteBoard(id: string): Promise<void> {
+    await executeOperation(
+      'board.delete',
+      { id },
+      { source: 'sdk', fromWorkbench: true, humanAuthor: true, suppressAutoGhost: true },
+    );
+  }
+
+  // ── Static export (plan 013) ─────────────────────────────────
+
+  /** Write a self-contained HTML file of a board (default: the open board). */
+  async exportBoard(
+    options: { board?: string; includeFiles?: boolean; includeDerivedText?: boolean } = {},
+  ): Promise<{ path: string; url: string; bytes: number; manifest: ExportManifest }> {
+    return (await executeOperation('export.run', options, { source: 'sdk' })) as {
+      path: string;
+      url: string;
+      bytes: number;
+      manifest: ExportManifest;
+    };
+  }
+
+  // ── Library backup (plan 012) ─────────────────────────────────
+
+  async getBackupStatus(): Promise<BackupStatus> {
+    return (await executeOperation('backup.status', {}, { source: 'sdk' })) as BackupStatus;
+  }
+
+  /** Back up every board now; `to` and `keep` default to the configured folder and count. */
+  async backup(options: { to?: string; keep?: number } = {}): Promise<{ backup: BackupFile; removed: string[] }> {
+    return (await executeOperation('backup.run', options, { source: 'sdk' })) as {
+      backup: BackupFile;
+      removed: string[];
+    };
+  }
+
+  /** Back up on a schedule run by the server; `every: 'off'` stops it. */
+  async setBackupSchedule(options: { every: string; to?: string; keep?: number }): Promise<BackupStatus> {
+    return (await executeOperation('backup.schedule', options, { source: 'sdk' })) as BackupStatus;
+  }
+
+  /** Replace every board with a backup file; the current file is kept as `canvas.db.before-restore`. */
+  async restoreBackup(file: string): Promise<void> {
+    await executeOperation('backup.restore', { file }, { source: 'sdk' });
+  }
+
+  /** The context read log: which canvas context each agent read and which pinned nodes reached it. */
+  getContextReads(limit?: number): ReturnType<typeof canvasState.getContextReads> {
+    return canvasState.getContextReads(limit);
+  }
+
   listWorkItems(): PmxAxWorkItem[] {
     return canvasState.getWorkItems();
   }
@@ -1002,12 +1230,19 @@ export class PmxCanvas extends EventEmitter {
     return result;
   }
 
-  getLayout(): CanvasLayout {
+  getLayout(options?: { board?: string }): CanvasLayout {
+    if (options?.board) {
+      const read = canvasState.readBoard(options.board);
+      if (!read) throw new Error(`Board "${options.board}" not found.`);
+      return read.layout;
+    }
     return canvasState.getLayout();
   }
 
-  getNode(id: string): SdkCanvasNode | undefined {
-    const node = canvasState.getNode(id);
+  getNode(id: string, options?: { board?: string }): SdkCanvasNode | undefined {
+    const node = options?.board
+      ? this.getLayout(options).nodes.find((candidate) => candidate.id === id)
+      : canvasState.getNode(id);
     return node ? toSdkNode(node) : undefined;
   }
 
@@ -1423,6 +1658,9 @@ export {
   screenshotCanvasAutomationWebView,
 } from './server.js';
 export { canvasState } from './canvas-state.js';
+export type { CanvasBoard } from './canvas-db.js';
+export type { BackupFile, BackupStatus } from './backup.js';
+export type { ExportManifest } from './board-export.js';
 export type {
   CanvasAnnotation,
   CanvasSnapshot,

package/src/server/mutation-history.ts

@@ -13,6 +13,7 @@
  */
 
 import type { CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
+import { currentActor as getActor, setCurrentActor } from './attribution.js';
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -116,10 +117,13 @@ class MutationHistory {
   record(entry: Omit<MutationEntry, 'id' | 'timestamp' | 'actor'> & { actor?: MutationActor }): void {
     if (this._replaying) return;
 
+    const attribution = getActor();
+    const actor = attribution.actor === 'human' ? 'human' : 'agent';
+    const writer = actor === 'agent' ? (attribution.agentId ?? attribution.source) : undefined;
     const full: MutationEntry = {
       ...entry,
-      actor: entry.actor ?? currentActor ?? 'agent',
-      ...((entry.writer ?? currentWriter) ? { writer: entry.writer ?? currentWriter ?? undefined } : {}),
+      actor: entry.actor ?? actor,
+      ...((entry.writer ?? writer) ? { writer: entry.writer ?? writer } : {}),
       id: `mut-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
       timestamp: new Date().toISOString(),
     };
@@ -415,16 +419,9 @@ export function formatDiff(diff: SnapshotDiffResult): string {
 
 export const mutationHistory = new MutationHistory();
 
-/**
- * Actor context for entries recorded while an operation runs. executeOperation
- * sets it from the workbench marker around each op; writes outside the
- * registry (the sync SDK) default to `agent`. Only the undo affordance reads
- * it, so an async op interleaving with another request costs at most a
- * mislabelled row — never a wrong undo.
- */
-let currentActor: MutationActor | null = null;
-let currentWriter: string | null = null;
+/** Direct callers share the same async-local attribution as node mutations. */
 export function setMutationActor(actor: MutationActor | null, writer: string | null = null): void {
-  currentActor = actor;
-  currentWriter = actor === 'agent' ? writer : null;
+  setCurrentActor(
+    actor ? { actor, source: actor === 'human' ? 'browser' : 'sdk', ...(writer ? { agentId: writer } : {}) } : null,
+  );
 }

package/src/server/operations/composites.ts

@@ -123,6 +123,13 @@ const GATE_OPS: Array<{ op: string; kind: string; action: string }> = GATE_KINDS
 );
 
 export const compositeToolDefinitions: CompositeToolDefinition[] = [
+  {
+    toolName: 'canvas_import',
+    description:
+      'Agent-assisted document ingestion. List jobs, read attachment metadata/download bytes, submit bounded Markdown extraction, or report unavailable. Request, commit, and cancel are human-only HTTP actions.',
+    actionSummary: 'list | read | submit | unavailable',
+    actions: { list: 'import.list', read: 'import.read', submit: 'import.submit', unavailable: 'import.unavailable' },
+  },
   {
     // v0.4.0: the long-deferred snapshot composite (plan-006 #7). The name was
     // held by the legacy save-snapshot standalone through v0.3.x; listing the
@@ -141,6 +148,19 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
       diff: 'snapshot.diff',
     },
   },
+  {
+    toolName: 'canvas_board',
+    description:
+      'Boards in this workspace — the library of the human\'s and your working memory, filed in categories on Home. Your writes always go to the board the human has open (activeBoardId); on Home (no board open) your first write opens their most recent board, or a new one when there are none. Action "list" returns every board (with its category), most recently opened first; "get" reads one (default: the open board); "create" makes a new empty board WITHOUT opening it (optional category); "update" renames a board, files it under a category (category "" removes it), or designates its README via readmeNodeId. As part of normal board authoring, read the board metadata; if readmeNodeId is null, choose or create a concise markdown introduction explaining its purpose and key context, then designate that node with "update". Preserve an existing README unless the human asks to change it; humans can override the designation manually. Only the human opens, switches or deletes boards — if you need another board, ask them in the chat to open it.',
+    actionSummary: 'list | get | create | create-from | update',
+    actions: {
+      list: 'board.list',
+      get: 'board.get',
+      create: 'board.create',
+      'create-from': 'board.create-from',
+      update: 'board.update',
+    },
+  },
   {
     toolName: 'canvas_node',
     description:
@@ -203,8 +223,10 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
     toolName: 'canvas_view',
     description:
       'Canvas viewport and layout control. Action "arrange" auto-lays-out nodes (grid/columns/etc.); "focus" pans/zooms the viewport to a node; "fit" zooms to fit all nodes in view; "clear" removes every node and edge from the canvas; "remove-annotation" deletes a human-drawn annotation by id.',
-    actionSummary: 'arrange | focus | fit | clear | remove-annotation',
+    actionSummary: 'arrange | focus | fit | clear | remove-annotation | get-tour | set-tour',
     actions: {
+      'get-tour': 'tour.get',
+      'set-tour': 'tour.set',
       arrange: 'arrange',
       focus: 'node.focus',
       fit: 'view.fit',
@@ -215,9 +237,10 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_query',
     description:
-      'Read the board cheapest-first. Action "search" finds nodes by title/content keywords (prefer this before reading the full layout); "layout" returns the full node/edge layout; "validate" checks the board for node collisions, group-containment issues, and missing edge endpoints. Use search to locate, then layout or canvas_node get for detail.',
-    actionSummary: 'search | layout | validate',
+      'Read the board cheapest-first. Action "context" returns a budgeted cross-board brief with a durable consumer cursor (budget is UTF-16 characters); "search" finds nodes by title/content keywords; "layout" returns the full layout; "validate" checks geometry and endpoints.',
+    actionSummary: 'context | search | layout | validate',
     actions: {
+      context: 'context.get',
       search: 'search',
       layout: 'layout.get',
       validate: 'validate.get',
@@ -299,13 +322,14 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_ax_timeline',
     description:
-      'Read or write the bounded PMX AX timeline. Action "read" returns recent agent-events, evidence, and steering messages plus counts (limit); "record-event" records a normalized agent-event (kind prompt|assistant-message|tool-start|tool-result|failure|approval|steering, summary, detail, data); "add-evidence" records an evidence item (kind logs|tool-result|screenshot|file|diff|test-output, title, body, ref); "send-steering" records a steering message (message). Timeline rows persist for diagnostics/continuity but are not restored by snapshots; exposed via canvas://ax-timeline.',
-    actionSummary: 'read | record-event | add-evidence | send-steering',
+      'Read or write the bounded PMX AX timeline. Action "read" returns recent agent-events, evidence, and steering messages plus counts (limit); "record-event" records a normalized agent-event (kind prompt|assistant-message|tool-start|tool-result|failure|approval|steering, summary, detail, data); "add-evidence" records an evidence item (kind logs|tool-result|screenshot|file|diff|test-output, title, body, ref); "send-steering" records a steering message (message); "reads" returns the context read log — which canvas context each agent read and which pinned nodes reached it — with a per-consumer summary (limit). Timeline rows persist for diagnostics/continuity but are not restored by snapshots; exposed via canvas://ax-timeline.',
+    actionSummary: 'read | record-event | add-evidence | send-steering | reads',
     actions: {
       read: 'ax.timeline.get',
       'record-event': 'ax.event.record',
       'add-evidence': 'ax.evidence.add',
       'send-steering': 'ax.steer',
+      reads: 'ax.reads.list',
     },
   },
   {

package/src/server/operations/http.ts

@@ -9,6 +9,7 @@
 import { executeOperation, listOperations } from './registry.js';
 import { SOURCE_LABEL_RE } from '../agent-presence.js';
 import { OperationError } from './types.js';
+import { isWorkbenchToken } from '../workbench-auth.js';
 
 function responseJson(data: unknown, status = 200): Response {
   return Response.json(data, {
@@ -88,15 +89,20 @@ export async function dispatchOperationRoute(req: Request, url: URL): Promise<Re
       // The workbench marks its own HTTP calls: a human dragging/editing in
       // the browser is not agent activity, so it never synthesizes an
       // auto-ghost. Everything else (CLI, scripts, adapters) counts as agent.
-      const fromWorkbench = req.headers.get('x-pmx-workbench') === '1';
+      const workbenchMarked = req.headers.get('x-pmx-workbench') === '1';
+      const humanAuthor = isWorkbenchToken(req.headers.get('x-pmx-workbench-token'));
       // Presence writer label: adapters/CLI may identify themselves; plain
       // HTTP callers read as 'api'.
       const sourceHeader = req.headers.get('x-pmx-source');
       const source = sourceHeader && SOURCE_LABEL_RE.test(sourceHeader) ? sourceHeader : 'api';
       const result = await executeOperation(op.name, input, {
-        suppressAutoGhost: fromWorkbench,
-        fromWorkbench,
+        // The legacy marker remains a UI-policy signal (ghost suppression).
+        // Only the unguessable boot token classifies authorship as human.
+        suppressAutoGhost: workbenchMarked,
+        fromWorkbench: workbenchMarked,
+        humanAuthor,
         source,
+        proxiedRead: req.headers.get('x-pmx-proxied-read') === '1',
       });
       return responseJson(result, route.status ? route.status(result) : 200);
     } catch (error) {

package/src/server/operations/index.ts

@@ -11,6 +11,9 @@ import { queryOperations } from './ops/query.js';
 import { validateOperations } from './ops/validate.js';
 import { annotationOperations } from './ops/annotation.js';
 import { snapshotOperations } from './ops/snapshots.js';
+import { boardOperations } from './ops/boards.js';
+import { backupOperations } from './ops/backup.js';
+import { exportOperations } from './ops/export.js';
 import { jsonRenderOperations } from './ops/json-render.js';
 import { axStateOperations } from './ops/ax-state.js';
 import { axWorkOperations } from './ops/ax-work.js';
@@ -25,6 +28,7 @@ import { axReadOperations } from './ops/ax-read.js';
 import { axPresenceOperations } from './ops/ax-presence.js';
 import { humanPresenceOperations } from './ops/human-presence.js';
 import { canvasWireOperations } from './ops/canvas-wire.js';
+import { importOperations } from './ops/imports.js';
 
 for (const op of [
   ...nodeOperations,
@@ -35,6 +39,9 @@ for (const op of [
   ...validateOperations,
   ...annotationOperations,
   ...snapshotOperations,
+  ...boardOperations,
+  ...backupOperations,
+  ...exportOperations,
   ...jsonRenderOperations,
   ...axStateOperations,
   ...axWorkOperations,
@@ -49,6 +56,7 @@ for (const op of [
   ...axPresenceOperations,
   ...humanPresenceOperations,
   ...canvasWireOperations,
+  ...importOperations,
 ]) {
   registerOperation(op);
 }

package/src/server/operations/invoker.ts

@@ -29,14 +29,19 @@ function defaultPresenceSource(name: string, input: Record<string, unknown>, sou
 /** Runs operations in-process against the shared canvasState singleton. */
 export class LocalOperationInvoker implements OperationInvoker {
   private readonly source: string;
+  private readonly proxiedRead: boolean;
 
   /** `source` labels this caller's agent presence ('mcp', 'sdk', …). */
   constructor(source = 'api') {
     this.source = agentSourceLabel(source);
+    this.proxiedRead = source === 'mcp';
   }
 
   async invoke(name: string, input: Record<string, unknown>): Promise<unknown> {
-    return await executeOperation(name, defaultPresenceSource(name, input, this.source), { source: this.source });
+    return await executeOperation(name, defaultPresenceSource(name, input, this.source), {
+      source: this.source,
+      proxiedRead: this.proxiedRead,
+    });
   }
 }
 
@@ -48,11 +53,13 @@ function toOperationErrorStatus(status: number): OperationErrorStatus {
 export class HttpOperationInvoker implements OperationInvoker {
   private readonly baseUrl: string;
   private readonly source: string;
+  private readonly proxiedRead: boolean;
 
   /** `source` labels this caller's agent presence on the server ('cli', 'mcp', …). */
   constructor(baseUrl: string, source = 'api') {
     this.baseUrl = baseUrl.replace(/\/$/, '');
     this.source = agentSourceLabel(source);
+    this.proxiedRead = source === 'mcp';
   }
 
   async invoke(name: string, rawInput: Record<string, unknown>): Promise<unknown> {
@@ -79,7 +86,11 @@ export class HttpOperationInvoker implements OperationInvoker {
     }
 
     let url = `${this.baseUrl}${path}`;
-    const init: RequestInit = { method: route.method, headers: { 'x-pmx-source': this.source } };
+    const proxyHeaders: Record<string, string> = this.proxiedRead ? { 'x-pmx-proxied-read': '1' } : {};
+    const init: RequestInit = {
+      method: route.method,
+      headers: { 'x-pmx-source': this.source, ...proxyHeaders },
+    };
     if (route.method === 'GET' || route.method === 'DELETE') {
       const params = new URLSearchParams();
       for (const [key, value] of Object.entries(rest)) {
@@ -88,7 +99,7 @@ export class HttpOperationInvoker implements OperationInvoker {
       const query = params.toString();
       if (query) url += `?${query}`;
     } else {
-      init.headers = { 'Content-Type': 'application/json', 'x-pmx-source': this.source };
+      init.headers = { 'Content-Type': 'application/json', 'x-pmx-source': this.source, ...proxyHeaders };
       init.body = JSON.stringify(rest);
     }
 

package/src/server/operations/mcp.ts

@@ -10,12 +10,59 @@
 import { z, type ZodRawShape, type ZodTypeAny } from 'zod';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { getOperation, listOperations } from './registry.js';
-import type { OperationInvoker } from './invoker.js';
+import { agentSourceLabel, type OperationInvoker } from './invoker.js';
 import { OperationError, type Operation, type OperationMcpToolHost } from './types.js';
+import { CONTEXT_READ_OPS, contextReadFromPayload, type ContextReadInput } from '../context-reads.js';
 import { compositeFoldedOpNames, compositeToolDefinitions, type CompositeToolDefinition } from './composites.js';
 
 export interface OperationToolHost extends OperationMcpToolHost {
   invoker(): OperationInvoker;
+  prepareContextRead(board?: string): Promise<{ boardId: string | null; pinnedNodeIds: string[] }>;
+  recordContextRead(read: ContextReadInput): Promise<void>;
+}
+
+async function invokeMcpOperation(
+  host: OperationToolHost,
+  op: Operation,
+  opInput: Record<string, unknown>,
+  formatInput: Record<string, unknown>,
+  consumer: string | null,
+) {
+  const board = typeof opInput.board === 'string' && opInput.board.trim() ? opInput.board.trim() : undefined;
+  const readTarget = CONTEXT_READ_OPS.has(op.name) ? await host.prepareContextRead(board) : null;
+  if (readTarget?.boardId && 'board' in op.inputShape) {
+    opInput = { ...opInput, board: readTarget.boardId };
+    formatInput = { ...formatInput, board: readTarget.boardId };
+  }
+  const result = await host.invoker().invoke(op.name, opInput);
+  const formatted = op.mcp?.formatResult
+    ? await op.mcp.formatResult(result, formatInput, host)
+    : { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+  if (readTarget) {
+    const text = formatted.content
+      .filter((item): item is Extract<(typeof formatted.content)[number], { type: 'text' }> => item.type === 'text')
+      .map((item) => item.text)
+      .join('');
+    try {
+      await host.recordContextRead(
+        contextReadFromPayload(
+          {
+            channel: 'operation',
+            resource: op.name,
+            source: agentSourceLabel('mcp'),
+            consumer,
+            agentId: null,
+            pinnedNodeIds: readTarget.pinnedNodeIds,
+            boardId: readTarget.boardId,
+          },
+          text,
+        ),
+      );
+    } catch (error) {
+      console.error('[pmx-canvas mcp] recording a context read failed:', error);
+    }
+  }
+  return formatted;
 }
 
 export function registerOperationTools(server: McpServer, getHost: () => Promise<OperationToolHost>): void {
@@ -43,11 +90,7 @@ export function registerOperationTools(server: McpServer, getHost: () => Promise
         try {
           const host = await getHost();
           const opInput = tool.buildInput ? tool.buildInput(input) : input;
-          const result = await host.invoker().invoke(op.name, opInput);
-          if (tool.formatResult) {
-            return await tool.formatResult(result, input, host);
-          }
-          return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+          return await invokeMcpOperation(host, op, opInput, input, server.server.getClientVersion()?.name ?? null);
         } catch (error) {
           return {
             content: [{ type: 'text' as const, text: error instanceof Error ? error.message : String(error) }],
@@ -261,11 +304,7 @@ export function registerCompositeTools(
             );
           }
           const opInput = op.mcp?.buildInput ? op.mcp.buildInput(rest) : rest;
-          const result = await host.invoker().invoke(opName, opInput);
-          if (op.mcp?.formatResult) {
-            return await op.mcp.formatResult(result, rest, host);
-          }
-          return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+          return await invokeMcpOperation(host, op, opInput, rest, server.server.getClientVersion()?.name ?? null);
         } catch (error) {
           return {
             content: [{ type: 'text' as const, text: error instanceof Error ? error.message : String(error) }],