pmx-canvas 0.6.4 → 0.7.0

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

@@ -32,6 +32,7 @@
  */
 import { z } from 'zod';
 import { canvasState } from '../../canvas-state.js';
+import { describeCreateSize, type CanvasSizeAdjustment } from '../../canvas-operations.js';
 import {
   closeMcpAppSession,
   openMcpApp as openExternalMcpApp,
@@ -75,6 +76,7 @@ export interface OpenMcpAppCoreResult {
   toolCallId: string;
   sessionId: string;
   resourceUri: string;
+  sizeAdjustment?: CanvasSizeAdjustment;
 }
 
 /**
@@ -105,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,
@@ -112,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) {
@@ -121,6 +128,7 @@ export async function openMcpAppCore(input: OpenMcpAppCoreInput, ctx: OperationC
   const toolResult = isExcalidrawCreateView(opened.serverName, opened.toolName)
     ? ensureExcalidrawCheckpointId(opened.toolResult, nodeIdSeed)
     : opened.toolResult;
+  const existingNodeIds = new Set(canvasState.getLayout().nodes.map((node) => node.id));
   ctx.emit('ext-app-open', {
     toolCallId,
     nodeId: nodeIdSeed,
@@ -158,6 +166,11 @@ export async function openMcpAppCore(input: OpenMcpAppCoreInput, ctx: OperationC
       getNode: (id) => canvasState.getNode(id),
       listNodes: () => canvasState.getLayout().nodes,
     });
+  const node = nodeId ? canvasState.getNode(nodeId) : undefined;
+  const sizeAdjustment =
+    node && !existingNodeIds.has(node.id)
+      ? describeCreateSize(input.width, input.height, node.size.width, node.size.height, node.size)
+      : undefined;
   return {
     ok: true,
     ...(nodeId ? { id: nodeId } : {}),
@@ -165,6 +178,7 @@ export async function openMcpAppCore(input: OpenMcpAppCoreInput, ctx: OperationC
     toolCallId,
     sessionId: opened.sessionId,
     resourceUri: opened.resourceUri,
+    ...(sizeAdjustment ? { sizeAdjustment } : {}),
   };
 }
 
@@ -388,6 +402,7 @@ function webArtifactEnvelope(result: WebArtifactCanvasBuildResult, includeLogs:
     ...(typeof result.nodeId === 'string' ? { id: result.nodeId } : {}),
     nodeId: result.nodeId,
     url: result.url,
+    ...(result.sizeAdjustment ? { sizeAdjustment: result.sizeAdjustment } : {}),
     metadata: result.metadata,
     logs: result.logs,
     ...(includeLogs ? { stdout: result.stdout, stderr: result.stderr } : {}),

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

@@ -145,7 +145,11 @@ function createInternalBatchNode(args: Record<string, unknown>): Record<string,
     defaultHeight: 200,
   });
 
-  return { ok: true, ...serializeCanvasNodeCompact(created.node) };
+  return {
+    ok: true,
+    ...serializeCanvasNodeCompact(created.node),
+    ...(created.sizeAdjustment ? { sizeAdjustment: created.sizeAdjustment } : {}),
+  };
 }
 
 /**
@@ -165,7 +169,7 @@ function shapeBatchEntry(op: string, result: unknown): Record<string, unknown> {
     const id = typeof body.id === 'string' ? body.id : '';
     const node = id ? canvasState.getNode(id) : undefined;
     const extras: Record<string, unknown> = {};
-    for (const key of ['fetch', 'error', 'url', 'spec']) {
+    for (const key of ['fetch', 'error', 'url', 'spec', 'sizeAdjustment']) {
       if (body[key] !== undefined) extras[key] = body[key];
     }
     if (node) return { ok: true, ...serializeCanvasNodeCompact(node), ...extras };
@@ -183,7 +187,11 @@ function shapeBatchEntry(op: string, result: unknown): Record<string, unknown> {
   if (op === 'group.add') {
     const groupId = typeof body.groupId === 'string' ? body.groupId : '';
     const group = groupId ? canvasState.getNode(groupId) : undefined;
-    return { ok: true, ...(group ? serializeCanvasNode(group) : { id: groupId }) };
+    return {
+      ok: true,
+      ...(group ? serializeCanvasNode(group) : { id: groupId }),
+      ...(body.sizeAdjustment ? { sizeAdjustment: body.sizeAdjustment } : {}),
+    };
   }
 
   // pin.set/add/remove: legacy pushed { ok:true, ...{ count, nodeIds } }; wire shape drops nodeIds.
@@ -242,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) {
@@ -305,6 +320,7 @@ function compactBatchValue(value: unknown): unknown {
     'content',
     'position',
     'size',
+    'sizeAdjustment',
     'fetch',
     'error',
     'from',