pmx-canvas 0.11.0 → 0.12.1

package/src/server/index.ts

@@ -1,4 +1,6 @@
 import { EventEmitter } from 'node:events';
+import type { BoardMoveInput, BoardMovePreview, BoardMoveResult } from './board-move.js';
+export type { BoardMoveInput, BoardMovePreview, BoardMoveResult } from './board-move.js';
 import type { Camera, Tour, TourPresenter, TourStop } from '../shared/tour.js';
 import {
   currentTour,
@@ -508,21 +510,19 @@ export class PmxCanvas extends EventEmitter {
     return (await executeOperation('edge.update', { id, ...patch }, { source: 'sdk' })) as CanvasEdge;
   }
 
-  addAnnotation(input: Omit<CanvasAnnotation, 'id' | 'createdAt'> & { id?: string; createdAt?: string }): string {
-    const id = input.id ?? `ann-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-    canvasState.addAnnotation({
-      ...input,
-      id,
-      createdAt: input.createdAt ?? new Date().toISOString(),
-    });
-    emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
-    return id;
+  async addAnnotation(
+    input: Pick<CanvasAnnotation, 'points'> &
+      Partial<Pick<CanvasAnnotation, 'id' | 'type' | 'color' | 'width' | 'text' | 'label'>>,
+  ): Promise<string> {
+    const result = (await executeOperation('annotation.add', input, { source: 'sdk' })) as {
+      annotation: { id: string };
+    };
+    return result.annotation.id;
   }
 
-  removeAnnotation(id: string): boolean {
-    const removed = canvasState.removeAnnotation(id);
-    if (removed) emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
-    return removed;
+  async removeAnnotation(id: string): Promise<boolean> {
+    const result = (await executeOperation('annotation.remove', { id }, { source: 'sdk' })) as { ok: boolean };
+    return result.ok;
   }
 
   removeEdge(id: string): void {
@@ -764,7 +764,12 @@ export class PmxCanvas extends EventEmitter {
   }
 
   /** Undelivered steering for a consumer (loop-safe; excludes consumer-originated). */
-  getPendingSteering(options?: { consumer?: string; limit?: number }): PmxAxSteeringMessage[] {
+  getPendingSteering(options?: {
+    consumer?: string;
+    limit?: number;
+    addressedOnly?: boolean;
+    offset?: number;
+  }): PmxAxSteeringMessage[] {
     return canvasState.getPendingSteering(options ?? {});
   }
 
@@ -954,6 +959,15 @@ export class PmxCanvas extends EventEmitter {
     return (await executeOperation('board.create-from', input, { source: 'sdk' })) as Record<string, unknown>;
   }
 
+  /** Relocate identities atomically; preview is read-only and retries reuse the original receipt. */
+  async moveSelectionToNewBoard(
+    input: BoardMoveInput,
+  ): Promise<{ ok: true; preview: BoardMovePreview } | (BoardMoveResult & { ok: true; replayed: boolean })> {
+    return (await executeOperation('board.move-selection', input, { source: 'sdk' })) as
+      | { ok: true; preview: BoardMovePreview }
+      | (BoardMoveResult & { ok: true; replayed: boolean });
+  }
+
   async searchLibrary(query: string, limit?: number): Promise<Record<string, unknown>> {
     return (await executeOperation('search', { q: query, scope: 'library', limit }, { source: 'sdk' })) as Record<
       string,
@@ -970,7 +984,13 @@ export class PmxCanvas extends EventEmitter {
 
   /** Budgeted cross-board brief. Budget is measured in UTF-16 characters. */
   async getContextBrief(
-    options: { consumer?: string; since?: number; budget?: number } = {},
+    options: {
+      consumer?: string;
+      since?: number;
+      budget?: number;
+      contextDelivery?: boolean;
+      includeSteering?: boolean;
+    } = {},
   ): Promise<Record<string, unknown>> {
     return (await executeOperation('context.get', options, { source: 'sdk' })) as Record<string, unknown>;
   }

package/src/server/intent-registry.ts

@@ -25,6 +25,8 @@ import {
   type PmxAxIntentKind,
 } from '../shared/ax-intent.js';
 import { OperationError } from './operations/types.js';
+import { createBoardLocal } from './board-local.js';
+import { canvasState } from './canvas-state.js';
 
 type IntentEmitter = (event: string, payload: Record<string, unknown>) => void;
 const MAX_VETO_TOMBSTONES = 128;
@@ -103,11 +105,33 @@ function nextIntentId(): string {
 }
 
 export class IntentRegistry {
-  private readonly intents = new Map<string, PmxAxIntent>();
-  private readonly vetoedIntentIds = new Map<string, number>();
-  private readonly committingIntentIds = new Set<string>();
+  private readonly board = createBoardLocal(
+    () => ({
+      intents: new Map<string, PmxAxIntent>(),
+      vetoedIntentIds: new Map<string, number>(),
+      committingIntentIds: new Set<string>(),
+      sweepTimer: null as ReturnType<typeof setInterval> | null,
+    }),
+    (state) => {
+      if (state.sweepTimer) clearInterval(state.sweepTimer);
+    },
+  );
+  private get intents() {
+    return this.board.current.intents;
+  }
+  private get vetoedIntentIds() {
+    return this.board.current.vetoedIntentIds;
+  }
+  private get committingIntentIds() {
+    return this.board.current.committingIntentIds;
+  }
   private emit: IntentEmitter = () => {};
-  private sweepTimer: ReturnType<typeof setInterval> | null = null;
+  private get sweepTimer() {
+    return this.board.current.sweepTimer;
+  }
+  private set sweepTimer(value: ReturnType<typeof setInterval> | null) {
+    this.board.current.sweepTimer = value;
+  }
 
   /** Inject the workbench SSE emitter (server.ts wires this at module load). */
   setEmitter(emitter: IntentEmitter | null): void {
@@ -118,6 +142,17 @@ export class IntentRegistry {
     return [...this.intents.values()];
   }
 
+  /** The first write from Home adopts its ghosts and vetoes without opening on signal. */
+  moveHomeIntentsToBoard(boardId: string): void {
+    const home = this.board.current;
+    canvasState.withBoard(boardId, () => {
+      for (const [id, intent] of home.intents) this.intents.set(id, intent);
+      for (const [id, expires] of home.vetoedIntentIds) this.vetoedIntentIds.set(id, expires);
+      this.ensureSweeper();
+    });
+    this.reset();
+  }
+
   /** Signal a new (or replace an existing) intent. Returns the stored envelope. */
   signal(raw: unknown): PmxAxIntent {
     const input = parseOrThrow(intentSignalSchema, raw, 'intent');
@@ -335,7 +370,10 @@ export class IntentRegistry {
 
   private ensureSweeper(): void {
     if (this.sweepTimer || this.intents.size === 0) return;
-    this.sweepTimer = setInterval(() => this.sweep(), 1000);
+    this.sweepTimer = setInterval(
+      canvasState.bindBoard(() => this.sweep()),
+      1000,
+    );
     // Don't keep the process (or a test runner) alive just for ghost expiry.
     (this.sweepTimer as { unref?: () => void }).unref?.();
   }

package/src/server/knowledge-lifecycle.ts

@@ -4,6 +4,7 @@ import { normalizeBoardFolder } from '../shared/boards.js';
 import { memoryKey, type MemoryTarget } from '../shared/memory-graph.js';
 import { currentActor, type ActorAttribution } from './attribution.js';
 import { OperationError } from './operations/types.js';
+import { CARD_HISTORY_CTE } from './card-relocation.js';
 import type { LifecycleQualification } from '../shared/lifecycle-status.js';
 import type { CanvasNodeState } from './canvas-state.js';
 import { RELATION_PRESETS, relationPresetSchema, type RelationPreset } from '../shared/relations.js';
@@ -281,15 +282,19 @@ export class KnowledgeLifecycle {
     if (!targets.length) return new Map();
     const rows = this.indexedDb()
       .query<{ boardId: string; nodeId: string; validation: string | null; retirement: string | null }, [string]>(
-        `WITH targets AS (
-         SELECT json_extract(value, '$.boardId') AS boardId, json_extract(value, '$.cardId') AS nodeId
-         FROM json_each(?)
-       ) SELECT boardId, nodeId,
-         (SELECT value FROM review_records WHERE board_id = boardId AND node_id = nodeId
+        `${CARD_HISTORY_CTE}
+       SELECT t.current_board AS boardId, t.node_id AS nodeId,
+         (SELECT value FROM review_records r JOIN history h
+          ON r.board_id = h.board_id AND r.node_id = h.node_id
+          AND r.sequence > h.review_after AND r.sequence <= h.review_through
+          WHERE h.current_board = t.current_board AND h.node_id = t.node_id
           AND ${validationPredicate} ORDER BY sequence DESC LIMIT 1) AS validation,
-         (SELECT json_extract(value, '$.outcome') FROM review_records WHERE board_id = boardId AND node_id = nodeId
+         (SELECT json_extract(value, '$.outcome') FROM review_records r JOIN history h
+          ON r.board_id = h.board_id AND r.node_id = h.node_id
+          AND r.sequence > h.review_after AND r.sequence <= h.review_through
+          WHERE h.current_board = t.current_board AND h.node_id = t.node_id
           AND ${retirementPredicate} ORDER BY sequence DESC LIMIT 1) AS retirement
-       FROM targets`,
+       FROM targets t`,
       )
       .all(JSON.stringify(targets));
     return new Map(
@@ -306,11 +311,29 @@ export class KnowledgeLifecycle {
     );
   }
 
+  /** Resolve a current card's location when evidence was recorded, without rewriting that evidence. */
+  locationAtReview(review: ReviewRecord, target: MemoryTarget): MemoryTarget {
+    const sequence = this.db()
+      .query<{ sequence: number }, [string, string, string]>(
+        "SELECT sequence FROM review_records WHERE board_id = ? AND node_id = ? AND json_extract(value, '$.id') = ?",
+      )
+      .get(review.boardId, review.nodeId, review.id)?.sequence;
+    if (sequence === undefined) return target;
+    const location = this.db()
+      .query<{ board_id: string }, [string, number, number]>(
+        `${CARD_HISTORY_CTE} SELECT board_id FROM history WHERE review_after < ? AND review_through >= ? LIMIT 1`,
+      )
+      .get(JSON.stringify([target]), sequence, sequence);
+    return location ? { ...target, boardId: location.board_id } : target;
+  }
+
   reviews(boardId: string, nodeId: string) {
     const records = (
       this.db()
-        .query('SELECT value FROM review_records WHERE board_id = ? AND node_id = ? ORDER BY sequence')
-        .all(boardId, nodeId) as { value: string }[]
+        .query(`${CARD_HISTORY_CTE} SELECT value FROM review_records r JOIN history h
+          ON r.board_id = h.board_id AND r.node_id = h.node_id
+          AND r.sequence > h.review_after AND r.sequence <= h.review_through ORDER BY sequence`)
+        .all(JSON.stringify([{ boardId, cardId: nodeId }])) as { value: string }[]
     ).map((r): ReviewRecord => {
       const record = JSON.parse(r.value) as ReviewRecord;
       return { ...record, contentRevision: record.contentRevision ?? null };

package/src/server/lifecycle-status.ts

@@ -11,6 +11,7 @@ const processStartedAt = Date.now();
 interface Source {
   key: string;
   target: MemoryTarget;
+  edge?: { owner: MemoryTarget; id: string };
   baseline?: number;
   kind: string;
   observedAt?: string;
@@ -179,6 +180,7 @@ export function lifecycleSnapshot(now = Date.now(), atUse: MemoryTarget[] = [],
       existing.push({
         key: JSON.stringify([board.id, edge.id, kind, memoryKey(target)]),
         target,
+        edge: { owner: from, id: edge.id },
         kind,
         baseline: edge.sourceRevision,
       });
@@ -219,13 +221,30 @@ export function lifecycleSnapshot(now = Date.now(), atUse: MemoryTarget[] = [],
       const current = cards.get(memoryKey(source.target));
       const revision = source.availability === 'unavailable' ? null : (current?.contentRevision ?? null);
       status.observations[source.key] = revision;
-      const observed = validation ? validation.sourceRevisions?.[source.key] : source.baseline;
+      let observed = validation ? validation.sourceRevisions?.[source.key] : source.baseline;
+      if (validation?.sourceRevisions && observed === undefined) {
+        const target = canvasState.knowledge.locationAtReview(validation, source.target);
+        const historicalKey = source.edge
+          ? JSON.stringify([
+              canvasState.knowledge.locationAtReview(validation, source.edge.owner).boardId,
+              source.edge.id,
+              source.kind,
+              memoryKey(target),
+            ])
+          : `provenance:${memoryKey(target)}`;
+        observed = validation.sourceRevisions[historicalKey];
+      }
       const title = current ? String(current.data.title ?? current.id) : 'Unavailable source';
+      const before = status.reasons.length;
       if (!current) status.reasons.push('A dependency source is unavailable; no fresh check.');
       else if (source.availability === 'unavailable')
         status.reasons.push(`${title}: source unavailable; cached content is not a fresh check.`);
       else if (observed !== revision || (!validation && ['contradicts', 'supersedes'].includes(source.kind)))
         status.reasons.push(`${source.kind}: ${title}${observed === undefined ? ' needs review' : ' changed'}.`);
+      if (status.reasons.length > before) {
+        status.sourceWarnings ??= {};
+        status.sourceWarnings[source.key] = status.reasons.slice(before);
+      }
     }
   }
   // Fixed point, not recursive traversal: cycles cannot overflow and unrelated links never propagate.
@@ -246,6 +265,15 @@ export function lifecycleSnapshot(now = Date.now(), atUse: MemoryTarget[] = [],
     }
   }
   for (const [key, status] of Object.entries(result)) {
+    for (const source of sources.get(key) ?? []) {
+      const upstream = result[memoryKey(source.target)];
+      if (upstream?.due || upstream?.retired) {
+        status.sourceWarnings ??= {};
+        status.sourceWarnings[source.key] ??= [
+          upstream.retired ? 'Source is retired.' : 'An explicit source needs review.',
+        ];
+      }
+    }
     const references: Source[] = [...(sources.get(key) ?? [])];
     const boardId = portals.get(key);
     if (boardId) {

package/src/server/mcp-app-runtime.ts

@@ -18,6 +18,7 @@ import { EXTENSION_ID, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps
 import type { McpUiClientCapabilities, McpUiResourceCsp, McpUiResourceMeta } from '@modelcontextprotocol/ext-apps';
 import { getToolUiResourceUri } from '@modelcontextprotocol/ext-apps/app-bridge';
 import { normalizeExtAppToolResult } from './ext-app-tool-result.js';
+import { canvasState } from './canvas-state.js';
 
 // A restriction follows async rehydration spawned by an embedded operation,
 // without disabling independent requests from the local workbench.
@@ -71,10 +72,12 @@ type RuntimeTransport = StdioClientTransport | StreamableHTTPClientTransport;
 
 interface McpAppSession {
   id: string;
+  board: object;
   serverName: string;
   client: Client;
   transport: RuntimeTransport;
   tools: Tool[];
+  unregisterBoardDispose: () => void;
 }
 
 const uiCapabilities: McpUiClientCapabilities = {
@@ -223,21 +226,35 @@ async function createSession(
   }
   const transport = buildTransport(transportConfig);
   const client = new Client({ name: 'pmx-canvas-app-host', version: '0.1.0' }, { capabilities: clientCapabilities });
-  await client.connect(transport, requestOptions(timeoutMs));
-
-  const toolList = await client.listTools(undefined, requestOptions(timeoutMs));
+  const id = randomId('mcp-app-session');
+  let disposed = false;
   const session: McpAppSession = {
-    id: randomId('mcp-app-session'),
+    id,
+    board: canvasState.boardIdentity,
     serverName: normalizeServerName(serverName, transportConfig),
     client,
     transport,
-    tools: toolList.tools,
+    tools: [],
+    unregisterBoardDispose: canvasState.onBoardDispose(() => {
+      disposed = true;
+      closeMcpAppSession(id);
+    }),
   };
   sessions.set(session.id, session);
-  return session;
+  try {
+    await client.connect(transport, requestOptions(timeoutMs));
+    const toolList = await client.listTools(undefined, requestOptions(timeoutMs));
+    if (disposed) throw new Error('The app board was deleted while connecting.');
+    session.tools = toolList.tools;
+    return session;
+  } catch (error) {
+    await closeSession(session);
+    throw error;
+  }
 }
 
 async function closeSession(session: McpAppSession): Promise<void> {
+  session.unregisterBoardDispose();
   sessions.delete(session.id);
   await session.transport.close();
 }
@@ -468,5 +485,7 @@ export function hasMcpAppSession(sessionId: string): boolean {
 }
 
 export function listMcpAppSessionIds(): string[] {
-  return [...sessions.keys()];
+  return [...sessions.values()]
+    .filter((session) => session.board === canvasState.boardIdentity)
+    .map((session) => session.id);
 }

package/src/server/mutation-history.ts

@@ -14,6 +14,7 @@
 
 import type { CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
 import { currentActor as getActor, setCurrentActor } from './attribution.js';
+import { createBoardLocal } from './board-local.js';
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -88,11 +89,25 @@ export interface SnapshotDiffResult {
   removedEdges: { id: string; from: string; to: string; toBoardId?: string; type: string }[];
 }
 
-function comparableNodeData(data: Record<string, unknown>): Record<string, unknown> {
+function comparableNodeData(data: Record<string, unknown>): string {
   const comparable = { ...data };
   delete comparable.title;
   delete comparable.content;
-  return comparable;
+  // Match content-revision semantics: fetching the same page again is not a
+  // content change. Keep authored timestamps elsewhere, including nested data.
+  delete comparable.fetchedAt;
+  if (comparable.provenance && typeof comparable.provenance === 'object') {
+    const provenance = { ...(comparable.provenance as Record<string, unknown>) };
+    delete provenance.syncedAt;
+    comparable.provenance = provenance;
+  }
+  // Canonical JSON preserves array order and the persisted JSON semantics for
+  // undefined properties, while ignoring object-key insertion order at any depth.
+  return JSON.stringify(comparable, (_key, value: unknown) =>
+    value && typeof value === 'object' && !Array.isArray(value)
+      ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+      : value,
+  );
 }
 
 // ── Ring Buffer ──────────────────────────────────────────────────────
@@ -100,11 +115,25 @@ function comparableNodeData(data: Record<string, unknown>): Record<string, unkno
 const MAX_ENTRIES = 200;
 
 class MutationHistory {
-  private entries: MutationEntry[] = [];
-  /** Index of the last applied mutation. -1 means nothing applied / all undone. */
-  private cursor = -1;
-  /** When true, mutations triggered by undo/redo are not recorded. */
-  private _replaying = false;
+  private readonly board = createBoardLocal(() => ({ entries: [] as MutationEntry[], cursor: -1, replaying: false }));
+  private get entries() {
+    return this.board.current.entries;
+  }
+  private set entries(value: MutationEntry[]) {
+    this.board.current.entries = value;
+  }
+  private get cursor() {
+    return this.board.current.cursor;
+  }
+  private set cursor(value: number) {
+    this.board.current.cursor = value;
+  }
+  private get _replaying() {
+    return this.board.current.replaying;
+  }
+  private set _replaying(value: boolean) {
+    this.board.current.replaying = value;
+  }
 
   get isReplaying(): boolean {
     return this._replaying;
@@ -315,7 +344,7 @@ export function diffLayouts(
       changes.push(`content changed (${lenDiff >= 0 ? '+' : ''}${lenDiff} chars)`);
     }
 
-    if (JSON.stringify(comparableNodeData(snapNode.data)) !== JSON.stringify(comparableNodeData(curNode.data))) {
+    if (comparableNodeData(snapNode.data) !== comparableNodeData(curNode.data)) {
       changes.push('data changed');
     }
 

package/src/server/operations/composites.ts

@@ -152,15 +152,17 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_board',
     description:
+      '"move-selection" previews or atomically relocates selected cards and group descendants to a new board, preserves identity and leaves a portal. Supply sourceBoardId, nodeIds, name, expectedRevision and requestId; preview:true reports blockers and the Undo/snapshot boundary. Retry identical input with the same requestId. It never opens the destination. ' +
       'Knowledge data: knowledge-list reads categories/folders/shared relation presets; category-set replaces category (id/name/glyph/decayType/rate/triggers/revalidationMethod); category-remove deletes an unused category by id (explicit folder assignments, including empty folders, refuse deletion); relation-preset-set saves preset (id/name/vocabulary); relation-preset-remove deletes a template without changing existing board vocabularies; folder-set replaces path/categoryId/lifecycleOverride (null inherits). These workspace actions never open a board and are refused under agent scope fences. ' +
       'Boards in this workspace — the library of the human\'s and your working memory, filed in folders on Home. Your writes always go to the open board (activeBoardId); on Home (no board open) your first write opens the most recent board, or a new one when there are none. Action "list" returns every board (with its folder), most recently opened first; "get" reads one (default: the open board); "create" makes a new empty board WITHOUT opening it (optional folder); "open" explicitly switches the server active board to id (null or omitted opens Home), changing the subsequent write target. Humans browsing Map/Graph stay in the library until they explicitly open a board/card; do not infer activeBoardId from their visible library. After creating a board, open its returned id and verify activeBoardId before writing; another participant can switch the board later. "update" renames a board, files it under a folder (folder "" 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. "pin" adds a board to the working set (its README and pinned cards reach your brief whichever board is open; optional reason), "unpin" removes it; a pinned board is read-only context, never a write target. Only the human deletes boards.',
     actionSummary:
-      'list | get | create | create-from | open | update | pin | unpin | knowledge-list | category-set | category-remove | relation-preset-set | relation-preset-remove | folder-set',
+      'list | get | create | create-from | move-selection | open | update | pin | unpin | knowledge-list | category-set | category-remove | relation-preset-set | relation-preset-remove | folder-set',
     actions: {
       list: 'board.list',
       get: 'board.get',
       create: 'board.create',
       'create-from': 'board.create-from',
+      'move-selection': 'board.move-selection',
       open: 'board.open',
       update: 'board.update',
       'knowledge-list': 'knowledge.list',
@@ -239,9 +241,9 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_view',
     description:
-      'Canvas viewport and layout control. Action "arrange" auto-lays-out nodes (grid/columns/etc.); "focus" pans/zooms the viewport to a node; "fit" zooms to fit all nodes in view; "clear" removes every node and edge from the canvas; "remove-annotation" deletes a human-drawn annotation by id; "get-tour"/"set-tour" read or persist the presentation tour; "tour-go" presents a stop (stop index or step next/previous); "tour-exit" leaves presentation; "move" eases the camera to a nodeId, world rect or viewport over a duration. Camera actions never enter undo history.',
+      'Canvas viewport and layout control. Action "arrange" auto-lays-out nodes (grid/columns/etc.); "focus" pans/zooms the viewport to a node; "fit" zooms to fit all nodes in view; "clear" removes every node and edge from the canvas; "add-annotation" draws freehand points or text in world coordinates; "remove-annotation" erases a whole mark by id; "get-tour"/"set-tour" read or persist the presentation tour; "tour-go" presents a stop (stop index or step next/previous); "tour-exit" leaves presentation; "move" eases the camera to a nodeId, world rect or viewport over a duration. Camera actions never enter undo history.',
     actionSummary:
-      'arrange | focus | fit | clear | remove-annotation | get-tour | set-tour | tour-go | tour-exit | move',
+      'arrange | focus | fit | clear | add-annotation | remove-annotation | get-tour | set-tour | tour-go | tour-exit | move',
     actions: {
       'get-tour': 'tour.get',
       'set-tour': 'tour.set',
@@ -252,6 +254,7 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
       focus: 'node.focus',
       fit: 'view.fit',
       clear: 'canvas.clear',
+      'add-annotation': 'annotation.add',
       'remove-annotation': 'annotation.remove',
     },
   },

package/src/server/operations/mcp-contracts.ts

@@ -86,6 +86,20 @@ const payloads: Record<string, ZodType> = {
     board,
     z.looseObject({ ok: z.boolean(), sourceBoardId: id, cards: z.array(node), edges: z.array(edge) }),
   ]),
+  'board.move-selection': z.union([
+    z.looseObject({
+      ok: z.boolean(),
+      preview: z.looseObject({ sourceBoardId: id, nodeIds: z.array(id), blockers: z.array(z.string()) }),
+    }),
+    z.looseObject({
+      ok: z.boolean(),
+      sourceBoardId: id,
+      destinationBoardId: id,
+      portalId: id,
+      nodeIds: z.array(id),
+      replayed: z.boolean(),
+    }),
+  ]),
   'board.open': boards,
   'board.update': boards,
   'board.pin': boards,
@@ -145,6 +159,7 @@ const payloads: Record<string, ZodType> = {
   'node.focus': z.looseObject({ ok: z.boolean(), focused: id, panned: z.boolean() }),
   'view.fit': z.looseObject({ ok: z.boolean(), viewport }),
   'canvas.clear': z.looseObject({ ok: z.boolean(), cleared: z.literal(true) }),
+  'annotation.add': entity('annotation'),
   'annotation.remove': ok,
   'context.get': z.looseObject({ version: z.literal(1), budgetUnit: z.literal('utf16-code-units') }),
   'memory-graph.get': z.looseObject({

package/src/server/operations/mcp.ts

@@ -36,6 +36,17 @@ export interface OperationToolHost extends OperationMcpToolHost {
   recordContextRead(read: ContextReadInput): Promise<void>;
 }
 
+const routingShape = {
+  targetBoardId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      'Execute on this board without changing the shared workbench view. Nested operations retain this target.',
+    ),
+  agentId: z.string().min(1).optional().describe('Stable agent/thread identity for attribution and scope fences.'),
+};
+
 function executionOptions(extra: RequestHandlerExtra<ServerRequest, ServerNotification>): OperationExecutionOptions {
   const progressToken = extra._meta?.progressToken;
   return {
@@ -58,9 +69,23 @@ async function invokeMcpOperation(
   options: OperationExecutionOptions,
 ) {
   options.signal?.throwIfAborted();
-  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) {
+  // buildInput may project operation-specific fields; routing belongs to the
+  // invocation and must also cover formatter follow-up reads and accounting.
+  const routing = {
+    ...(formatInput.targetBoardId !== undefined ? { targetBoardId: formatInput.targetBoardId } : {}),
+    ...(formatInput.agentId !== undefined ? { agentId: formatInput.agentId } : {}),
+  };
+  opInput = { ...opInput, ...routing };
+  if (typeof routing.agentId === 'string') consumer = routing.agentId;
+  const board =
+    typeof routing.targetBoardId === 'string'
+      ? routing.targetBoardId
+      : typeof opInput.board === 'string' && opInput.board.trim()
+        ? opInput.board.trim()
+        : undefined;
+  const preparesContext = op.name === 'context.get' && opInput.contextDelivery === false;
+  const readTarget = CONTEXT_READ_OPS.has(op.name) && !preparesContext ? await host.prepareContextRead(board) : null;
+  if (readTarget?.boardId && 'board' in op.inputShape && opInput.board === undefined) {
     opInput = { ...opInput, board: readTarget.boardId };
     formatInput = { ...formatInput, board: readTarget.boardId };
   }
@@ -70,8 +95,10 @@ async function invokeMcpOperation(
   // Preserve the host receiver, and bind options to formatter follow-up reads
   // (history flags, snapshot summary, streaming node metadata).
   const formatterHost: OperationMcpToolHost = {
-    getPinnedNodeIds: (target) => host.getPinnedNodeIds(target),
-    invoker: () => ({ invoke: (name, input, followUp) => invoker.invoke(name, input, { ...options, ...followUp }) }),
+    getPinnedNodeIds: (target) => host.getPinnedNodeIds(target ?? board),
+    invoker: () => ({
+      invoke: (name, input, followUp) => invoker.invoke(name, { ...input, ...routing }, { ...options, ...followUp }),
+    }),
   };
   const formatted = structuredOperationResult(
     op.name,
@@ -151,7 +178,7 @@ export function registerOperationTools(server: McpServer, getHost: () => Promise
         // successful over MCP while the same HTTP call 400'd (0.5.1 Amp
         // finding A). Loose parsing forwards unknown keys to the op layer,
         // the single authority on dead-field rejection, HTTP and MCP alike.
-        inputSchema: z.looseObject({ ...op.inputShape, ...(tool.extraShape ?? {}) }),
+        inputSchema: z.looseObject({ ...op.inputShape, ...(tool.extraShape ?? {}), ...routingShape }),
         outputSchema: operationOutputSchema([op.name]),
         annotations: operationToolAnnotations(tool.toolName),
       },
@@ -376,8 +403,8 @@ export function registerOperationHelpTool(server: McpServer): void {
       const composite = compositeToolDefinitions.find((def) => compositeMemberOps(def).includes(name));
       const publicName = (field: string) =>
         Object.entries(composite?.fieldRemap ?? {}).find(([, original]) => original === field)?.[0] ?? field;
-      const shape = Object.fromEntries(
-        Object.entries({ ...op.inputShape, ...op.mcp?.extraShape }).map(([field, schema]) => [
+      const shape: Record<string, ZodTypeAny> = Object.fromEntries(
+        Object.entries({ ...op.inputShape, ...op.mcp?.extraShape, ...routingShape }).map(([field, schema]) => [
           publicName(field),
           schema,
         ]),
@@ -444,7 +471,7 @@ export function registerCompositeTools(
       def.toolName,
       {
         description: def.description,
-        inputSchema: z.looseObject(buildCompositeShape(def)),
+        inputSchema: z.looseObject({ ...buildCompositeShape(def), ...routingShape }),
         outputSchema: operationOutputSchema(compositeMemberOps(def)),
         annotations: operationToolAnnotations(def.toolName),
       },

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

@@ -13,6 +13,7 @@
  *
  * This module must never import server.ts or index.ts.
  */
+import { isDeepStrictEqual } from 'node:util';
 import { z } from 'zod';
 import { canvasState, type CanvasAnnotation } from '../../canvas-state.js';
 import { summarizeCanvasAnnotation } from '../../canvas-serialization.js';
@@ -35,7 +36,7 @@ const annotationRemoveOperation = defineOperation<z.infer<typeof annotationRemov
   },
   mcp: {
     toolName: 'canvas_remove_annotation',
-    description: 'Remove a human-drawn canvas annotation by ID.',
+    description: 'Erase a whole canvas mark by ID, whether drawn by a human or agent.',
     extraShape: {
       id: z.string().describe('Annotation ID to remove'),
     },
@@ -119,6 +120,19 @@ const annotationAddOperation = defineOperation<z.infer<typeof annotationAddSchem
     method: 'POST',
     path: '/api/canvas/annotation',
   },
+  mcp: {
+    toolName: 'canvas_add_annotation',
+    description: 'Draw canvas ink or write a text note in world coordinates. No session required.',
+    extraShape: {
+      type: z.enum(['freehand', 'text']).optional(),
+      points: z.array(z.object({ x: z.number(), y: z.number() })).min(1),
+      width: z.number().optional(),
+      color: z.string().optional(),
+      label: z.string().optional(),
+      text: z.string().optional(),
+      id: z.string().optional(),
+    },
+  },
   handler: (input) => {
     const body: Record<string, unknown> = input;
     const type = body.type === 'text' ? 'text' : 'freehand';
@@ -164,6 +178,13 @@ const annotationAddOperation = defineOperation<z.infer<typeof annotationAddSchem
       createdAt: new Date().toISOString(),
     };
 
+    const existing = canvasState.getAnnotations().find((entry) => entry.id === id);
+    if (existing) {
+      if (!isDeepStrictEqual(existing, { ...annotation, createdAt: existing.createdAt })) {
+        throw new OperationError(`Annotation "${id}" already exists with different content.`, 409);
+      }
+      return { ok: true, annotation: summarizeCanvasAnnotation(existing) };
+    }
     canvasState.addAnnotation(annotation);
     return { ok: true, annotation: summarizeCanvasAnnotation(annotation) };
   },

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

@@ -69,6 +69,7 @@ function clampTimeoutMs(value: unknown): number {
 /** Accept the operation's timeoutMs as well as the direct HTTP waitMs spelling. */
 function readWaitMsInput(_req: Request, params: Record<string, string>, url: URL): Record<string, unknown> {
   return {
+    ...Object.fromEntries(url.searchParams),
     ...params,
     timeoutMs: clampTimeoutMs(url.searchParams.get('timeoutMs') ?? url.searchParams.get('waitMs') ?? ''),
   };