pmx-canvas 0.6.5 → 0.7.1

package/src/server/document-import.ts

@@ -0,0 +1,223 @@
+import type { Database } from 'bun:sqlite';
+import { randomUUID } from 'node:crypto';
+
+export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+export const MAX_INLINE_ATTACHMENT_BYTES = 2 * 1024 * 1024;
+export const MAX_ATTACHMENT_NAME_LENGTH = 255;
+export const MAX_IMPORT_SECTIONS = 32;
+export const MAX_IMPORT_WARNINGS = 20;
+export const MAX_IMPORT_TEXT = 200_000;
+export const MAX_IMPORT_TITLE_LENGTH = 500;
+export const MAX_IMPORT_REFERENCE_LENGTH = 2_000;
+export const MAX_IMPORT_WARNING_LENGTH = 2_000;
+export const MAX_IMPORT_AGENT_DESCRIPTION_LENGTH = 4_000;
+export const MAX_IMPORT_REASON_LENGTH = 4_000;
+
+export interface Attachment {
+  id: string;
+  boardId: string;
+  sha256: string;
+  name: string;
+  mime: string;
+  size: number;
+  createdAt: string;
+}
+
+export interface ImportSection {
+  title: string;
+  markdown: string;
+  reference?: string;
+}
+export type DocumentImportStatus = 'attached' | 'requested' | 'drafted' | 'unavailable' | 'cancelled' | 'committed';
+export interface DocumentImport {
+  id: string;
+  boardId: string;
+  attachmentId: string;
+  status: DocumentImportStatus;
+  position: { x: number; y: number };
+  sections: ImportSection[];
+  warnings: string[];
+  agentDescription: string | null;
+  reason: string | null;
+  committedNodeIds: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface AttachmentRow {
+  id: string;
+  board_id: string;
+  sha256: string;
+  name: string;
+  mime: string;
+  size: number;
+  created_at: string;
+}
+interface ImportRow {
+  id: string;
+  board_id: string;
+  attachment_id: string;
+  status: DocumentImportStatus;
+  position_x: number;
+  position_y: number;
+  sections: string | null;
+  warnings: string | null;
+  agent_description: string | null;
+  reason: string | null;
+  committed_node_ids: string | null;
+  created_at: string;
+  updated_at: string;
+}
+const attachment = (r: AttachmentRow): Attachment => ({
+  id: r.id,
+  boardId: r.board_id,
+  sha256: r.sha256,
+  name: r.name,
+  mime: r.mime,
+  size: r.size,
+  createdAt: r.created_at,
+});
+const imported = (r: ImportRow): DocumentImport => ({
+  id: r.id,
+  boardId: r.board_id,
+  attachmentId: r.attachment_id,
+  status: r.status,
+  position: { x: r.position_x, y: r.position_y },
+  sections: r.sections ? (JSON.parse(r.sections) as ImportSection[]) : [],
+  warnings: r.warnings ? (JSON.parse(r.warnings) as string[]) : [],
+  agentDescription: r.agent_description,
+  reason: r.reason,
+  committedNodeIds: r.committed_node_ids ? (JSON.parse(r.committed_node_ids) as string[]) : [],
+  createdAt: r.created_at,
+  updatedAt: r.updated_at,
+});
+
+export function storeAttachment(
+  db: Database,
+  input: { boardId: string; name: string; mime: string; bytes: Uint8Array },
+): Attachment {
+  if (!input.name.trim() || input.name.length > MAX_ATTACHMENT_NAME_LENGTH)
+    throw new Error(`Attachment name must be 1-${MAX_ATTACHMENT_NAME_LENGTH} characters.`);
+  if (input.bytes.byteLength === 0 || input.bytes.byteLength > MAX_ATTACHMENT_BYTES)
+    throw new Error(`Attachment must contain 1-${MAX_ATTACHMENT_BYTES} bytes.`);
+  const sha256 = new Bun.CryptoHasher('sha256').update(input.bytes).digest('hex');
+  const value: Attachment = {
+    id: randomUUID(),
+    boardId: input.boardId,
+    sha256,
+    name: input.name,
+    mime: input.mime,
+    size: input.bytes.byteLength,
+    createdAt: new Date().toISOString(),
+  };
+  db.transaction(() => {
+    db.run('INSERT OR IGNORE INTO attachment_bytes (sha256,data,size) VALUES (?,?,?)', [
+      sha256,
+      input.bytes,
+      value.size,
+    ]);
+    db.run('INSERT INTO attachments (id,board_id,sha256,name,mime,size,created_at) VALUES (?,?,?,?,?,?,?)', [
+      value.id,
+      value.boardId,
+      value.sha256,
+      value.name,
+      value.mime,
+      value.size,
+      value.createdAt,
+    ]);
+  })();
+  return value;
+}
+
+export function getAttachment(db: Database, id: string): Attachment | null {
+  const row = db
+    .query<AttachmentRow, [string]>('SELECT id,board_id,sha256,name,mime,size,created_at FROM attachments WHERE id=?')
+    .get(id);
+  return row ? attachment(row) : null;
+}
+export function readAttachmentBytes(db: Database, id: string): Uint8Array | null {
+  return (
+    db
+      .query<{ data: Uint8Array }, [string]>(
+        'SELECT b.data FROM attachment_bytes b JOIN attachments a ON a.sha256=b.sha256 WHERE a.id=?',
+      )
+      .get(id)?.data ?? null
+  );
+}
+export function copyBoardAttachments(
+  db: Database,
+  sourceBoardId: string,
+  targetBoardId: string,
+  referencedIds: Set<string>,
+): Map<string, string> {
+  const map = new Map<string, string>();
+  const rows = db
+    .query<AttachmentRow, string[]>(
+      `SELECT id,board_id,sha256,name,mime,size,created_at FROM attachments WHERE board_id=? AND id IN (${[...referencedIds].map(() => '?').join(',') || "''"})`,
+    )
+    .all(sourceBoardId, ...referencedIds);
+  for (const row of rows) {
+    const id = randomUUID();
+    map.set(row.id, id);
+    db.run('INSERT INTO attachments (id,board_id,sha256,name,mime,size,created_at) VALUES (?,?,?,?,?,?,?)', [
+      id,
+      targetBoardId,
+      row.sha256,
+      row.name,
+      row.mime,
+      row.size,
+      new Date().toISOString(),
+    ]);
+  }
+  return map;
+}
+export function createImport(db: Database, attachmentId: string, position: { x: number; y: number }): DocumentImport {
+  const a = getAttachment(db, attachmentId);
+  if (!a) throw new Error('Attachment not found.');
+  const now = new Date().toISOString(),
+    id = randomUUID();
+  db.run(
+    "INSERT INTO document_imports (id,board_id,attachment_id,status,position_x,position_y,created_at,updated_at) VALUES (?,?,?,'attached',?,?,?,?)",
+    [id, a.boardId, attachmentId, position.x, position.y, now, now],
+  );
+  return getImport(db, id)!;
+}
+export function getImport(db: Database, id: string): DocumentImport | null {
+  const r = db.query<ImportRow, [string]>('SELECT * FROM document_imports WHERE id=?').get(id);
+  return r ? imported(r) : null;
+}
+export function listImports(db: Database, boardId?: string): DocumentImport[] {
+  const rows = boardId
+    ? db
+        .query<ImportRow, [string]>('SELECT * FROM document_imports WHERE board_id=? ORDER BY created_at DESC')
+        .all(boardId)
+    : db.query<ImportRow, []>('SELECT * FROM document_imports ORDER BY created_at DESC').all();
+  return rows.map(imported);
+}
+export function updateImport(
+  db: Database,
+  id: string,
+  status: DocumentImportStatus,
+  fields: {
+    sections?: ImportSection[];
+    warnings?: string[];
+    agentDescription?: string;
+    reason?: string;
+    committedNodeIds?: string[];
+  } = {},
+): DocumentImport {
+  db.run(
+    'UPDATE document_imports SET status=?,sections=COALESCE(?,sections),warnings=COALESCE(?,warnings),agent_description=COALESCE(?,agent_description),reason=COALESCE(?,reason),committed_node_ids=COALESCE(?,committed_node_ids),updated_at=? WHERE id=?',
+    [
+      status,
+      fields.sections ? JSON.stringify(fields.sections) : null,
+      fields.warnings ? JSON.stringify(fields.warnings) : null,
+      fields.agentDescription ?? null,
+      fields.reason ?? null,
+      fields.committedNodeIds ? JSON.stringify(fields.committedNodeIds) : null,
+      new Date().toISOString(),
+      id,
+    ],
+  );
+  return getImport(db, id)!;
+}

package/src/server/index.ts

@@ -37,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';
@@ -600,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);
   }
 
@@ -682,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();
   }
@@ -1014,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;
   }
 
@@ -1435,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:
@@ -217,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',
@@ -301,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);
 }