pmx-canvas 0.6.5 → 0.7.0

package/dist/types/server/canvas-state.d.ts

@@ -12,8 +12,11 @@
  * the one-shot boot migration into SQLite was retired.
  */
 import { type Tour } from '../shared/tour.js';
-import { type PersistedCanvasState, type CanvasTheme, type AxTimelineQuery } from './canvas-db.js';
+import { type CanvasBoard, type PersistedCanvasState, type CanvasTheme, type AxTimelineQuery } from './canvas-db.js';
+import { type DocumentImport, type DocumentImportStatus, type ImportSection, type Attachment } from './document-import.js';
 import { type PmxAxActivityKind, type PmxAxElicitation, type PmxAxModeRequest, type PmxAxMode, type PmxAxCommandDescriptor, type PmxAxPolicy, type PmxAxFocusState, type PmxAxSource, type PmxAxState, type PmxAxWorkItem, type PmxAxWorkItemStatus, type PmxAxApprovalGate, type PmxAxReviewAnnotation, type PmxAxReviewKind, type PmxAxReviewSeverity, type PmxAxReviewStatus, type PmxAxReviewAnchorType, type PmxAxReviewRegion, type PmxAxEvent, type PmxAxEventKind, type PmxAxEvidence, type PmxAxEvidenceKind, type PmxAxSteeringMessage, type PmxAxHostCapability, type PmxAxTimelineSummary } from './ax-state.js';
+import { type ActorAttribution } from './attribution.js';
+import { type ContextRead, type ContextReadConsumerSummary, type ContextReadInput } from './context-reads.js';
 export declare const PMX_CANVAS_DIR = ".pmx-canvas";
 export interface PersistedBlobRef {
     __pmxCanvasBlob: 'v1';
@@ -54,7 +57,7 @@ export interface CanvasSnapshotGcResult {
 }
 export interface CanvasNodeState {
     id: string;
-    type: 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'diff' | 'mermaid' | 'image' | 'html' | 'group';
+    type: 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'board' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'diff' | 'mermaid' | 'image' | 'html' | 'group';
     position: {
         x: number;
         y: number;
@@ -67,6 +70,27 @@ export interface CanvasNodeState {
     collapsed: boolean;
     pinned: boolean;
     data: Record<string, unknown>;
+    /** Server-owned provenance. Legacy rows normalize to unknown. */
+    createdBy?: ActorAttribution;
+    lastEditedBy?: ActorAttribution;
+    /** Board-monotonic revision of this node's latest semantic content. */
+    contentRevision?: number;
+}
+export interface NodeDeletionTombstone {
+    nodeId: string;
+    revision: number;
+    deletedBy: ActorAttribution;
+}
+export interface BoardContentRevision {
+    revision: number;
+    /** Cursors below this value are expired and must perform a full reset. */
+    retentionFloor: number;
+}
+export interface BoardContentDelta extends BoardContentRevision {
+    since: number;
+    reset: boolean;
+    nodes: CanvasNodeState[];
+    deleted: NodeDeletionTombstone[];
 }
 export interface ViewportState {
     x: number;
@@ -123,6 +147,8 @@ export interface CanvasNodeUpdate {
     collapsed?: boolean;
 }
 export type CanvasChangeType = 'pins' | 'nodes' | 'ax' | 'ax-timeline';
+/** Name for a board nobody named yet: when it was made, to the minute. */
+export declare function defaultBoardName(): string;
 export interface MutationRecordInfo {
     operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'updateEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'addWorkItem' | 'updateWorkItem' | 'requestApproval' | 'resolveApproval' | 'addReviewAnnotation' | 'updateReviewAnnotation' | 'requestElicitation' | 'respondElicitation' | 'requestMode' | 'resolveModeRequest' | 'setPolicy' | 'arrange' | 'batch' | 'groupNodes' | 'releaseGroupChildren' | 'viewport';
     description: string;
@@ -146,6 +172,9 @@ declare class CanvasStateManager {
     private _theme;
     private _contextPinnedNodeIds;
     private _workspaceRoot;
+    private _contentRevision;
+    private _revisionFloor;
+    private _deletionTombstones;
     private readonly ax;
     private _changeListeners;
     /**
@@ -178,12 +207,22 @@ declare class CanvasStateManager {
     private applyResolvedGroupBounds;
     private getGroupSnapshot;
     private normalizeNode;
+    private nextContentRevision;
+    private revisionState;
+    /**
+     * Stable delta cursor contract: revisions strictly increase per active board;
+     * geometry-only writes do not advance them. `reset` means `since` predates
+     * retained tombstones, so callers must replace their view with `nodes`.
+     */
+    readContentDelta(since?: number): BoardContentDelta;
+    getContentRevision(): BoardContentRevision;
     private nodeForRead;
     private reflowAllGroups;
     private translateGroupChildren;
     private recomputeParentGroupBounds;
     private compactGroupChildren;
     private _db;
+    private _dbPath;
     private _saveTimer;
     /** Workspace root backing persistence and workspace-relative path resolution. */
     get workspaceRoot(): string;
@@ -201,8 +240,95 @@ declare class CanvasStateManager {
     private externalizePersistedStateBlobs;
     getWorkspaceRoot(): string;
     private emptyPersistedState;
-    /** Load canvas state from SQLite. Call once on server startup. */
+    /**
+     * Load the board that was open last. Call once on server startup. With no
+     * such board the workspace starts on Home (no board open).
+     */
     loadFromDisk(options?: LoadFromDiskOptions): boolean;
+    /** The SQLite file holding every board, or null without a workspace database. */
+    get databasePath(): string | null;
+    readWorkspaceMeta(key: string): string | null;
+    writeWorkspaceMeta(key: string, value: string | null): void;
+    /** A consistent copy of the whole library, safe while the server runs. */
+    backupDatabaseTo(path: string): void;
+    /**
+     * Replace the library with `file`: the current file is kept beside it as
+     * `<db>.before-restore`, then the restored file opens (migrating an older
+     * layout) on the board it had open last.
+     */
+    replaceDatabase(file: string): void;
+    private _activeBoardId;
+    private _boardGeneration;
+    /** Invalidates asynchronous work whenever the loaded board state is replaced. */
+    get boardGeneration(): number;
+    /** The open board, or null on Home. */
+    get activeBoardId(): string | null;
+    getActiveBoard(): CanvasBoard | null;
+    /**
+     * One board's content without opening it: the open board from memory, any
+     * other straight from SQLite. Null when there is no such board.
+     */
+    readBoard(id: string, includeBlobs?: boolean): {
+        board: CanvasBoard;
+        state: PersistedCanvasState;
+        layout: CanvasLayout;
+    } | null;
+    /** Every board in the workspace, most recently opened first. */
+    listBoards(): CanvasBoard[];
+    storeAttachment(input: {
+        boardId: string;
+        name: string;
+        mime: string;
+        bytes: Uint8Array;
+    }): Attachment | null;
+    getAttachment(id: string): Attachment | null;
+    readAttachmentBytes(id: string): Uint8Array | null;
+    createDocumentImport(attachmentId: string, position: {
+        x: number;
+        y: number;
+    }): DocumentImport | null;
+    getDocumentImport(id: string): DocumentImport | null;
+    listDocumentImports(boardId?: string): DocumentImport[];
+    updateDocumentImport(id: string, status: DocumentImportStatus, fields?: {
+        sections?: ImportSection[];
+        warnings?: string[];
+        agentDescription?: string;
+        reason?: string;
+        committedNodeIds?: string[];
+    }): DocumentImport | null;
+    commitDocumentImport(id: string, nodeIds: string[]): DocumentImport | null;
+    getContextBriefCursor(boardId: string, consumer: string): number | null;
+    advanceContextBriefCursor(boardId: string, consumer: string, revision: number): void;
+    /** Creates a board without opening it. */
+    createBoard(name: string, category?: string | null): CanvasBoard | null;
+    updateBoard(id: string, patch: {
+        name?: string;
+        category?: string | null;
+    }): boolean;
+    setBoardReadme(id: string, nodeId: string | null): boolean;
+    /** Bounded inactive-board creation; never replaces the state the human has open. */
+    createBoardFromBoard(input: {
+        sourceBoardId: string;
+        name: string;
+        category?: string | null;
+        nodeIds?: string[];
+        includeReadme?: boolean;
+        includeStructure?: boolean;
+    }): CanvasBoard | null;
+    /** Deletes a board and its snapshots; deleting the open board returns to Home first. */
+    deleteBoard(id: string): boolean;
+    /**
+     * Save the open board, then open `id` (or Home for null). The canvas state is
+     * replaced wholesale; callers own the runtime side (undo history, app
+     * sessions, watchers, SSE) — see `openCanvasBoard` in canvas-operations.
+     */
+    switchBoard(id: string | null): boolean;
+    /**
+     * Content written while no board is open (Home) lands on a new board, which
+     * opens: nothing the human was looking at is displaced.
+     */
+    private ensureActiveBoard;
+    private hasBoardContent;
     /** Debounced save — coalesces rapid mutations into a single write. */
     private scheduleSave;
     flushToDisk(): void;
@@ -246,6 +372,11 @@ declare class CanvasStateManager {
     deleteSnapshot(id: string): boolean;
     /** Remove all snapshots from the DB. Used by test teardown. */
     clearAllSnapshots(): void;
+    private restampRestoredContent;
+    private semanticData;
+    private nodeContentChanged;
+    private setSemanticNode;
+    private recordDeletion;
     get viewport(): ViewportState;
     addNode(node: CanvasNodeState): void;
     addJsonRenderNode(node: CanvasNodeState): void;
@@ -476,6 +607,12 @@ declare class CanvasStateManager {
     }): PmxAxSteeringMessage[];
     getPendingSteeringCount(consumer?: string): number;
     getAxTimelineSummary(): PmxAxTimelineSummary;
+    /** Records one agent context read (diagnostics; never notifies, so a read cannot trigger reads). */
+    recordContextRead(input: ContextReadInput, boardId?: string | null): ContextRead | null;
+    getContextReads(limit?: number): {
+        reads: ContextRead[];
+        summary: ContextReadConsumerSummary[];
+    };
     getAxTimeline(q?: AxTimelineQuery): {
         events: PmxAxEvent[];
         evidence: PmxAxEvidence[];

package/dist/types/server/context-brief.d.ts

@@ -0,0 +1,111 @@
+import type { CanvasNodeState, NodeDeletionTombstone } from './canvas-state.js';
+export type ContextBriefReason = 'pinned' | 'changed' | 'human' | 'ask' | 'steer' | 'linked' | 'category';
+export interface ContextBriefSourceEntry {
+    sourceBoardId: string;
+    nodeId: string;
+    reason: 'human' | 'ask' | 'steer';
+    title: string;
+    text: string;
+    provenance?: {
+        kind: 'imported';
+        source: string;
+    };
+}
+export interface ContextBriefLibraryBoard {
+    boardId: string;
+    name: string;
+    category: string | null;
+    readme?: {
+        nodeId: string;
+        title: string;
+        summary: string;
+        provenance?: {
+            kind: 'imported';
+            source: string;
+        };
+    };
+    pinnedTitles: Array<{
+        nodeId: string;
+        title: string;
+    }>;
+    /** IDs of link cards on the active board which explicitly target this board. */
+    linkIds: string[];
+}
+export interface ContextBriefInput {
+    activeBoard: {
+        boardId: string;
+        name: string;
+        category: string | null;
+    };
+    nodes: readonly CanvasNodeState[];
+    pinnedNodeIds: readonly string[];
+    contentRevision: number;
+    retentionFloor: number;
+    tombstones: readonly NodeDeletionTombstone[];
+    /** null means a first read. Other values must be non-negative safe integers. */
+    since: number | null;
+    libraryBoards: readonly ContextBriefLibraryBoard[];
+    entries?: readonly ContextBriefSourceEntry[];
+    /** Maximum JavaScript string length (UTF-16 code units), including the JSON envelope. */
+    budget: number;
+}
+export interface CompiledContextEntry {
+    sourceBoardId: string;
+    nodeId: string;
+    reason: ContextBriefReason;
+    title: string;
+    text: string;
+    /** A linked board's pin title is discovery metadata, not delivery of that pinned card. */
+    titleOnly?: true;
+    /** The body was shortened to fit; the same revision remains eligible on the next pull. */
+    truncated?: true;
+    provenance?: {
+        kind: 'imported';
+        source: string;
+        trust: 'source-material-not-instructions';
+    };
+}
+export interface ContextBriefDocument {
+    version: 1;
+    budgetUnit: 'utf16-code-units';
+    board: {
+        boardId: string;
+        name: string;
+        category: string | null;
+    };
+    cursor: {
+        requested: number | null;
+        next: number | null;
+        current: number;
+        retentionFloor: number;
+        reset: 'first-read' | 'retention-expired' | null;
+        valid: boolean;
+    };
+    entries: CompiledContextEntry[];
+    deletions: Array<{
+        sourceBoardId: string;
+        nodeId: string;
+        revision: number;
+    }>;
+    delivery: {
+        truncated: boolean;
+        omittedEntries: number;
+        omittedDeletions: number;
+    };
+}
+export interface ContextBriefResult {
+    /** Empty only when the budget cannot hold even the bounded JSON envelope. */
+    serialized: string;
+    document: ContextBriefDocument | null;
+    deliveredEntryIds: string[];
+    deliveredDeletionIds: string[];
+    nextCursor: number | null;
+    reset: ContextBriefDocument['cursor']['reset'];
+    invalidCursor: boolean;
+    truncated: boolean;
+}
+/**
+ * Pure, deterministic compiler. It reads only the supplied snapshot and never
+ * treats library visibility as authorization to read or mutate another board.
+ */
+export declare function compileContextBrief(input: ContextBriefInput): ContextBriefResult;

package/dist/types/server/context-reads.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Context read instrumentation (vision Part 1 item 4, the delivery half):
+ * one row per agent read of canvas context — which surface, by whom, and
+ * which pinned nodes were in what came back. Diagnostics only, like the AX
+ * timeline: never snapshotted, never cleared with the canvas, bounded, and
+ * recording never notifies (a read must not trigger more reads).
+ */
+import type { Database } from 'bun:sqlite';
+export declare const CONTEXT_READ_RETENTION = 5000;
+export declare const CONTEXT_READ_CHANNELS: readonly ["operation", "mcp-resource", "mcp-prompt", "adapter"];
+export type ContextReadChannel = (typeof CONTEXT_READ_CHANNELS)[number];
+/** Registry reads that hand an agent canvas context; recorded in executeOperation. */
+export declare const CONTEXT_READ_OPS: Set<string>;
+export interface ContextRead {
+    seq: number;
+    id: string;
+    at: string;
+    channel: ContextReadChannel;
+    resource: string;
+    source: string;
+    consumer: string | null;
+    agentId: string | null;
+    pinnedNodeIds: string[];
+    deliveredNodeIds: string[];
+    bytes: number;
+    /** The board open when the read happened (null on Home). */
+    boardId: string | null;
+}
+export type ContextReadInput = Omit<ContextRead, 'seq' | 'id' | 'at' | 'boardId'> & {
+    /** Explicit read target, captured before asynchronous formatting/proxy work. */
+    boardId?: string | null;
+};
+export interface ContextReadConsumerSummary {
+    consumer: string;
+    reads: number;
+    readsWithPins: number;
+    readsDeliveringAllPins: number;
+    lastReadAt: string;
+    resources: Record<string, number>;
+}
+/**
+ * Pinned nodes whose serialized node (an object carrying `"id": "<id>"`) is in
+ * what the reader received. A bare id list, a title, or a clipped-off node does
+ * not count — the agent got the pin's name, not its content.
+ */
+export declare function deliveredPinnedIds(pinnedNodeIds: string[], payloadText: string): string[];
+export declare function contextReadFromPayload(base: Omit<ContextReadInput, 'deliveredNodeIds' | 'bytes'>, payload: unknown): ContextReadInput;
+export declare const CONTEXT_READS_SCHEMA_SQL = "\n  CREATE TABLE IF NOT EXISTS context_reads (\n    seq INTEGER PRIMARY KEY AUTOINCREMENT,\n    id TEXT NOT NULL UNIQUE,\n    at TEXT NOT NULL,\n    channel TEXT NOT NULL,\n    resource TEXT NOT NULL,\n    source TEXT NOT NULL,\n    consumer TEXT,\n    agent_id TEXT,\n    pinned_node_ids TEXT NOT NULL DEFAULT '[]',\n    delivered_node_ids TEXT NOT NULL DEFAULT '[]',\n    bytes INTEGER NOT NULL DEFAULT 0,\n    board_id TEXT\n  );\n";
+export declare function appendContextReadToDB(db: Database, input: ContextReadInput, boardId: string | null): ContextRead;
+/** Newest first. The summary covers every retained row, not just the returned page. */
+export declare function loadContextReadsFromDB(db: Database, limit?: number): {
+    reads: ContextRead[];
+    summary: ContextReadConsumerSummary[];
+};
+export declare function summarizeContextReads(reads: ContextRead[]): ContextReadConsumerSummary[];

package/dist/types/server/document-import.d.ts

@@ -0,0 +1,66 @@
+import type { Database } from 'bun:sqlite';
+export declare const MAX_ATTACHMENT_BYTES: number;
+export declare const MAX_INLINE_ATTACHMENT_BYTES: number;
+export declare const MAX_ATTACHMENT_NAME_LENGTH = 255;
+export declare const MAX_IMPORT_SECTIONS = 32;
+export declare const MAX_IMPORT_WARNINGS = 20;
+export declare const MAX_IMPORT_TEXT = 200000;
+export declare const MAX_IMPORT_TITLE_LENGTH = 500;
+export declare const MAX_IMPORT_REFERENCE_LENGTH = 2000;
+export declare const MAX_IMPORT_WARNING_LENGTH = 2000;
+export declare const MAX_IMPORT_AGENT_DESCRIPTION_LENGTH = 4000;
+export declare const MAX_IMPORT_REASON_LENGTH = 4000;
+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;
+}
+export declare function storeAttachment(db: Database, input: {
+    boardId: string;
+    name: string;
+    mime: string;
+    bytes: Uint8Array;
+}): Attachment;
+export declare function getAttachment(db: Database, id: string): Attachment | null;
+export declare function readAttachmentBytes(db: Database, id: string): Uint8Array | null;
+export declare function copyBoardAttachments(db: Database, sourceBoardId: string, targetBoardId: string, referencedIds: Set<string>): Map<string, string>;
+export declare function createImport(db: Database, attachmentId: string, position: {
+    x: number;
+    y: number;
+}): DocumentImport;
+export declare function getImport(db: Database, id: string): DocumentImport | null;
+export declare function listImports(db: Database, boardId?: string): DocumentImport[];
+export declare function updateImport(db: Database, id: string, status: DocumentImportStatus, fields?: {
+    sections?: ImportSection[];
+    warnings?: string[];
+    agentDescription?: string;
+    reason?: string;
+    committedNodeIds?: string[];
+}): DocumentImport;

package/dist/types/server/index.d.ts

@@ -7,7 +7,10 @@ import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout } from
 import { type AxInteractionInput, type AxInteractionPublicResult } from './ax-interaction.js';
 import type { PmxAxIntent } from '../shared/ax-intent.js';
 import type { PmxAxActivityKind, PmxAxApprovalGate, PmxAxCommandDescriptor, PmxAxContext, PmxAxElicitation, PmxAxEvent, PmxAxEvidence, PmxAxEvidenceKind, PmxAxFocusState, PmxAxHostCapability, PmxAxMode, PmxAxModeRequest, PmxAxPolicy, PmxAxReviewAnchorType, PmxAxReviewAnnotation, PmxAxReviewKind, PmxAxReviewRegion, PmxAxReviewSeverity, PmxAxReviewStatus, PmxAxSource, PmxAxState, PmxAxSteeringMessage, 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 type { BackupFile, BackupStatus } from './backup.js';
+import type { ExportManifest } from './board-export.js';
 import { searchNodes } from './spatial-analysis.js';
 import { diffLayouts } from './mutation-history.js';
 import { fitCanvasView, gcCanvasSnapshots, listCanvasSnapshots } from './canvas-operations.js';
@@ -155,7 +158,9 @@ export declare class PmxCanvas extends EventEmitter {
     getAxState(): PmxAxState;
     getAxContext(options?: {
         consumer?: string;
-    }): PmxAxContext;
+    }): PmxAxContext & {
+        boardId: string | null;
+    };
     setAxFocus(nodeIds: string[], options?: {
         source?: PmxAxSource;
     }): PmxAxFocusState;
@@ -201,6 +206,93 @@ export declare class PmxCanvas extends EventEmitter {
         source?: PmxAxSource;
     }): AxInteractionPublicResult;
     getAxTimeline(query?: AxTimelineQuery): ReturnType<typeof canvasState.getAxTimeline>;
+    listBoards(): {
+        activeBoardId: string | null;
+        boards: CanvasBoard[];
+    };
+    listImports(boardId?: string): DocumentImport[];
+    readImport(id: string): {
+        import: DocumentImport;
+        attachment: Attachment;
+        downloadPath: string;
+        bytes?: Uint8Array;
+    } | null;
+    submitImport(id: string, sections: ImportSection[], agentDescription: string, warnings?: string[]): Promise<DocumentImport>;
+    markImportUnavailable(id: string, reason: string): Promise<DocumentImport>;
+    attachDocument(input: {
+        boardId: string;
+        name: string;
+        mime?: string;
+        bytes: Uint8Array;
+        x?: number;
+        y?: number;
+    }): {
+        attachment: Attachment;
+        import: DocumentImport;
+        nodeId: string;
+    };
+    requestImport(id: string, consent: true, trustedHumanToken: string): Promise<DocumentImport>;
+    cancelImport(id: string, trustedHumanToken: string): Promise<DocumentImport>;
+    commitImport(id: string, trustedHumanToken: string): Promise<{
+        import: DocumentImport;
+        nodeIds: string[];
+    }>;
+    createBoard(name: string, category?: string): Promise<CanvasBoard>;
+    /** Rename a board and/or file it under a category (`category: null` removes it). */
+    updateBoard(id: string, patch: {
+        name?: string;
+        category?: string | null;
+    }): Promise<void>;
+    setBoardReadme(id: string, readmeNodeId: string | null): Promise<void>;
+    createBoardFrom(input: {
+        sourceBoardId: string;
+        name: string;
+        category?: string;
+        nodeIds?: string[];
+        includeReadme?: boolean;
+        includeStructure?: boolean;
+        preview?: boolean;
+    }): Promise<Record<string, unknown>>;
+    searchLibrary(query: string, limit?: number): Promise<Record<string, unknown>>;
+    /** Budgeted cross-board brief. Budget is measured in UTF-16 characters. */
+    getContextBrief(options?: {
+        consumer?: string;
+        since?: number;
+        budget?: number;
+    }): Promise<Record<string, unknown>>;
+    /** Open a board, or Home with null. */
+    openBoard(id: string | null): Promise<void>;
+    deleteBoard(id: string): Promise<void>;
+    /** Write a self-contained HTML file of a board (default: the open board). */
+    exportBoard(options?: {
+        board?: string;
+        includeFiles?: boolean;
+        includeDerivedText?: boolean;
+    }): Promise<{
+        path: string;
+        url: string;
+        bytes: number;
+        manifest: ExportManifest;
+    }>;
+    getBackupStatus(): Promise<BackupStatus>;
+    /** Back up every board now; `to` and `keep` default to the configured folder and count. */
+    backup(options?: {
+        to?: string;
+        keep?: number;
+    }): Promise<{
+        backup: BackupFile;
+        removed: string[];
+    }>;
+    /** Back up on a schedule run by the server; `every: 'off'` stops it. */
+    setBackupSchedule(options: {
+        every: string;
+        to?: string;
+        keep?: number;
+    }): Promise<BackupStatus>;
+    /** Replace every board with a backup file; the current file is kept as `canvas.db.before-restore`. */
+    restoreBackup(file: string): Promise<void>;
+    /** The context read log: which canvas context each agent read and which pinned nodes reached it. */
+    getContextReads(limit?: number): ReturnType<typeof canvasState.getContextReads>;
     listWorkItems(): PmxAxWorkItem[];
     addWorkItem(input: {
         title: string;
@@ -390,8 +482,12 @@ export declare class PmxCanvas extends EventEmitter {
         maxScale?: number;
         nodeIds?: string[];
     }): ReturnType<typeof fitCanvasView>;
-    getLayout(): CanvasLayout;
-    getNode(id: string): SdkCanvasNode | undefined;
+    getLayout(options?: {
+        board?: string;
+    }): CanvasLayout;
+    getNode(id: string, options?: {
+        board?: string;
+    }): SdkCanvasNode | undefined;
     search(query: string): ReturnType<typeof searchNodes>;
     getSpatialContext(): import("./spatial-analysis.js").SpatialContext;
     undo(): Promise<{
@@ -592,6 +688,9 @@ export type { CanvasNodeState, CanvasEdge, CanvasLayout, ViewportState } from '.
 export type { CanvasAutomationWebViewOptions, CanvasAutomationWebViewStatus, PrimaryWorkbenchCanvasPromptRequest, PrimaryWorkbenchIntent, } from './server.js';
 export { emitPrimaryWorkbenchEvent, consumePrimaryWorkbenchIntents, setPrimaryWorkbenchAutoOpenEnabled, setPrimaryWorkbenchCanvasPromptHandler, startCanvasServer, stopCanvasServer, getCanvasServerPort, openUrlInExternalBrowser, getCanvasAutomationWebViewStatus, startCanvasAutomationWebView, stopCanvasAutomationWebView, evaluateCanvasAutomationWebView, resizeCanvasAutomationWebView, 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, CanvasSnapshotGcResult, CanvasSnapshotListOptions, } from './canvas-state.js';
 export { findOpenCanvasPosition } from './placement.js';
 export { searchNodes, buildSpatialContext, detectClusters, findNeighborhoods } from './spatial-analysis.js';

package/dist/types/server/mutation-history.d.ts

@@ -114,5 +114,6 @@ export declare function diffLayouts(snapshotName: string, snapshotLayout: {
  */
 export declare function formatDiff(diff: SnapshotDiffResult): string;
 export declare const mutationHistory: MutationHistory;
+/** Direct callers share the same async-local attribution as node mutations. */
 export declare function setMutationActor(actor: MutationActor | null, writer?: string | null): void;
 export {};

package/dist/types/server/operations/invoker.d.ts

@@ -10,6 +10,7 @@ export declare function agentSourceLabel(fallback: string): string;
 /** Runs operations in-process against the shared canvasState singleton. */
 export declare class LocalOperationInvoker implements OperationInvoker {
     private readonly source;
+    private readonly proxiedRead;
     /** `source` labels this caller's agent presence ('mcp', 'sdk', …). */
     constructor(source?: string);
     invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
@@ -18,6 +19,7 @@ export declare class LocalOperationInvoker implements OperationInvoker {
 export declare class HttpOperationInvoker implements OperationInvoker {
     private readonly baseUrl;
     private readonly source;
+    private readonly proxiedRead;
     /** `source` labels this caller's agent presence on the server ('cli', 'mcp', …). */
     constructor(baseUrl: string, source?: string);
     invoke(name: string, rawInput: Record<string, unknown>): Promise<unknown>;

package/dist/types/server/operations/mcp.d.ts

@@ -1,9 +1,15 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { OperationInvoker } from './invoker.js';
+import { type OperationInvoker } from './invoker.js';
 import { type OperationMcpToolHost } from './types.js';
+import { type ContextReadInput } from '../context-reads.js';
 import { 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>;
 }
 export declare function registerOperationTools(server: McpServer, getHost: () => Promise<OperationToolHost>): void;
 /**

package/dist/types/server/operations/ops/ax-shared.d.ts

@@ -16,14 +16,14 @@ export declare const AX_SOURCES: readonly ["agent", "amp", "api", "browser", "cl
 export declare const AX_SOURCE_SHAPE: z.ZodOptional<z.ZodEnum<{
     amp: "amp";
     agent: "agent";
+    system: "system";
+    sdk: "sdk";
     api: "api";
     browser: "browser";
     cli: "cli";
     codex: "codex";
     copilot: "copilot";
     mcp: "mcp";
-    sdk: "sdk";
-    system: "system";
 }>>;
 /** Zod schema for the optional `agentId` field shared by AX MCP tool shapes. */
 export declare const AX_AGENT_ID_SHAPE: z.ZodOptional<z.ZodString>;

package/dist/types/server/operations/ops/backup.d.ts

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const backupOperations: Operation[];

package/dist/types/server/operations/ops/boards.d.ts

@@ -0,0 +1,10 @@
+import { type CanvasLayout } from '../../canvas-state.js';
+import { type Operation } from '../types.js';
+export declare function boardsPayload(): Record<string, unknown>;
+/** Read a board without opening it. Omitted board preserves the active-board contract. */
+export declare function readTargetBoard(boardId?: unknown, includeBlobs?: boolean): {
+    boardId: string | null;
+    layout: CanvasLayout;
+    pinnedNodeIds: Set<string>;
+};
+export declare const boardOperations: Operation[];

package/dist/types/server/operations/ops/export.d.ts

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const exportOperations: Operation[];

package/dist/types/server/operations/ops/imports.d.ts

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const importOperations: Operation[];