pmx-canvas 0.6.5 → 0.7.1

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) }],

package/src/server/operations/ops/app.ts

@@ -107,6 +107,7 @@ export async function openMcpAppCore(input: OpenMcpAppCoreInput, ctx: OperationC
     throw new OperationError(`Node "${input.nodeId}" is not an external app node.`);
   }
 
+  const boardGeneration = canvasState.boardGeneration;
   const opened = await openExternalMcpApp({
     transport: input.transport,
     toolName: input.toolName,
@@ -114,6 +115,10 @@ export async function openMcpAppCore(input: OpenMcpAppCoreInput, ctx: OperationC
     ...(input.serverName ? { serverName: input.serverName } : {}),
     ...(typeof input.timeoutMs === 'number' ? { timeoutMs: input.timeoutMs } : {}),
   });
+  if (canvasState.boardGeneration !== boardGeneration) {
+    closeMcpAppSession(opened.sessionId);
+    throw new OperationError('The board changed while the MCP app was opening.', 409);
+  }
   const toolCallId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
   const previousSessionId = targetNode?.data.appSessionId;
   if (typeof previousSessionId === 'string' && previousSessionId.trim().length > 0) {

package/src/server/operations/ops/ax-read.ts

@@ -28,6 +28,7 @@ import {
 import { canvasState, type CanvasNodeState } from '../../canvas-state.js';
 import { buildCodeGraphSummary } from '../../code-graph.js';
 import { defineOperation, OperationError, type Operation, type OperationContext } from '../types.js';
+import { readTargetBoard } from './boards.js';
 import { normalizeAxNodeIds, normalizeAxSource } from './ax-shared.js';
 import { isRecord } from './nodes.js';
 
@@ -153,19 +154,22 @@ const axSurfaceSnapshotOperation = defineOperation<z.infer<typeof emptySchema>,
 
 // ── pinned-context.get ────────────────────────────────────────
 
-const pinnedContextOperation = defineOperation<z.infer<typeof emptySchema>, Record<string, unknown>>({
+const pinnedContextShape = { board: z.unknown().optional().describe('Board id to read without opening it.') };
+const pinnedContextSchema = z.looseObject(pinnedContextShape);
+const pinnedContextOperation = defineOperation<z.infer<typeof pinnedContextSchema>, Record<string, unknown>>({
   name: 'pinned-context.get',
   mutates: false,
-  input: emptySchema,
-  inputShape: emptyShape,
+  input: pinnedContextSchema,
+  inputShape: pinnedContextShape,
   http: {
     method: 'GET',
     path: '/api/canvas/pinned-context',
   },
-  handler: () => {
-    const pinnedIds = Array.from(canvasState.contextPinnedNodeIds);
+  handler: ({ board }) => {
+    const target = readTargetBoard(board);
+    const pinnedIds = Array.from(target.pinnedNodeIds);
     const nodes = pinnedIds
-      .map((id) => canvasState.getNode(id))
+      .map((id) => target.layout.nodes.find((node) => node.id === id))
       .filter((node): node is CanvasNodeState => node !== undefined);
     const preamble =
       pinnedIds.length > 0 ? buildAgentContextPreamble(nodes, { defaultTextLength: 700, webpageTextLength: 1600 }) : '';

package/src/server/operations/ops/ax-timeline.ts

@@ -51,6 +51,7 @@ import { canvasState } from '../../canvas-state.js';
 import { buildPendingAxActivity, isAxEventKind, isAxEvidenceKind } from '../../ax-state.js';
 import type { PmxAxEventKind, PmxAxEvidenceKind } from '../../ax-state.js';
 import { waitForAxCondition } from '../../ax-wait.js';
+import { CONTEXT_READ_CHANNELS } from '../../context-reads.js';
 import { defineOperation, OperationError, type Operation } from '../types.js';
 import { isRecord } from './nodes.js';
 import {
@@ -462,6 +463,78 @@ const axCommandInvokeOperation = defineOperation<z.infer<typeof axCommandInvokeS
   },
 });
 
+// ── ax.reads.list / ax.reads.record (context read instrumentation) ──
+
+const axReadsListShape = {
+  limit: z.unknown().optional().describe('Max reads to return, newest first (default 50, max 500).'),
+};
+const axReadsListSchema = z.looseObject(axReadsListShape);
+
+const axReadsListOperation = defineOperation<z.infer<typeof axReadsListSchema>, Record<string, unknown>>({
+  name: 'ax.reads.list',
+  mutates: false,
+  input: axReadsListSchema,
+  inputShape: axReadsListShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/ax/context-reads',
+  },
+  mcp: {
+    toolName: 'canvas_get_context_reads',
+    description:
+      'Read the context read log: which canvas context each agent read, and which pinned nodes were in what it received. Summary is per consumer.',
+    extraShape: {
+      limit: z.number().optional().describe('Max reads to return, newest first (default 50, max 500).'),
+    },
+    formatResult: axJsonResult,
+  },
+  handler: (input) => {
+    const limit = Number(input.limit ?? '');
+    return { ok: true, ...canvasState.getContextReads(Number.isFinite(limit) && limit > 0 ? limit : undefined) };
+  },
+});
+
+const axReadsRecordShape = {
+  channel: z.enum(CONTEXT_READ_CHANNELS).describe('How the read reached the agent.'),
+  resource: z.string().min(1).describe('Resource URI or operation name that was read.'),
+  consumer: z.string().nullable().optional().describe('Reader identity (MCP client name, adapter host).'),
+  agentId: z.string().nullable().optional().describe('Agent id when known.'),
+  source: z.string().optional().describe('Transport label (default "api").'),
+  pinnedNodeIds: z.array(z.string()).optional().describe('Pins at read time; defaults to the current pins.'),
+  deliveredNodeIds: z.array(z.string()).describe('Pinned ids present in what the agent received.'),
+  bytes: z.number().int().nonnegative().describe('Size of what the agent received.'),
+  boardId: z.string().nullable().optional().describe('Board that was read, captured before delivery.'),
+};
+const axReadsRecordSchema = z.object(axReadsRecordShape);
+
+/** For proxies (an MCP server attached to this daemon, host adapters) that record the read the agent made. */
+const axReadsRecordOperation = defineOperation<z.infer<typeof axReadsRecordSchema>, Record<string, unknown>>({
+  name: 'ax.reads.record',
+  mutates: false,
+  input: axReadsRecordSchema,
+  inputShape: axReadsRecordShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/ax/context-reads',
+  },
+  handler: (input) => {
+    const read = canvasState.recordContextRead(
+      {
+        channel: input.channel,
+        resource: input.resource,
+        source: input.source ?? 'api',
+        consumer: input.consumer ?? null,
+        agentId: input.agentId ?? null,
+        pinnedNodeIds: input.pinnedNodeIds ?? [...canvasState.contextPinnedNodeIds],
+        deliveredNodeIds: input.deliveredNodeIds,
+        bytes: input.bytes,
+      },
+      input.boardId === undefined ? canvasState.activeBoardId : input.boardId,
+    );
+    return { ok: true, read };
+  },
+});
+
 export const axTimelineOperations: Operation[] = [
   axEventRecordOperation,
   axEvidenceAddOperation,
@@ -470,4 +543,6 @@ export const axTimelineOperations: Operation[] = [
   axDeliveryPendingOperation,
   axDeliveryMarkOperation,
   axCommandInvokeOperation,
+  axReadsListOperation,
+  axReadsRecordOperation,
 ];

package/src/server/operations/ops/backup.ts

@@ -0,0 +1,134 @@
+/**
+ * Library backup (plan 012): backup.status / backup.run / backup.schedule /
+ * backup.restore. HTTP, CLI and SDK only — backing up and restoring are the
+ * human's maintenance, not agent tools, so there is no MCP surface.
+ *
+ * This module must never import server.ts or index.ts.
+ */
+import { z } from 'zod';
+import {
+  assertRestorableBackup,
+  getBackupStatus,
+  parseBackupInterval,
+  runBackup,
+  setBackupSchedule,
+} from '../../backup.js';
+import { restoreCanvasLibrary } from '../../canvas-operations.js';
+import { canvasState } from '../../canvas-state.js';
+import { defineOperation, OperationError, type Operation } from '../types.js';
+import { boardsPayload } from './boards.js';
+
+function requireDatabase(): void {
+  if (!canvasState.databasePath) throw new OperationError('Backups need a workspace database.', 409);
+}
+
+function positiveInteger(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null || value === '') return undefined;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1)
+    throw new OperationError(`${field} must be a whole number of 1 or more.`);
+  return parsed;
+}
+
+const statusShape = {};
+const statusSchema = z.looseObject(statusShape);
+
+const backupStatusOperation = defineOperation<z.infer<typeof statusSchema>, Record<string, unknown>>({
+  name: 'backup.status',
+  mutates: false,
+  input: statusSchema,
+  inputShape: statusShape,
+  http: { method: 'GET', path: '/api/canvas/backup' },
+  handler: () => {
+    requireDatabase();
+    return { ok: true, ...getBackupStatus() };
+  },
+});
+
+const runShape = {
+  to: z.unknown().optional().describe('Folder to write the backup to (default: the configured folder)'),
+  keep: z.unknown().optional().describe('How many backups to keep in that folder'),
+};
+const runSchema = z.looseObject(runShape);
+
+const backupRunOperation = defineOperation<z.infer<typeof runSchema>, Record<string, unknown>>({
+  name: 'backup.run',
+  mutates: false,
+  input: runSchema,
+  inputShape: runShape,
+  http: { method: 'POST', path: '/api/canvas/backup' },
+  handler: (input) => {
+    requireDatabase();
+    const result = runBackup({
+      ...(typeof input.to === 'string' && input.to.trim() ? { folder: input.to.trim() } : {}),
+      ...(positiveInteger(input.keep, 'keep') ? { keep: positiveInteger(input.keep, 'keep') } : {}),
+    });
+    return { ok: true, ...result, status: getBackupStatus() };
+  },
+});
+
+const scheduleShape = {
+  every: z.unknown().optional().describe('Interval like "24h", "30m", "7d"; "off" or null stops scheduled backups'),
+  to: z.unknown().optional().describe('Backup folder'),
+  keep: z.unknown().optional().describe('How many backups to keep'),
+};
+const scheduleSchema = z.looseObject(scheduleShape);
+
+const backupScheduleOperation = defineOperation<z.infer<typeof scheduleSchema>, Record<string, unknown>>({
+  name: 'backup.schedule',
+  mutates: false,
+  input: scheduleSchema,
+  inputShape: scheduleShape,
+  http: { method: 'POST', path: '/api/canvas/backup/schedule' },
+  handler: (input) => {
+    requireDatabase();
+    const off = input.every === null || input.every === 'off';
+    const everyMs = off ? null : parseBackupInterval(String(input.every ?? ''));
+    if (!off && everyMs === null) throw new OperationError('every must look like "30m", "24h" or "7d", or be "off".');
+    try {
+      const status = setBackupSchedule({
+        everyMs,
+        ...(typeof input.to === 'string' && input.to.trim() ? { folder: input.to.trim() } : {}),
+        ...(positiveInteger(input.keep, 'keep') ? { keep: positiveInteger(input.keep, 'keep') } : {}),
+      });
+      return { ok: true, ...status };
+    } catch (error) {
+      throw new OperationError(error instanceof Error ? error.message : String(error));
+    }
+  },
+});
+
+const restoreShape = {
+  file: z.unknown().optional().describe('Backup file to restore'),
+};
+const restoreSchema = z.looseObject(restoreShape);
+
+const backupRestoreOperation = defineOperation<z.infer<typeof restoreSchema>, Record<string, unknown>>({
+  name: 'backup.restore',
+  mutates: false,
+  input: restoreSchema,
+  inputShape: restoreShape,
+  http: { method: 'POST', path: '/api/canvas/backup/restore' },
+  handler: (input, ctx) => {
+    requireDatabase();
+    const file = typeof input.file === 'string' ? input.file.trim() : '';
+    if (!file) throw new OperationError('file is required.');
+    try {
+      assertRestorableBackup(file);
+    } catch (error) {
+      throw new OperationError(error instanceof Error ? error.message : String(error));
+    }
+    const previous = `${canvasState.databasePath}.before-restore`;
+    restoreCanvasLibrary(file);
+    // `reloaded` tells open tabs to take the board fresh even when its id is unchanged.
+    ctx.emit('boards-changed', { ...boardsPayload(), reloaded: true });
+    return { ok: true, restored: file, previous, ...boardsPayload() };
+  },
+});
+
+export const backupOperations: Operation[] = [
+  backupStatusOperation,
+  backupRunOperation,
+  backupScheduleOperation,
+  backupRestoreOperation,
+];

package/src/server/operations/ops/batch.ts

@@ -250,7 +250,14 @@ async function runBatch(operations: BatchEntry[]): Promise<BatchEnvelope> {
       // ghost-cursor exemption for batch operations). No `fromWorkbench`: the
       // browser never issues batches, so inner writes are agent writes and the
       // scope fence applies to each of them.
-      const raw = await executeOperation(dispatch.name, dispatch.args, { suppressAutoGhost: true });
+      const pending = executeOperation(dispatch.name, dispatch.args, { suppressAutoGhost: true });
+      // The first write may synchronously open a board from Home. Capture after
+      // dispatch, then refuse to continue a partially completed batch elsewhere.
+      const boardGeneration = canvasState.boardGeneration;
+      const raw = await pending;
+      if (canvasState.boardGeneration !== boardGeneration) {
+        throw new Error('The board changed while the batch was running.');
+      }
       const result = shapeBatchEntry(operation.op, raw);
       results.push(result);
       if (typeof operation.assign === 'string' && operation.assign.trim().length > 0) {