pmx-canvas 0.9.3 → 0.10.0

package/src/server/operations/http.ts

@@ -8,7 +8,7 @@
  */
 import { executeOperation, listOperations } from './registry.js';
 import { SOURCE_LABEL_RE } from '../agent-presence.js';
-import { OperationError } from './types.js';
+import { OperationError, type OperationExecutionOptions, type OperationProgress } from './types.js';
 import { isWorkbenchToken, refuseStaleWorkbenchWrite } from '../workbench-auth.js';
 
 function responseJson(data: unknown, status = 200): Response {
@@ -20,6 +20,57 @@ function responseJson(data: unknown, status = 200): Response {
   });
 }
 
+/** Opt-in NDJSON; the terminal frame retains the ordinary HTTP status/body. */
+export type OperationStreamFrame =
+  | { type: 'progress'; progress: OperationProgress }
+  | { type: 'result'; status: number; body: unknown };
+
+function operationFailure(name: string, error: unknown, signal: AbortSignal): Response {
+  if (signal.aborted) return responseJson({ ok: false, cancelled: true, error: 'Operation cancelled.' }, 499);
+  if (error instanceof OperationError) {
+    return responseJson({ ok: false, error: error.message, ...(error.details ?? {}) }, error.status);
+  }
+  // Keep unexpected errors server-side, never leak a Bun development overlay.
+  console.error(`[operation] unhandled error dispatching ${name}:`, error);
+  return responseJson({ ok: false, error: 'Internal error processing the request.' }, 500);
+}
+
+function progressResponse(
+  req: Request,
+  name: string,
+  run: (options: OperationExecutionOptions) => Promise<Response>,
+): Response {
+  const cancelled = new AbortController();
+  const signal = AbortSignal.any([req.signal, cancelled.signal]);
+  const encoder = new TextEncoder();
+  let closed = false;
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const send = (frame: OperationStreamFrame): void => {
+        if (!closed) controller.enqueue(encoder.encode(`${JSON.stringify(frame)}\n`));
+      };
+      let response: Response;
+      try {
+        response = await run({ signal, onProgress: (progress) => send({ type: 'progress', progress }) });
+      } catch (error) {
+        response = operationFailure(name, error, signal);
+      }
+      if (!closed) {
+        send({ type: 'result', status: response.status, body: await response.json() });
+        closed = true;
+        controller.close();
+      }
+    },
+    cancel() {
+      closed = true;
+      cancelled.abort();
+    },
+  });
+  return new Response(stream, {
+    headers: { 'Content-Type': 'application/x-ndjson', 'Cache-Control': 'no-store', 'X-Accel-Buffering': 'no' },
+  });
+}
+
 export function matchOperationPath(template: string, pathname: string): Record<string, string> | null {
   const templateSegments = template.split('/');
   const pathSegments = pathname.split('/');
@@ -83,6 +134,7 @@ export async function dispatchOperationRoute(req: Request, url: URL): Promise<Re
     const params = matchOperationPath(route.path, url.pathname);
     if (!params) continue;
     try {
+      req.signal.throwIfAborted();
       const input = route.readInput
         ? await route.readInput(req, params, url)
         : await readOperationInput(req, params, url);
@@ -100,27 +152,23 @@ export async function dispatchOperationRoute(req: Request, url: URL): Promise<Re
       // HTTP callers read as 'api'.
       const sourceHeader = req.headers.get('x-pmx-source');
       const source = sourceHeader && SOURCE_LABEL_RE.test(sourceHeader) ? sourceHeader : 'api';
-      const result = await executeOperation(op.name, input, {
-        // The legacy marker remains a UI-policy signal (ghost suppression).
-        // Only the unguessable boot token classifies authorship as human.
-        suppressAutoGhost: workbenchMarked,
-        fromWorkbench: workbenchMarked,
-        humanAuthor,
-        source,
-        proxiedRead: req.headers.get('x-pmx-proxied-read') === '1',
-      });
-      return responseJson(result, route.status ? route.status(result) : 200);
+      const run = async (options: OperationExecutionOptions): Promise<Response> => {
+        const result = await executeOperation(op.name, input, {
+          ...options,
+          // The legacy marker remains a UI-policy signal (ghost suppression).
+          // Only the unguessable boot token classifies authorship as human.
+          suppressAutoGhost: workbenchMarked,
+          fromWorkbench: workbenchMarked,
+          humanAuthor,
+          source,
+          proxiedRead: req.headers.get('x-pmx-proxied-read') === '1',
+        });
+        return responseJson(result, route.status ? route.status(result) : 200);
+      };
+      if (req.headers.get('accept') === 'application/x-ndjson') return progressResponse(req, op.name, run);
+      return await run({ signal: req.signal });
     } catch (error) {
-      if (error instanceof OperationError) {
-        return responseJson({ ok: false, error: error.message, ...(error.details ?? {}) }, error.status);
-      }
-      // An unexpected (non-OperationError) throw from a handler MUST NOT escape the
-      // dispatcher: Bun.serve has no per-request boundary, so an escaped throw renders
-      // its dev error overlay (HTTP 500 text/html leaking the absolute server source
-      // path + stack). Return a clean JSON 500 with a generic message instead (the
-      // real error is logged server-side, never echoed to the client).
-      console.error(`[operation] unhandled error dispatching ${op.name}:`, error);
-      return responseJson({ ok: false, error: 'Internal error processing the request.' }, 500);
+      return operationFailure(op.name, error, req.signal);
     }
   }
   return null;

package/src/server/operations/index.ts

@@ -77,7 +77,12 @@ export { runCanvasBatchOperation, type BatchEnvelope } from './ops/batch.js';
 // OpenMcpAppCoreResult is the SDK's cast target for executeOperation('mcpapp.open').
 export type { OpenMcpAppCoreResult } from './ops/app.js';
 export { LocalOperationInvoker, HttpOperationInvoker, type OperationInvoker } from './invoker.js';
-export { registerOperationTools, registerCompositeTools, type OperationToolHost } from './mcp.js';
+export {
+  registerOperationTools,
+  registerCompositeTools,
+  registerOperationHelpTool,
+  type OperationToolHost,
+} from './mcp.js';
 export { compositeToolDefinitions, type CompositeToolDefinition } from './composites.js';
 export {
   OperationError,
@@ -85,5 +90,7 @@ export {
   type Operation,
   type OperationContext,
   type OperationDefinition,
+  type OperationExecutionOptions,
   type OperationErrorStatus,
+  type OperationProgress,
 } from './types.js';

package/src/server/operations/invoker.ts

@@ -5,10 +5,11 @@
  */
 import { SOURCE_LABEL_RE } from '../agent-presence.js';
 import { executeOperation, getOperation } from './registry.js';
-import { OperationError, type OperationErrorStatus } from './types.js';
+import { OperationError, type OperationErrorStatus, type OperationExecutionOptions } from './types.js';
+import type { OperationStreamFrame } from './http.js';
 
 export interface OperationInvoker {
-  invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
+  invoke(name: string, input: Record<string, unknown>, options?: OperationExecutionOptions): Promise<unknown>;
 }
 
 /**
@@ -40,9 +41,14 @@ export class LocalOperationInvoker implements OperationInvoker {
     this.proxiedRead = source === 'mcp';
   }
 
-  async invoke(name: string, input: Record<string, unknown>): Promise<unknown> {
+  async invoke(
+    name: string,
+    input: Record<string, unknown>,
+    options: OperationExecutionOptions = {},
+  ): Promise<unknown> {
     const args = this.allowExternalMcp ? input : { ...input, allowExternalMcp: false };
     return await executeOperation(name, defaultPresenceSource(name, args, this.source), {
+      ...options,
       source: this.source,
       proxiedRead: this.proxiedRead,
     });
@@ -53,6 +59,37 @@ function toOperationErrorStatus(status: number): OperationErrorStatus {
   return status === 404 ? 404 : status === 409 ? 409 : status === 403 ? 403 : 400;
 }
 
+async function readProgressResponse(response: Response, options: OperationExecutionOptions): Promise<Response> {
+  if (!response.body) throw new OperationError('Missing operation progress stream.');
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      buffer += decoder.decode(value, { stream: !done });
+      let end = buffer.indexOf('\n');
+      while (end !== -1) {
+        const frame = JSON.parse(buffer.slice(0, end)) as OperationStreamFrame;
+        buffer = buffer.slice(end + 1);
+        if (frame.type === 'result') return Response.json(frame.body, { status: frame.status });
+        if (frame.type !== 'progress') throw new OperationError('Invalid operation progress frame.');
+        try {
+          await options.onProgress?.(frame.progress);
+        } catch (error) {
+          if (!options.signal?.aborted) console.error('[operation] progress callback failed:', error);
+        }
+        end = buffer.indexOf('\n');
+      }
+      if (done) throw new OperationError('Operation progress stream ended without a result.');
+    }
+  } finally {
+    // A fetch abort already errors the reader; preserve that original failure.
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+}
+
 /** Builds the HTTP request from the op's route template (`:id` from input, GET flags to query). */
 export class HttpOperationInvoker implements OperationInvoker {
   private readonly baseUrl: string;
@@ -70,7 +107,12 @@ export class HttpOperationInvoker implements OperationInvoker {
     this.proxiedRead = source === 'mcp';
   }
 
-  async invoke(name: string, rawInput: Record<string, unknown>): Promise<unknown> {
+  async invoke(
+    name: string,
+    rawInput: Record<string, unknown>,
+    options: OperationExecutionOptions = {},
+  ): Promise<unknown> {
+    options.signal?.throwIfAborted();
     const args = this.allowExternalMcp ? rawInput : { ...rawInput, allowExternalMcp: false };
     const input = defaultPresenceSource(name, args, this.source);
     const op = getOperation(name);
@@ -96,8 +138,10 @@ export class HttpOperationInvoker implements OperationInvoker {
 
     let url = `${this.baseUrl}${path}`;
     const proxyHeaders: Record<string, string> = this.proxiedRead ? { 'x-pmx-proxied-read': '1' } : {};
+    if (options.onProgress) proxyHeaders.accept = 'application/x-ndjson';
     const init: RequestInit = {
       method: route.method,
+      signal: options.signal,
       headers: { 'x-pmx-source': this.source, ...proxyHeaders },
     };
     if (route.method === 'GET' || route.method === 'DELETE') {
@@ -112,7 +156,10 @@ export class HttpOperationInvoker implements OperationInvoker {
       init.body = JSON.stringify(rest);
     }
 
-    const response = await fetch(url, init);
+    let response = await fetch(url, init);
+    if (response.headers.get('content-type')?.startsWith('application/x-ndjson')) {
+      response = await readProgressResponse(response, options);
+    }
     const text = await response.text();
     let parsed: unknown = null;
     let parsedAsJson = false;
@@ -125,6 +172,7 @@ export class HttpOperationInvoker implements OperationInvoker {
       }
     }
     if (!response.ok) {
+      if (response.status === 499) throw new DOMException('Operation cancelled.', 'AbortError');
       // errorBodyAsResult carries the route's STRUCTURED partial-failure
       // envelope (e.g. canvas_batch { ok:false, failedIndex, ... }) through as
       // a result. A non-JSON error body (an HTML 502 from a proxy, a foreign

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

@@ -0,0 +1,339 @@
+/**
+ * MCP's output is the FORMATTER projection, never the larger HTTP payload.
+ * `result` wraps prose/arrays without pretending they are JSON objects. Each
+ * operation validates its stable fields; loose payloads preserve full:true and
+ * extensible node/app data. No schema advertises an unconstrained root record.
+ */
+import { z, type ZodType } from 'zod';
+import type { CallToolResult, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import { tourSchema, tourStopSchema } from '../../shared/tour.js';
+
+const id = z.string().min(1);
+const count = z.number().int().nonnegative();
+const ok = z.looseObject({ ok: z.boolean() });
+const identified = z.looseObject({ id });
+const message = z.strictObject({ message: z.string() });
+const node = z.looseObject({
+  id,
+  type: z.string(),
+  contentRevision: count.optional(),
+  linksRevision: count.optional(),
+});
+const created = z.looseObject({
+  ok: z.boolean(),
+  id,
+  nodeId: id.optional(),
+  node: node.optional(),
+  contentRevision: count.optional(),
+});
+const edge = z.looseObject({ id, from: id, to: id, type: z.string() });
+const boards = z.looseObject({ ok: z.boolean(), activeBoardId: id.nullable(), boards: z.array(identified) });
+const board = z.looseObject({ ok: z.boolean(), board: identified });
+const viewport = z.object({ x: z.number(), y: z.number(), scale: z.number().positive() });
+const webview = z.looseObject({ supported: z.boolean(), active: z.boolean() });
+const entity = (key: string) => z.looseObject({ ok: z.boolean(), [key]: identified });
+const gate = (key: string) =>
+  z.looseObject({ ok: z.boolean(), [key]: identified.nullable(), pending: z.boolean().optional() });
+const history = z.looseObject({ ok: z.boolean(), description: z.string(), canUndo: z.boolean(), canRedo: z.boolean() });
+const batchEntry = z.looseObject({
+  ok: z.boolean(),
+  id: id.optional(),
+  nodeId: id.optional(),
+  contentRevision: count.optional(),
+});
+const batch = z.discriminatedUnion('ok', [
+  z.looseObject({ ok: z.literal(true), results: z.array(batchEntry), refs: z.record(z.string(), batchEntry) }),
+  z.looseObject({
+    ok: z.literal(false),
+    failedIndex: count,
+    error: z.string(),
+    cancelled: z.boolean().optional(),
+    results: z.array(batchEntry),
+    refs: z.record(z.string(), batchEntry),
+  }),
+]);
+
+/** Required stable fields, keyed by dispatched operation (including every composite action). */
+const payloads: Record<string, ZodType> = {
+  'pin.set': z.looseObject({ ok: z.boolean(), pinnedNodeIds: z.array(id) }),
+  'ax.command.invoke': entity('event'),
+  'canvas.batch': batch,
+  'import.list': z.looseObject({ ok: z.boolean(), imports: z.array(identified) }),
+  'import.read': z.looseObject({
+    ok: z.boolean(),
+    import: identified,
+    attachment: identified,
+    downloadPath: z.string(),
+  }),
+  'import.submit': entity('import'),
+  'import.unavailable': entity('import'),
+  'snapshot.save': z.looseObject({ ok: z.boolean(), id, snapshot: identified }),
+  'snapshot.list': z.looseObject({ snapshots: z.array(identified) }),
+  'snapshot.restore': z.looseObject({
+    ok: z.boolean(),
+    restored: id,
+    summary: z.looseObject({ nodeCount: count, edgeCount: count }),
+  }),
+  'snapshot.restore-node': z.looseObject({ ok: z.boolean(), id, restored: z.boolean() }),
+  'snapshot.delete': z.looseObject({ ok: z.boolean(), deleted: id }),
+  'snapshot.gc': ok,
+  'snapshot.diff': message,
+  'board.list': boards,
+  'board.get': board,
+  'board.create': board,
+  'board.create-from': z.union([
+    board,
+    z.looseObject({ ok: z.boolean(), sourceBoardId: id, cards: z.array(node), edges: z.array(edge) }),
+  ]),
+  'board.open': boards,
+  'board.update': boards,
+  'board.pin': boards,
+  'board.unpin': boards,
+  'knowledge.list': z.looseObject({
+    ok: z.boolean(),
+    categories: z.array(identified),
+    folders: z.array(z.looseObject({ path: z.string() })),
+  }),
+  'knowledge.category-set': entity('category'),
+  'knowledge.category-remove': z.looseObject({ ok: z.boolean(), id }),
+  'knowledge.relation-preset-set': entity('preset'),
+  'knowledge.relation-preset-remove': z.looseObject({ ok: z.boolean(), id }),
+  'knowledge.folder-set': z.looseObject({ ok: z.boolean(), folder: z.looseObject({ path: z.string() }) }),
+  'node.add': created,
+  'node.get': node,
+  'node.update': created,
+  'node.remove': z.looseObject({ ok: z.boolean(), removed: id }),
+  'node.lifecycle-get': z.looseObject({ ok: z.boolean(), boardId: id, nodeId: id, contentRevision: count }),
+  'node.lifecycle-set': ok,
+  'node.review': entity('record'),
+  'node.lifecycle-restore': entity('record'),
+  'schema.describe': z.looseObject({ ok: z.boolean(), nodeTypes: z.array(z.looseObject({ type: z.string() })) }),
+  'spec.validate': ok,
+  'jsonrender.add': created,
+  'jsonrender.stream': created.extend({ specVersion: count, applied: count, skipped: count }),
+  'graph.add': created,
+  'render.workboard': z.looseObject({ ok: z.boolean(), id }),
+  'edge.add': edge,
+  'edge.update': z.looseObject({ id, type: z.string() }),
+  'edge.remove': z.looseObject({ ok: z.boolean(), removed: id }),
+  'group.create': created,
+  'group.add': z.looseObject({ ok: z.boolean(), groupId: id }),
+  'group.remove': z.looseObject({ ok: z.boolean(), groupId: id }),
+  'canvas.undo': history,
+  'canvas.redo': history,
+  'tour.get': z.looseObject({ tour: tourSchema, derived: z.boolean(), position: count.nullable() }),
+  'tour.set': ok,
+  'tour.go': z.looseObject({ ok: z.boolean(), index: count, total: count, stop: tourStopSchema }),
+  'tour.exit': ok,
+  'camera.move': z.looseObject({ ok: z.boolean(), stop: tourStopSchema, viewport }),
+  arrange: z.looseObject({ ok: z.boolean(), layout: z.enum(['grid', 'column', 'flow']) }),
+  '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.remove': ok,
+  'context.get': z.looseObject({ version: z.literal(1), budgetUnit: z.literal('utf16-code-units') }),
+  'memory-graph.get': z.looseObject({
+    nodes: z.array(z.looseObject({ key: id, boardId: id, kind: z.enum(['board', 'card']) })),
+    edges: z.array(z.looseObject({ id, from: id, to: id })),
+    depth: count,
+  }),
+  search: z.looseObject({ query: z.string(), resultCount: count, results: z.array(node) }),
+  'layout.get': z.looseObject({ nodes: z.array(node), edges: z.array(edge), viewport }),
+  'validate.get': ok,
+  'mcpapp.open': z.looseObject({
+    ok: z.boolean(),
+    nodeId: id.nullable(),
+    sessionId: id,
+    toolCallId: id,
+    resourceUri: z.string(),
+  }),
+  'diagram.open': z.looseObject({
+    ok: z.boolean(),
+    nodeId: id.nullable(),
+    sessionId: id,
+    toolCallId: id,
+    resourceUri: z.string(),
+  }),
+  'webartifact.build': z.looseObject({
+    ok: z.boolean(),
+    path: z.string(),
+    bytes: count,
+    openedInCanvas: z.boolean(),
+    id: id.optional(),
+    nodeId: id.nullable().optional(),
+  }),
+  'webview.status': webview,
+  'webview.start': webview,
+  'webview.stop': z.looseObject({ ok: z.boolean(), stopped: z.boolean(), webview }),
+  'webview.resize': webview,
+  // Evaluation deliberately returns arbitrary page values, including undefined
+  // (serialized as an absent value). This is the one untyped leaf, not a root contract.
+  'webview.evaluate': z.strictObject({ value: z.unknown().optional() }),
+  'ax.get': ok,
+  'ax.focus.set': z.looseObject({ ok: z.boolean(), focus: z.looseObject({ nodeIds: z.array(id) }) }),
+  'ax.policy.set': ok,
+  'ax.host-capability.report': ok,
+  'ax.presence.get': ok,
+  'ax.presence.set': ok,
+  'ax.work.create': entity('workItem'),
+  'ax.work.update': entity('workItem'),
+  'ax.review.add': entity('reviewAnnotation'),
+  'ax.approval.request': gate('approvalGate'),
+  'ax.approval.resolve': gate('approvalGate'),
+  'ax.approval.get': gate('approvalGate'),
+  'ax.elicitation.request': gate('elicitation'),
+  'ax.elicitation.respond': gate('elicitation'),
+  'ax.elicitation.get': gate('elicitation'),
+  'ax.mode.request': gate('modeRequest'),
+  'ax.mode.resolve': gate('modeRequest'),
+  'ax.mode.get': gate('modeRequest'),
+  'ax.timeline.get': ok,
+  'ax.event.record': entity('event'),
+  'ax.evidence.add': entity('evidence'),
+  'ax.steer': entity('steering'),
+  'ax.reads.list': ok,
+  'ax.reads.status': z.looseObject({ ok: z.boolean(), boardId: id.nullable() }),
+  'ax.delivery.pending': z.looseObject({ ok: z.boolean(), pending: z.array(identified) }),
+  'ax.delivery.mark': z.looseObject({ ok: z.boolean(), delivered: z.boolean() }),
+  'intent.signal': entity('intent'),
+  'intent.update': entity('intent'),
+  'intent.clear': z.looseObject({ ok: z.boolean(), cleared: z.boolean() }),
+};
+
+function payloadSchema(operation: string): ZodType {
+  const schema = payloads[operation];
+  if (!schema) throw new Error(`Missing MCP output contract for ${operation}.`);
+  return schema;
+}
+
+const errorData = z.strictObject({ message: z.string() });
+const formattedErrorData = z.looseObject({ ok: z.literal(false), error: z.string() });
+
+export function operationOutputSchema(operations: string[]) {
+  // Shared schema identity proves equivalent validation without comparing or
+  // rewriting JSON Schema. Keep distinct contracts tied to their operations.
+  const successGroups = new Map<ZodType, string[]>();
+  const variants: ZodType[] = operations.flatMap((operation): ZodType[] => {
+    if (operation === 'canvas.batch')
+      return [
+        z.strictObject({ operation: z.literal(operation), outcome: z.literal('success'), data: batch.options[0] }),
+        z.strictObject({
+          operation: z.literal(operation),
+          outcome: z.literal('error'),
+          data: batch.options[1].extend({ results: z.array(batchEntry).length(0) }),
+        }),
+        z.strictObject({
+          operation: z.literal(operation),
+          outcome: z.literal('partial'),
+          data: batch.options[1].extend({ results: z.array(batchEntry).min(1) }),
+        }),
+      ];
+    const schema = payloadSchema(operation);
+    const group = successGroups.get(schema);
+    if (group) group.push(operation);
+    else successGroups.set(schema, [operation]);
+    return [];
+  });
+  for (const [data, names] of successGroups)
+    variants.push(
+      z.strictObject({
+        operation: names.length === 1 ? z.literal(names[0]) : z.enum(names),
+        outcome: z.literal('success'),
+        data,
+      }),
+    );
+  const formattedErrors = operations.filter((operation) => operation !== 'canvas.batch');
+  if (formattedErrors.length)
+    variants.push(
+      z.strictObject({
+        operation: z.enum(formattedErrors),
+        outcome: z.literal('error'),
+        data: z.union([errorData, formattedErrorData]),
+      }),
+    );
+  // null identifies an exception rather than a formatted operation result;
+  // it does NOT promise that no writes occurred before the exception.
+  return z.strictObject({
+    result: z.union([
+      ...variants,
+      z.strictObject({ operation: z.null(), outcome: z.literal('error'), data: errorData }),
+    ]),
+  });
+}
+
+export function structuredOperationResult(operation: string, formatted: CallToolResult): CallToolResult {
+  const text = formatted.content
+    .filter((item) => item.type === 'text')
+    .map((item) => item.text)
+    .join('\n');
+  let data: unknown;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = { message: text };
+  }
+  // Error payloads can contain meaningful partial state. Never replace them
+  // with the thrown-error message shape, or lose batch results/refs.
+  if (!formatted.isError || operation === 'canvas.batch') payloadSchema(operation).parse(data);
+  else z.union([errorData, formattedErrorData]).parse(data);
+  const partial =
+    operation === 'canvas.batch' &&
+    formatted.isError &&
+    typeof data === 'object' &&
+    data !== null &&
+    'results' in data &&
+    Array.isArray(data.results) &&
+    data.results.length > 0;
+  return {
+    ...formatted,
+    structuredContent: {
+      result: { operation, outcome: partial ? 'partial' : formatted.isError ? 'error' : 'success', data },
+    },
+  };
+}
+
+export function operationToolError(error: unknown): CallToolResult {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    content: [{ type: 'text', text: message }],
+    isError: true,
+    structuredContent: { result: { operation: null, outcome: 'error', data: { message } } },
+  };
+}
+
+/**
+ * Explicit worst-case audit of all 21 generated tools. `mutates` only controls
+ * layout events and is intentionally absent here. Tuple = destructive,
+ * idempotent, open-world. All tools have a write action, including query's
+ * durable consumer cursor. Read logging alone would not make a tool a write.
+ */
+const annotations: Record<string, readonly [boolean, boolean, boolean]> = {
+  canvas_pin_nodes: [true, true, false], // set/remove can replace the human's pins
+  canvas_invoke_command: [false, false, false], // appends an allowlisted intent, not arbitrary execution
+  canvas_batch: [true, false, true], // remove/replace; webpage creation can fetch
+  canvas_import: [false, false, false], // submit/unavailable transition a requested job
+  canvas_snapshot: [true, false, true], // restore/delete/gc; restoring apps can reconnect
+  canvas_board: [true, false, true], // category/template removal; open can rehydrate apps
+  canvas_node: [true, false, true], // remove/update; webpage fetching and file nodes
+  canvas_render: [true, false, false], // stream/workboard can replace an existing spec
+  canvas_edge: [true, false, false],
+  canvas_group: [true, false, false],
+  canvas_history: [true, false, true], // undo/redo can restore and reconnect app sessions
+  canvas_view: [true, false, false], // clear/remove annotation; tour next is not idempotent
+  canvas_query: [false, false, false], // context advances a durable consumer cursor
+  canvas_app: [true, false, true], // arbitrary external tools/build processes; existing-node replacement
+  canvas_webview: [true, false, true], // evaluate is arbitrary page JavaScript, not a read
+  canvas_ax_state: [true, false, false], // replaces policy/focus; presence can append sessions
+  canvas_ax_work: [true, false, false], // update replaces existing work-item fields
+  canvas_ax_gate: [true, false, false], // resolve changes pending gates; request creates IDs
+  canvas_ax_timeline: [false, false, false], // appends events/evidence/steering
+  canvas_ax_delivery: [false, false, false], // claim/mark consume delivery state
+  canvas_intent: [true, false, false], // update/clear; signal generates an ID and TTL
+};
+
+export function operationToolAnnotations(toolName: string): ToolAnnotations {
+  const flags = annotations[toolName];
+  if (!flags) throw new Error(`Missing MCP annotation audit for ${toolName}.`);
+  const [destructiveHint, idempotentHint, openWorldHint] = flags;
+  return { readOnlyHint: false, destructiveHint, idempotentHint, openWorldHint };
+}