pmx-canvas 0.9.3 → 0.10.0

package/src/server/operations/mcp.ts

@@ -9,9 +9,17 @@
  */
 import { z, type ZodRawShape, type ZodTypeAny } from 'zod';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { ServerRequest, ServerNotification } from '@modelcontextprotocol/sdk/types.js';
 import { getOperation, listOperations } from './registry.js';
 import { agentSourceLabel, type OperationInvoker } from './invoker.js';
-import { OperationError, type Operation, type OperationMcpToolHost } from './types.js';
+import { OperationError, type Operation, type OperationMcpToolHost, type OperationExecutionOptions } from './types.js';
+import {
+  operationOutputSchema,
+  operationToolAnnotations,
+  operationToolError,
+  structuredOperationResult,
+} from './mcp-contracts.js';
 import {
   CONTEXT_READ_OPS,
   contextReadFromPayload,
@@ -28,23 +36,51 @@ export interface OperationToolHost extends OperationMcpToolHost {
   recordContextRead(read: ContextReadInput): Promise<void>;
 }
 
+function executionOptions(extra: RequestHandlerExtra<ServerRequest, ServerNotification>): OperationExecutionOptions {
+  const progressToken = extra._meta?.progressToken;
+  return {
+    signal: extra.signal,
+    ...(progressToken !== undefined
+      ? {
+          onProgress: (progress: Parameters<NonNullable<OperationExecutionOptions['onProgress']>>[0]) =>
+            extra.sendNotification({ method: 'notifications/progress', params: { ...progress, progressToken } }),
+        }
+      : {}),
+  };
+}
+
 async function invokeMcpOperation(
   host: OperationToolHost,
   op: Operation,
   opInput: Record<string, unknown>,
   formatInput: Record<string, unknown>,
   consumer: string | null,
+  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) {
     opInput = { ...opInput, board: readTarget.boardId };
     formatInput = { ...formatInput, board: readTarget.boardId };
   }
-  const result = await host.invoker().invoke(op.name, opInput);
-  const formatted = op.mcp?.formatResult
-    ? await op.mcp.formatResult(result, formatInput, host)
-    : { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+  options.signal?.throwIfAborted();
+  const invoker = host.invoker();
+  const result = await invoker.invoke(op.name, opInput, options);
+  // 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 }) }),
+  };
+  const formatted = structuredOperationResult(
+    op.name,
+    op.mcp?.formatResult
+      ? await op.mcp.formatResult(result, formatInput, formatterHost)
+      : { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] },
+  );
+  // Do not throwIfAborted here: batch may already have returned a partial
+  // outcome, and cancellation must never erase completed work from the reply.
   if (readTarget) {
     const text = formatted.content
       .filter((item): item is Extract<(typeof formatted.content)[number], { type: 'text' }> => item.type === 'text')
@@ -116,17 +152,24 @@ export function registerOperationTools(server: McpServer, getHost: () => Promise
         // 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 ?? {}) }),
+        outputSchema: operationOutputSchema([op.name]),
+        annotations: operationToolAnnotations(tool.toolName),
       },
-      async (input: Record<string, unknown>) => {
+      async (input: Record<string, unknown>, extra) => {
         try {
           const host = await getHost();
+          extra.signal.throwIfAborted();
           const opInput = tool.buildInput ? tool.buildInput(input) : input;
-          return await invokeMcpOperation(host, op, opInput, input, server.server.getClientVersion()?.name ?? null);
+          return await invokeMcpOperation(
+            host,
+            op,
+            opInput,
+            input,
+            server.server.getClientVersion()?.name ?? null,
+            executionOptions(extra),
+          );
         } catch (error) {
-          return {
-            content: [{ type: 'text' as const, text: error instanceof Error ? error.message : String(error) }],
-            isError: true,
-          };
+          return operationToolError(error);
         }
       },
     );
@@ -295,6 +338,88 @@ function requiredMcpFields(op: Operation): string[] {
   return keys;
 }
 
+/** Registry metadata only: never boots a canvas or records a content read. */
+export function registerOperationHelpTool(server: McpServer): void {
+  const folded = compositeFoldedOpNames();
+  server.registerTool(
+    'canvas_help',
+    {
+      description:
+        'Look up an MCP operation by registry name (e.g. node.add, ax.approval.request). Returns its public tool, argument schema and guidance. Omit op to list operation names. Does not execute operations or read canvas content.',
+      inputSchema: z.object({ op: z.string().min(1).optional() }),
+      outputSchema: z.object({
+        result: z.union([
+          z.strictObject({ operations: z.array(z.string()) }),
+          z.strictObject({
+            operation: z.string(),
+            tool: z.string(),
+            description: z.string(),
+            inputSchema: z.record(z.string(), z.unknown()),
+          }),
+        ]),
+      }),
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    ({ op: name }) => {
+      const operations = listOperations().filter((op) => op.mcp || folded.has(op.name));
+      if (name === undefined) {
+        const result = { operations: operations.map((op) => op.name).sort() };
+        return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: { result } };
+      }
+      const op = operations.find((op) => op.name === name);
+      if (!op) {
+        return {
+          content: [{ type: 'text', text: `Unknown MCP operation "${name}". Omit op to list available operations.` }],
+          isError: true,
+        };
+      }
+      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]) => [
+          publicName(field),
+          schema,
+        ]),
+      );
+      if (composite?.resolveOp) {
+        // Resolve the same kind/action matrix used by composite dispatch.
+        const kinds = composite.extraDiscriminatorShape?.kind;
+        if (!(kinds instanceof z.ZodEnum)) throw new Error(`Missing kind enum for ${composite.toolName}.`);
+        for (const kind of kinds.options) {
+          for (const action of composite.actionEnum ?? []) {
+            if (composite.resolveOp({ kind: String(kind), action }) === name) {
+              shape.kind = z.literal(kind);
+              shape.action = z.literal(action);
+            }
+          }
+        }
+      } else if (composite) {
+        const action = Object.entries(composite.actions).find(([, operation]) => operation === name)![0];
+        shape.action = z.literal(action);
+      }
+      const inputSchema = z.toJSONSchema(z.looseObject(shape), { target: 'draft-7', io: 'input' });
+      // Mirror dispatch's required-name alternatives rather than demanding both names.
+      for (const [field, aliases] of Object.entries(REQUIRED_FIELD_ALIASES[name] ?? {})) {
+        const key = publicName(field);
+        if (!inputSchema.required?.includes(key)) continue;
+        inputSchema.required = inputSchema.required.filter((required) => required !== key);
+        inputSchema.allOf = [
+          ...(inputSchema.allOf ?? []),
+          { anyOf: [key, ...aliases.map(publicName)].map((alternative) => ({ required: [alternative] })) },
+        ];
+      }
+      const result = {
+        operation: name,
+        tool: composite?.toolName ?? op.mcp!.toolName,
+        description: op.mcp?.description ?? composite!.description,
+        inputSchema,
+      };
+      return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: { result } };
+    },
+  );
+}
+
 /**
  * Register composite (action-discriminated) MCP tools (plan-006). Each action
  * dispatches to a registered operation, reusing that op's `mcp.buildInput` and
@@ -317,10 +442,16 @@ export function registerCompositeTools(
     // must reach the op layer's dead-field rejection instead of being stripped.
     server.registerTool(
       def.toolName,
-      { description: def.description, inputSchema: z.looseObject(buildCompositeShape(def)) },
-      async (input: Record<string, unknown>) => {
+      {
+        description: def.description,
+        inputSchema: z.looseObject(buildCompositeShape(def)),
+        outputSchema: operationOutputSchema(compositeMemberOps(def)),
+        annotations: operationToolAnnotations(def.toolName),
+      },
+      async (input: Record<string, unknown>, extra) => {
         try {
           const host = await getHost();
+          extra.signal.throwIfAborted();
           const opName = resolveCompositeOp(def, input);
           const op = getOperation(opName);
           // Strip the composite discriminators (action + any extra, e.g. `kind`)
@@ -335,12 +466,16 @@ export function registerCompositeTools(
             );
           }
           const opInput = op.mcp?.buildInput ? op.mcp.buildInput(rest) : rest;
-          return await invokeMcpOperation(host, op, opInput, rest, server.server.getClientVersion()?.name ?? null);
+          return await invokeMcpOperation(
+            host,
+            op,
+            opInput,
+            rest,
+            server.server.getClientVersion()?.name ?? null,
+            executionOptions(extra),
+          );
         } catch (error) {
-          return {
-            content: [{ type: 'text' as const, text: error instanceof Error ? error.message : String(error) }],
-            isError: true,
-          };
+          return operationToolError(error);
         }
       },
     );

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

@@ -39,11 +39,7 @@
  *    the legacy error body — server-api only reads `missing.status`.
  *
  * Documented behavior change (accepted long-poll tradeoff, plan-007 sub-slice):
- *  - The legacy HTTP handler passed `req.signal` to waitForAxResolution, so a
- *    client disconnect aborted the wait early. The registry handler has no access
- *    to the HTTP Request, so the wait now runs to its (≤120s, subscription-based,
- *    cheap) timeout instead of aborting on disconnect. Resolution detection,
- *    timeout, and the `{ value, pending }` result are otherwise identical.
+ *  - Request cancellation rejects the wait and disposes its subscription/timer.
  *  - Remote-MCP only (daemon mode, untested for these reads): the legacy
  *    RemoteCanvasAccess.await* methods special-cased a 404 → `{ <key>:null }`. The
  *    generic HttpOperationInvoker throws on 404, so an await-on-missing over a
@@ -70,9 +66,12 @@ function clampTimeoutMs(value: unknown): number {
   return Math.min(ms, AX_WAIT_MAX_MS);
 }
 
-/** HTTP `?waitMs` → `timeoutMs`; absent/non-positive ⇒ 0 (plain read). Matches parseAxWaitMs. */
+/** 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 { ...params, timeoutMs: clampTimeoutMs(url.searchParams.get('waitMs') ?? '') };
+  return {
+    ...params,
+    timeoutMs: clampTimeoutMs(url.searchParams.get('timeoutMs') ?? url.searchParams.get('waitMs') ?? ''),
+  };
 }
 
 /** MCP buildInput: forward id + timeoutMs (omitted ⇒ 30000), clamped to [0, max]. */
@@ -131,13 +130,16 @@ const axApprovalGetOperation = defineOperation<z.infer<typeof awaitInputSchema>,
       };
     },
   },
-  handler: async (input) => {
+  handler: async (input, ctx) => {
     const id = typeof input.id === 'string' ? input.id : '';
+    await ctx.onProgress?.({ progress: 0, total: 1, message: 'Waiting for approval' });
     const { value, pending } = await waitForAxResolution<PmxAxApprovalGate>({
       read: () => canvasState.getApproval(id),
       isResolved: (g) => g.status !== 'pending',
       timeoutMs: clampTimeoutMs(input.timeoutMs),
+      signal: ctx.signal,
     });
+    await ctx.onProgress?.({ progress: 1, total: 1, message: pending ? 'Wait timed out' : 'Wait complete' });
     return { ok: value !== null, approvalGate: value, pending } as unknown as Record<string, unknown>;
   },
 });
@@ -170,13 +172,16 @@ const axElicitationGetOperation = defineOperation<z.infer<typeof awaitInputSchem
       };
     },
   },
-  handler: async (input) => {
+  handler: async (input, ctx) => {
     const id = typeof input.id === 'string' ? input.id : '';
+    await ctx.onProgress?.({ progress: 0, total: 1, message: 'Waiting for elicitation' });
     const { value, pending } = await waitForAxResolution<PmxAxElicitation>({
       read: () => canvasState.getElicitation(id),
       isResolved: (e) => e.status !== 'pending',
       timeoutMs: clampTimeoutMs(input.timeoutMs),
+      signal: ctx.signal,
     });
+    await ctx.onProgress?.({ progress: 1, total: 1, message: pending ? 'Wait timed out' : 'Wait complete' });
     return { ok: value !== null, elicitation: value, pending } as unknown as Record<string, unknown>;
   },
 });
@@ -209,13 +214,16 @@ const axModeGetOperation = defineOperation<z.infer<typeof awaitInputSchema>, Rec
       };
     },
   },
-  handler: async (input) => {
+  handler: async (input, ctx) => {
     const id = typeof input.id === 'string' ? input.id : '';
+    await ctx.onProgress?.({ progress: 0, total: 1, message: 'Waiting for mode resolution' });
     const { value, pending } = await waitForAxResolution<PmxAxModeRequest>({
       read: () => canvasState.getModeRequest(id),
       isResolved: (m) => m.status !== 'pending',
       timeoutMs: clampTimeoutMs(input.timeoutMs),
+      signal: ctx.signal,
     });
+    await ctx.onProgress?.({ progress: 1, total: 1, message: pending ? 'Wait timed out' : 'Wait complete' });
     return { ok: value !== null, modeRequest: value, pending } as unknown as Record<string, unknown>;
   },
 });

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

@@ -335,6 +335,8 @@ const interactionOperation = defineOperation<z.infer<typeof interactionSchema>,
   http: {
     method: 'POST',
     path: '/api/canvas/ax/interaction',
+    // MCP preserves the structured rejection code as well as its message.
+    errorBodyAsResult: true,
     // Legacy wire: 200 when accepted, the envelope's own status when refused.
     status: (result) =>
       isRecord(result) && result.ok !== true && typeof result.status === 'number' ? result.status : 200,

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

@@ -341,7 +341,7 @@ const axDeliveryPendingOperation = defineOperation<z.infer<typeof axDeliveryPend
     // `consumer` is a loop-safety scope, not a source label — never defaulted.
     formatResult: axJsonResult,
   },
-  handler: async (input) => {
+  handler: async (input, ctx) => {
     const consumer = typeof input.consumer === 'string' ? input.consumer : undefined;
     // A claim is proof this consumer polls steering — its presence (session or
     // external writer) becomes a legitimate composer steer target.
@@ -363,7 +363,7 @@ const axDeliveryPendingOperation = defineOperation<z.infer<typeof axDeliveryPend
       // Long-poll: hosts that cannot be woken from outside (Copilot, Codex —
       // their model runs only while the host gives it a turn) park here and
       // wake the moment steering lands, instead of burning the turn polling.
-      await waitForAxCondition({ ready: () => readPending().length > 0, timeoutMs });
+      await waitForAxCondition({ ready: () => readPending().length > 0, timeoutMs, signal: ctx.signal });
       pending = readPending();
     }
     // The MCP tool aggregated pendingActivity; one wire body now serves it over

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

@@ -44,6 +44,7 @@ export interface BatchEnvelope {
   refs: Record<string, unknown>;
   failedIndex?: number;
   error?: string;
+  cancelled?: boolean;
 }
 
 const SUPPORTED_BATCH_OPS = new Set([
@@ -220,7 +221,7 @@ function shapeBatchEntry(op: string, result: unknown, creationReceipt = false):
   return body;
 }
 
-async function runBatch(operations: BatchEntry[]): Promise<BatchEnvelope> {
+async function runBatch(operations: BatchEntry[], ctx: OperationContext): Promise<BatchEnvelope> {
   const refs: Record<string, unknown> = {};
   const results: Array<Record<string, unknown>> = [];
 
@@ -231,6 +232,15 @@ async function runBatch(operations: BatchEntry[]): Promise<BatchEnvelope> {
       return { ok: false, failedIndex: index, error: `Operation ${index} has invalid args.`, results, refs };
     }
     try {
+      ctx.signal?.throwIfAborted();
+      if (ctx.onProgress) {
+        const boardGeneration = canvasState.boardGeneration;
+        await ctx.onProgress({ progress: index, total: operations.length, message: operation.op });
+        if (canvasState.boardGeneration !== boardGeneration) {
+          throw new Error('The board changed while the batch was running.');
+        }
+      }
+      ctx.signal?.throwIfAborted();
       if (!SUPPORTED_BATCH_OPS.has(operation.op)) {
         return {
           ok: false,
@@ -259,35 +269,43 @@ async function runBatch(operations: BatchEntry[]): Promise<BatchEnvelope> {
       // ghost-cursor exemption for batch operations). No `fromWorkbench`: the
       // browser never issues batches, so inner writes are agent writes and the
       // scope fence applies to each of them.
-      const pending = executeOperation(dispatch.name, dispatch.args, { suppressAutoGhost: true });
+      const pending = executeOperation(dispatch.name, dispatch.args, {
+        suppressAutoGhost: true,
+        signal: ctx.signal,
+        onProgress: ctx.onProgress
+          ? (progress) => ctx.onProgress!({ progress: index, total: operations.length, message: progress.message })
+          : undefined,
+      });
       // The first write may synchronously open a board from Home. Capture after
       // dispatch, then refuse to continue a partially completed batch elsewhere.
       const boardGeneration = canvasState.boardGeneration;
       const raw = await pending;
-      if (canvasState.boardGeneration !== boardGeneration) {
-        throw new Error('The board changed while the batch was running.');
-      }
+      const boardChanged = canvasState.boardGeneration !== boardGeneration;
       const result = shapeBatchEntry(
         operation.op,
         raw,
-        ['node.add', 'group.create', 'edge.add'].includes(operation.op) &&
-          (args.requestId !== undefined || args.destinationBoardId !== undefined),
+        boardChanged ||
+          (['node.add', 'group.create', 'edge.add'].includes(operation.op) &&
+            (args.requestId !== undefined || args.destinationBoardId !== undefined)),
       );
       results.push(result);
       if (typeof operation.assign === 'string' && operation.assign.trim().length > 0) {
         refs[operation.assign] = result;
       }
+      if (boardChanged) throw new Error('The board changed while the batch was running.');
     } catch (error) {
       return {
         ok: false,
         failedIndex: index,
         error: error instanceof Error ? error.message : String(error),
+        ...(ctx.signal?.aborted ? { cancelled: true } : {}),
         results,
         refs,
       };
     }
   }
 
+  await ctx.onProgress?.({ progress: operations.length, total: operations.length, message: 'Batch complete' });
   return { ok: true, results, refs };
 }
 
@@ -356,6 +374,7 @@ function compactBatchResult(result: BatchEnvelope): Record<string, unknown> {
     ok: result.ok,
     ...(result.failedIndex !== undefined ? { failedIndex: result.failedIndex } : {}),
     ...(result.error ? { error: result.error } : {}),
+    ...(result.cancelled ? { cancelled: true } : {}),
     results: result.results.map((entry) => compactBatchValue(entry)),
     refs: Object.fromEntries(Object.entries(result.refs).map(([key, value]) => [key, compactBatchValue(value)])),
   };
@@ -406,7 +425,7 @@ const batchOperation = defineOperation<z.infer<typeof batchSchema>, BatchEnvelop
     // Suppress every per-entry SSE frame (auto layout emit + each handler's
     // ctx.emit). After the loop completes, emit ONE final canvas-layout-update.
     const revision = canvasState.getContentRevision().revision;
-    const envelope = await runWithSuppressedEmits(() => runBatch(operations));
+    const envelope = await runWithSuppressedEmits(() => runBatch(operations, ctx));
     if (
       revision !== canvasState.getContentRevision().revision ||
       operations.some(

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

@@ -633,6 +633,7 @@ async function createWebpageNode(body: Record<string, unknown>, ctx: OperationCo
 
   const extraData = isRecord(body.data) ? body.data : undefined;
   const geometry = resolveCreateGeometry(body);
+  ctx.signal?.throwIfAborted();
   const { id, node, sizeAdjustment } = addCanvasNode({
     type: 'webpage',
     ...(typeof body.title === 'string' ? { title: body.title } : {}),
@@ -648,7 +649,21 @@ async function createWebpageNode(body: Record<string, unknown>, ctx: OperationCo
   // registry emits the final layout update after the handler returns.
   ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
   const boardGeneration = canvasState.boardGeneration;
-  const refreshed = await refreshCanvasWebpageNode(id);
+  let refreshed: Awaited<ReturnType<typeof refreshCanvasWebpageNode>>;
+  try {
+    refreshed = await refreshCanvasWebpageNode(id, { signal: ctx.signal });
+  } catch (error) {
+    if (!ctx.signal?.aborted) throw error;
+    // Creation already committed. Return its receipt without writing an error
+    // status; batches retain this node and stop before their next entry.
+    return {
+      node,
+      extras: {
+        fetch: { ok: false, cancelled: true, error: 'Webpage fetch cancelled.' },
+        ...(sizeAdjustment ? { sizeAdjustment } : {}),
+      },
+    };
+  }
   if (canvasState.boardGeneration !== boardGeneration) {
     throw new OperationError('The board changed while the webpage was loading.', 409);
   }
@@ -1186,7 +1201,7 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
           throw new OperationError(error instanceof Error ? error.message : 'Invalid webpage URL.');
         }
       }
-      const result = await refreshCanvasWebpageNode(id, { ...(url ? { url } : {}) });
+      const result = await refreshCanvasWebpageNode(id, { ...(url ? { url } : {}), signal: ctx.signal });
       return result as unknown as Record<string, unknown>;
     }
 
@@ -1442,7 +1457,7 @@ const nodeRefreshOperation = defineOperation<z.infer<typeof nodeRefreshSchema>,
     }
     // Legacy wire: the layout update fires after every completed refresh
     // attempt, success or failure (the node may have partial refresh state).
-    const result = await refreshCanvasWebpageNode(nodeId, { ...(url ? { url } : {}) });
+    const result = await refreshCanvasWebpageNode(nodeId, { ...(url ? { url } : {}), signal: ctx.signal });
     ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
     return result as unknown as Record<string, unknown>;
   },

package/src/server/operations/registry.ts

@@ -20,7 +20,7 @@ import type { MemoryGraph } from '../../shared/memory-graph.js';
 import { openBoardForWrite } from '../canvas-operations.js';
 import { boardsPayload } from './ops/boards.js';
 import type { PmxAxIntent, PmxAxIntentKind } from '../../shared/ax-intent.js';
-import { OperationError, type Operation, type OperationContext } from './types.js';
+import { OperationError, type Operation, type OperationContext, type OperationExecutionOptions } from './types.js';
 
 const operations = new Map<string, Operation>();
 
@@ -75,8 +75,6 @@ export async function runWithSuppressedEmits<T>(fn: () => Promise<T>): Promise<T
   return suppressedEmits.run(true, fn);
 }
 
-const operationContext: OperationContext = { emit: emitOperationEvent };
-
 const INTENT_KINDS_BY_OPERATION: Record<string, readonly PmxAxIntentKind[]> = {
   'node.add': ['create'],
   'jsonrender.add': ['create'],
@@ -204,7 +202,7 @@ function autoGhostInput(name: string, rawInput: unknown, kind: string): Record<s
   }
 }
 
-export interface ExecuteOperationMeta {
+export interface ExecuteOperationMeta extends OperationExecutionOptions {
   /**
    * Skip the synthesized auto-ghost: set by the workbench's own HTTP calls
    * (a human dragging a node is not agent activity) and by canvas.batch for
@@ -395,6 +393,8 @@ export async function executeOperation(
   rawInput: unknown,
   meta: ExecuteOperationMeta = {},
 ): Promise<unknown> {
+  // Check before attribution, board auto-open, ghosts, or any handler writes.
+  meta.signal?.throwIfAborted();
   // Attribution follows this call chain across awaits and nested operations.
   const inputAgentId = asRecord(rawInput).agentId;
   return withCurrentActor(
@@ -479,6 +479,22 @@ function needsOpenBoard(op: Operation): boolean {
 }
 
 async function executeOperationInner(name: string, rawInput: unknown, meta: ExecuteOperationMeta): Promise<unknown> {
+  meta.signal?.throwIfAborted();
+  const operationContext: OperationContext = {
+    emit: emitOperationEvent,
+    signal: meta.signal,
+    // Progress is observational. A disconnected observer must not erase the
+    // receipt of a completed write or strand a batch's final layout emit.
+    onProgress: meta.onProgress
+      ? async (progress) => {
+          try {
+            await meta.onProgress!(progress);
+          } catch (error) {
+            if (!meta.signal?.aborted) console.error(`[operation] progress callback failed for ${name}:`, error);
+          }
+        }
+      : undefined,
+  };
   const op = getOperation(name);
   const storedCreation =
     ['node.add', 'group.create', 'edge.add'].includes(name) &&
@@ -543,6 +559,7 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
   }
   if (storedCreation) {
     const revision = canvasState.getContentRevision().revision;
+    meta.signal?.throwIfAborted();
     const result = await op.execute(rawInput, operationContext);
     const destination = asRecord(rawInput).destinationBoardId ?? canvasState.activeBoardId;
     if (destination === canvasState.activeBoardId || revision !== canvasState.getContentRevision().revision)
@@ -566,6 +583,7 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
       intentId,
       allowedKinds!,
       async () => {
+        meta.signal?.throwIfAborted();
         const result = await op.execute(input, operationContext);
         if (op.mutates) {
           emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
@@ -606,6 +624,7 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
     if (ghost) {
       const ghostId = ghost.id;
       try {
+        meta.signal?.throwIfAborted();
         const result = await op.execute(rawInput, operationContext);
         if (op.mutates) emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
         intentRegistry.clear(ghostId, { settledNodeId: settledNodeId(result, ghost) ?? undefined });
@@ -621,6 +640,7 @@ async function executeOperationInner(name: string, rawInput: unknown, meta: Exec
   const beforeBoard = canvasState.activeBoardId;
   const beforeRevision =
     name === 'board.create-from' || name === 'board.delete' ? canvasState.getContentRevision().revision : null;
+  meta.signal?.throwIfAborted();
   const result = await op.execute(rawInput, operationContext);
   // Library writes can invalidate relations on the open board without being
   // layout mutations themselves. Publish those clocks once, after the write.

package/src/server/operations/types.ts

@@ -29,7 +29,19 @@ export class OperationError extends Error {
   }
 }
 
-export interface OperationContext {
+export interface OperationProgress {
+  progress: number;
+  total?: number;
+  message?: string;
+}
+
+/** Cooperative cancellation: completed writes are never rolled back. */
+export interface OperationExecutionOptions {
+  signal?: AbortSignal;
+  onProgress?: (progress: OperationProgress) => void | Promise<void>;
+}
+
+export interface OperationContext extends OperationExecutionOptions {
   /** Emit a workbench SSE event (e.g. extra `canvas-layout-update` frames, focus, viewport). */
   emit(event: string, payload?: Record<string, unknown>): void;
 }
@@ -67,7 +79,9 @@ export interface OperationMcpToolHost {
    * Used by formatters that need a follow-up read (undo/redo history flags,
    * restore summary).
    */
-  invoker(): { invoke(name: string, input: Record<string, unknown>): Promise<unknown> };
+  invoker(): {
+    invoke(name: string, input: Record<string, unknown>, options?: OperationExecutionOptions): Promise<unknown>;
+  };
 }
 
 export interface OperationMcpTool {

package/src/server/server.ts

@@ -930,6 +930,15 @@ let workbenchEventSeq = 0;
 const workbenchEventRing: Array<{ seq: number; event: string; payload: PrimaryWorkbenchEventPayload }> = [];
 const workbenchPollWaiters = new Set<() => void>();
 let remoteEdgesSignature = '';
+const workbenchEventListeners = new Set<(event: string) => void>();
+
+/** In-process invalidation observers share the same events as daemon SSE clients. */
+export function onWorkbenchEvent(listener: (event: string) => void): () => void {
+  workbenchEventListeners.add(listener);
+  return () => {
+    workbenchEventListeners.delete(listener);
+  };
+}
 
 function broadcastWorkbenchEvent(event: string, payload: PrimaryWorkbenchEventPayload): void {
   let remoteEdgesChanged = false;
@@ -975,6 +984,7 @@ function broadcastWorkbenchEvent(event: string, payload: PrimaryWorkbenchEventPa
       syncCanvasBrowserOpenedFromSubscribers();
     }
   }
+  for (const listener of workbenchEventListeners) listener(event);
   if (remoteEdgesChanged) emitPrimaryWorkbenchEvent('boards-changed', boardsPayload());
 }