pmx-canvas 0.3.0 → 0.3.1

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

@@ -15,16 +15,11 @@ import type { PmxAxSource } from '../../ax-state.js';
 export const AX_SOURCES = ['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'] as const;
 
 /** Zod schema for the optional `source` field shared by AX MCP tool shapes. */
-export const AX_SOURCE_SHAPE = z
-  .enum(AX_SOURCES)
-  .optional()
-  .describe('Optional host/source label. Defaults to mcp.');
+export const AX_SOURCE_SHAPE = z.enum(AX_SOURCES).optional().describe('Optional host/source label. Defaults to mcp.');
 
 /** An absent or unrecognized source falls back to the per-surface default. */
 export function normalizeAxSource(value: unknown, fallback: PmxAxSource): PmxAxSource {
-  return (AX_SOURCES as readonly string[]).includes(value as string)
-    ? (value as PmxAxSource)
-    : fallback;
+  return (AX_SOURCES as readonly string[]).includes(value as string) ? (value as PmxAxSource) : fallback;
 }
 
 export function normalizeAxNodeIds(value: unknown): string[] {

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

@@ -52,7 +52,8 @@ const axGetOperation = defineOperation<z.infer<typeof axGetSchema>, Record<strin
   },
   mcp: {
     toolName: 'canvas_get_ax',
-    description: 'Read the host-agnostic PMX AX state and agent-ready AX context. Use this when you need pinned context plus the current focus field.',
+    description:
+      'Read the host-agnostic PMX AX state and agent-ready AX context. Use this when you need pinned context plus the current focus field.',
     extraShape: {
       includeContext: z.boolean().optional().describe('Include serialized agent-ready AX context. Default true.'),
     },
@@ -85,7 +86,12 @@ const axGetOperation = defineOperation<z.infer<typeof axGetSchema>, Record<strin
 
 const axFocusSetShape = {
   nodeIds: z.unknown().optional().describe('Node IDs to place in the AX focus field. Missing nodes are ignored.'),
-  source: z.unknown().optional().describe('Optional host/source label for adapter-originated focus. Defaults to mcp. Use codex from the Codex app adapter.'),
+  source: z
+    .unknown()
+    .optional()
+    .describe(
+      'Optional host/source label for adapter-originated focus. Defaults to mcp. Use codex from the Codex app adapter.',
+    ),
 };
 
 const axFocusSetSchema = z.looseObject(axFocusSetShape);
@@ -101,12 +107,16 @@ const axFocusSetOperation = defineOperation<z.infer<typeof axFocusSetSchema>, Re
   },
   mcp: {
     toolName: 'canvas_set_ax_focus',
-    description: 'Set the PMX AX focus field without requiring viewport movement. Focus is persisted and available through canvas://ax-context.',
+    description:
+      'Set the PMX AX focus field without requiring viewport movement. Focus is persisted and available through canvas://ax-context.',
     extraShape: {
       nodeIds: z.array(z.string()).describe('Node IDs to place in the AX focus field. Missing nodes are ignored.'),
-      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+      source: z
+        .enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
         .optional()
-        .describe('Optional host/source label for adapter-originated focus. Defaults to mcp. Use codex from the Codex app adapter.'),
+        .describe(
+          'Optional host/source label for adapter-originated focus. Defaults to mcp. Use codex from the Codex app adapter.',
+        ),
     },
     buildInput: (input) => ({ ...input, source: normalizeAxSource(input.source, 'mcp') }),
     formatResult: (result) => {
@@ -146,13 +156,16 @@ const axPolicySetOperation = defineOperation<z.infer<typeof axPolicySetSchema>,
   },
   mcp: {
     toolName: 'canvas_set_ax_policy',
-    description: 'Set the declarative AX policy (allowed/excluded/approval-required tools; prompt mode/append). PMX stores it and exposes it via canvas://ax-context; host adapters READ and enforce it. Merges with the existing policy.',
+    description:
+      'Set the declarative AX policy (allowed/excluded/approval-required tools; prompt mode/append). PMX stores it and exposes it via canvas://ax-context; host adapters READ and enforce it. Merges with the existing policy.',
     extraShape: {
-      tools: z.object({
-        allowed: z.array(z.string()).optional(),
-        excluded: z.array(z.string()).optional(),
-        approvalRequired: z.array(z.string()).optional(),
-      }).optional(),
+      tools: z
+        .object({
+          allowed: z.array(z.string()).optional(),
+          excluded: z.array(z.string()).optional(),
+          approvalRequired: z.array(z.string()).optional(),
+        })
+        .optional(),
       prompt: z.object({ systemAppend: z.string().optional(), mode: z.string().optional() }).optional(),
       source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system']).optional(),
     },
@@ -196,7 +209,10 @@ const axHostCapabilityReportShape = {
 
 const axHostCapabilityReportSchema = z.looseObject(axHostCapabilityReportShape);
 
-const axHostCapabilityReportOperation = defineOperation<z.infer<typeof axHostCapabilityReportSchema>, Record<string, unknown>>({
+const axHostCapabilityReportOperation = defineOperation<
+  z.infer<typeof axHostCapabilityReportSchema>,
+  Record<string, unknown>
+>({
   name: 'ax.host-capability.report',
   mutates: false,
   input: axHostCapabilityReportSchema,
@@ -208,7 +224,8 @@ const axHostCapabilityReportOperation = defineOperation<z.infer<typeof axHostCap
   },
   mcp: {
     toolName: 'canvas_report_host_capability',
-    description: 'Report host/session capability from an adapter: what the host can do (canvas/hooks/tools/sessionMessaging/permissions/files/uiPrompts). Stored for diagnostics; core does not depend on a host.',
+    description:
+      'Report host/session capability from an adapter: what the host can do (canvas/hooks/tools/sessionMessaging/permissions/files/uiPrompts). Stored for diagnostics; core does not depend on a host.',
     extraShape: {
       host: z.string().optional().describe('Host identifier (e.g. copilot, codex).'),
       canvas: z.boolean().optional(),
@@ -219,7 +236,8 @@ const axHostCapabilityReportOperation = defineOperation<z.infer<typeof axHostCap
       files: z.boolean().optional(),
       uiPrompts: z.boolean().optional(),
       raw: z.record(z.string(), z.unknown()).optional().describe('Optional raw capability payload for diagnostics.'),
-      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+      source: z
+        .enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
         .optional()
         .describe('Optional host/source label. Defaults to mcp.'),
     },

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

@@ -53,7 +53,15 @@ import { defineOperation, OperationError, type Operation } from '../types.js';
 import { isRecord } from './nodes.js';
 import { AX_SOURCE_SHAPE, axJsonResult, normalizeAxNodeIds, normalizeAxSource } from './ax-shared.js';
 
-const AX_EVENT_KINDS = ['prompt', 'assistant-message', 'tool-start', 'tool-result', 'failure', 'approval', 'steering'] as const;
+const AX_EVENT_KINDS = [
+  'prompt',
+  'assistant-message',
+  'tool-start',
+  'tool-result',
+  'failure',
+  'approval',
+  'steering',
+] as const;
 const AX_EVIDENCE_KINDS = ['logs', 'tool-result', 'screenshot', 'file', 'diff', 'test-output'] as const;
 
 // ── ax.event.record (canvas_record_ax_event) ──────────────────
@@ -80,7 +88,8 @@ const axEventRecordOperation = defineOperation<z.infer<typeof axEventRecordSchem
   },
   mcp: {
     toolName: 'canvas_record_ax_event',
-    description: 'Record a normalized AX timeline event (prompt/assistant-message/tool-start/tool-result/failure/approval/steering). Timeline events persist for diagnostics and continuity but are not restored by snapshots.',
+    description:
+      'Record a normalized AX timeline event (prompt/assistant-message/tool-start/tool-result/failure/approval/steering). Timeline events persist for diagnostics and continuity but are not restored by snapshots.',
     extraShape: {
       kind: z.enum(AX_EVENT_KINDS).describe('Normalized event kind.'),
       summary: z.string().describe('Short human-readable summary of the event.'),
@@ -136,7 +145,8 @@ const axEvidenceAddOperation = defineOperation<z.infer<typeof axEvidenceAddSchem
   },
   mcp: {
     toolName: 'canvas_add_evidence',
-    description: 'Record an AX evidence item (logs/tool-result/screenshot/file/diff/test-output) on the timeline. Evidence persists for diagnostics and continuity but is not restored by snapshots; exposed via canvas://ax-timeline.',
+    description:
+      'Record an AX evidence item (logs/tool-result/screenshot/file/diff/test-output) on the timeline. Evidence persists for diagnostics and continuity but is not restored by snapshots; exposed via canvas://ax-timeline.',
     extraShape: {
       kind: z.enum(AX_EVIDENCE_KINDS).describe('Evidence kind.'),
       title: z.string().describe('Short human-readable title for the evidence.'),
@@ -189,7 +199,8 @@ const axSteerOperation = defineOperation<z.infer<typeof axSteerSchema>, Record<s
   },
   mcp: {
     toolName: 'canvas_send_steering',
-    description: 'Record a steering message: a user instruction from the surface to the active agent session. Persisted on the AX timeline and exposed via canvas://ax-timeline.',
+    description:
+      'Record a steering message: a user instruction from the surface to the active agent session. Persisted on the AX timeline and exposed via canvas://ax-timeline.',
     extraShape: {
       message: z.string().describe('The steering instruction to deliver to the active agent session.'),
       source: AX_SOURCE_SHAPE,
@@ -228,7 +239,8 @@ const axTimelineGetOperation = defineOperation<z.infer<typeof axTimelineGetSchem
   },
   mcp: {
     toolName: 'canvas_get_ax_timeline',
-    description: 'Read the bounded AX timeline: recent agent-events, evidence, and steering messages plus counts. Use this for diagnostics and session continuity.',
+    description:
+      'Read the bounded AX timeline: recent agent-events, evidence, and steering messages plus counts. Use this for diagnostics and session continuity.',
     extraShape: {
       limit: z.number().optional().describe('Max rows per timeline table (default 50, max 200).'),
     },
@@ -238,9 +250,7 @@ const axTimelineGetOperation = defineOperation<z.infer<typeof axTimelineGetSchem
     // `limit` arrives as a number over MCP or a string over the HTTP query;
     // Number() normalizes both. Only a finite positive limit is forwarded.
     const limit = Number(input.limit ?? '');
-    const timeline = canvasState.getAxTimeline(
-      Number.isFinite(limit) && limit > 0 ? { limit } : {},
-    );
+    const timeline = canvasState.getAxTimeline(Number.isFinite(limit) && limit > 0 ? { limit } : {});
     return { ok: true, ...timeline } as unknown as Record<string, unknown>;
   },
 });
@@ -266,11 +276,17 @@ const axDeliveryPendingOperation = defineOperation<z.infer<typeof axDeliveryPend
   },
   mcp: {
     toolName: 'canvas_claim_ax_delivery',
-    description: 'Claim pending PMX AX deliveries for a consumer (adapterless delivery). Returns `pending` undelivered steering (mark each with canvas_mark_ax_delivery after acting) AND `pendingActivity`: open canvas-bound AX items awaiting the agent (open work items, pending approval gates / elicitations / mode requests) — typically created by the human in the browser. Both exclude items the consumer itself originated (loop prevention). `pending` defaults to oldest-first (FIFO, for ordered processing); pass `order:"newest"` to surface the human\'s LATEST in-canvas steering first when a small `limit` would otherwise bury it behind a stale backlog (report #68). pendingActivity is read-only here: resolve each via its own tool (canvas_resolve_approval / canvas_respond_elicitation / canvas_resolve_mode / canvas_update_work_item), not canvas_mark_ax_delivery.',
+    description:
+      'Claim pending PMX AX deliveries for a consumer (adapterless delivery). Returns `pending` undelivered steering (mark each with canvas_mark_ax_delivery after acting) AND `pendingActivity`: open canvas-bound AX items awaiting the agent (open work items, pending approval gates / elicitations / mode requests) — typically created by the human in the browser. Both exclude items the consumer itself originated (loop prevention). `pending` defaults to oldest-first (FIFO, for ordered processing); pass `order:"newest"` to surface the human\'s LATEST in-canvas steering first when a small `limit` would otherwise bury it behind a stale backlog (report #68). pendingActivity is read-only here: resolve each via its own tool (canvas_resolve_approval / canvas_respond_elicitation / canvas_resolve_mode / canvas_update_work_item), not canvas_mark_ax_delivery.',
     extraShape: {
       consumer: z.string().optional().describe('Consumer/source label to exclude from results (e.g. copilot, mcp).'),
       limit: z.number().optional().describe('Max steering messages to return.'),
-      order: z.enum(['newest', 'oldest']).optional().describe('Order of returned steering: "oldest" (FIFO, default) for ordered processing, or "newest" first to see the latest browser action when limited.'),
+      order: z
+        .enum(['newest', 'oldest'])
+        .optional()
+        .describe(
+          'Order of returned steering: "oldest" (FIFO, default) for ordered processing, or "newest" first to see the latest browser action when limited.',
+        ),
     },
     // `consumer` is a loop-safety scope, not a source label — never defaulted.
     formatResult: axJsonResult,
@@ -285,9 +301,7 @@ const axDeliveryPendingOperation = defineOperation<z.infer<typeof axDeliveryPend
     // queries apply the same loop-safe consumer filter before the limit.
     const newest = input.order === 'newest';
     const scope = { ...(consumer ? { consumer } : {}), ...(limit ? { limit } : {}) };
-    const pending = newest
-      ? canvasState.getPendingSteeringForContext(scope)
-      : canvasState.getPendingSteering(scope);
+    const pending = newest ? canvasState.getPendingSteeringForContext(scope) : canvasState.getPendingSteering(scope);
     // The MCP tool aggregated pendingActivity; one wire body now serves it over
     // HTTP too (documented broadening). Loop-safe: consumer scopes both queries.
     const pendingActivity = buildPendingAxActivity(canvasState.getAxState(), consumer);
@@ -352,7 +366,8 @@ const axCommandInvokeOperation = defineOperation<z.infer<typeof axCommandInvokeS
   },
   mcp: {
     toolName: 'canvas_invoke_command',
-    description: 'Invoke a registry-gated PMX command intent (pmx.plan | pmx.execute | pmx.promote-context | pmx.summarize | pmx.review). Records a timeline event a host/agent can observe — NOT arbitrary execution; unknown names are rejected.',
+    description:
+      'Invoke a registry-gated PMX command intent (pmx.plan | pmx.execute | pmx.promote-context | pmx.summarize | pmx.review). Records a timeline event a host/agent can observe — NOT arbitrary execution; unknown names are rejected.',
     extraShape: {
       name: z.string().describe('A command name from the PMX command registry.'),
       args: z.record(z.string(), z.unknown()).optional(),
@@ -365,11 +380,9 @@ const axCommandInvokeOperation = defineOperation<z.infer<typeof axCommandInvokeS
     if (typeof input.name !== 'string') {
       throw new OperationError('command requires a name.');
     }
-    const event = canvasState.invokeCommand(
-      input.name,
-      isRecord(input.args) ? input.args : null,
-      { source: normalizeAxSource(input.source, 'api') },
-    );
+    const event = canvasState.invokeCommand(input.name, isRecord(input.args) ? input.args : null, {
+      source: normalizeAxSource(input.source, 'api'),
+    });
     // Allowlist gate: invokeCommand returns null for an unknown command name.
     if (!event) throw new OperationError(`Unknown command "${input.name}".`, 400);
     ctx.emit('ax-event-created', { event });

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

@@ -61,9 +61,7 @@ import { AX_SOURCE_SHAPE, AX_SOURCES, axJsonResult, normalizeAxNodeIds, normaliz
 
 const AX_WORK_ITEM_STATUSES = new Set(['todo', 'in-progress', 'blocked', 'done', 'cancelled']);
 function normalizeAxWorkItemStatus(value: unknown): PmxAxWorkItemStatus | undefined {
-  return typeof value === 'string' && AX_WORK_ITEM_STATUSES.has(value)
-    ? value as PmxAxWorkItemStatus
-    : undefined;
+  return typeof value === 'string' && AX_WORK_ITEM_STATUSES.has(value) ? (value as PmxAxWorkItemStatus) : undefined;
 }
 
 const AX_REVIEW_KINDS = new Set(['comment', 'finding']);
@@ -72,16 +70,16 @@ const AX_REVIEW_STATUSES = new Set(['open', 'resolved', 'dismissed']);
 const AX_REVIEW_ANCHORS = new Set(['node', 'file', 'region']);
 
 function normalizeAxReviewKind(value: unknown): PmxAxReviewKind | undefined {
-  return typeof value === 'string' && AX_REVIEW_KINDS.has(value) ? value as PmxAxReviewKind : undefined;
+  return typeof value === 'string' && AX_REVIEW_KINDS.has(value) ? (value as PmxAxReviewKind) : undefined;
 }
 function normalizeAxReviewSeverity(value: unknown): PmxAxReviewSeverity | undefined {
-  return typeof value === 'string' && AX_REVIEW_SEVERITIES.has(value) ? value as PmxAxReviewSeverity : undefined;
+  return typeof value === 'string' && AX_REVIEW_SEVERITIES.has(value) ? (value as PmxAxReviewSeverity) : undefined;
 }
 function normalizeAxReviewStatus(value: unknown): PmxAxReviewStatus | undefined {
-  return typeof value === 'string' && AX_REVIEW_STATUSES.has(value) ? value as PmxAxReviewStatus : undefined;
+  return typeof value === 'string' && AX_REVIEW_STATUSES.has(value) ? (value as PmxAxReviewStatus) : undefined;
 }
 function normalizeAxReviewAnchor(value: unknown): PmxAxReviewAnchorType | undefined {
-  return typeof value === 'string' && AX_REVIEW_ANCHORS.has(value) ? value as PmxAxReviewAnchorType : undefined;
+  return typeof value === 'string' && AX_REVIEW_ANCHORS.has(value) ? (value as PmxAxReviewAnchorType) : undefined;
 }
 function normalizeAxReviewRegion(value: unknown): PmxAxReviewRegion | undefined {
   if (!isRecord(value)) return undefined;
@@ -115,10 +113,12 @@ const axWorkCreateOperation = defineOperation<z.infer<typeof axWorkCreateSchema>
   },
   mcp: {
     toolName: 'canvas_add_work_item',
-    description: 'Add a canvas-bound AX work item: a visible task/plan/status tied to nodes and agent work. Work items participate in snapshots and are exposed via canvas://ax-work.',
+    description:
+      'Add a canvas-bound AX work item: a visible task/plan/status tied to nodes and agent work. Work items participate in snapshots and are exposed via canvas://ax-work.',
     extraShape: {
       title: z.string().describe('Short title of the work item.'),
-      status: z.enum(['todo', 'in-progress', 'blocked', 'done', 'cancelled'])
+      status: z
+        .enum(['todo', 'in-progress', 'blocked', 'done', 'cancelled'])
         .optional()
         .describe('Work item status. Defaults to todo.'),
       detail: z.string().optional().describe('Optional longer description.'),
@@ -135,7 +135,9 @@ const axWorkCreateOperation = defineOperation<z.infer<typeof axWorkCreateSchema>
     // Report #56: reject an unknown status (e.g. "in_progress") instead of
     // silently dropping it — the accepted tokens use hyphens.
     if (input.status !== undefined && !normalizeAxWorkItemStatus(input.status)) {
-      throw new OperationError(`invalid work item status "${String(input.status)}"; expected one of: todo, in-progress, blocked, done, cancelled.`);
+      throw new OperationError(
+        `invalid work item status "${String(input.status)}"; expected one of: todo, in-progress, blocked, done, cancelled.`,
+      );
     }
     const status = normalizeAxWorkItemStatus(input.status);
     const workItem = canvasState.addWorkItem(
@@ -176,13 +178,12 @@ const axWorkUpdateOperation = defineOperation<z.infer<typeof axWorkUpdateSchema>
   },
   mcp: {
     toolName: 'canvas_update_work_item',
-    description: 'Update a canvas-bound AX work item by ID (title/status/detail/nodeIds). Returns null if the work item does not exist.',
+    description:
+      'Update a canvas-bound AX work item by ID (title/status/detail/nodeIds). Returns null if the work item does not exist.',
     extraShape: {
       id: z.string().describe('Work item ID to update.'),
       title: z.string().optional().describe('New title.'),
-      status: z.enum(['todo', 'in-progress', 'blocked', 'done', 'cancelled'])
-        .optional()
-        .describe('New status.'),
+      status: z.enum(['todo', 'in-progress', 'blocked', 'done', 'cancelled']).optional().describe('New status.'),
       detail: z.string().optional().describe('New detail text.'),
       nodeIds: z.array(z.string()).optional().describe('Replacement node IDs.'),
       source: AX_SOURCE_SHAPE,
@@ -194,7 +195,9 @@ const axWorkUpdateOperation = defineOperation<z.infer<typeof axWorkUpdateSchema>
     const id = typeof input.id === 'string' ? input.id : '';
     // Report #56: reject an unknown status instead of returning ok:true + no-op.
     if (input.status !== undefined && !normalizeAxWorkItemStatus(input.status)) {
-      throw new OperationError(`invalid work item status "${String(input.status)}"; expected one of: todo, in-progress, blocked, done, cancelled.`);
+      throw new OperationError(
+        `invalid work item status "${String(input.status)}"; expected one of: todo, in-progress, blocked, done, cancelled.`,
+      );
     }
     const status = normalizeAxWorkItemStatus(input.status);
     const workItem = canvasState.updateWorkItem(
@@ -240,7 +243,8 @@ const axReviewAddOperation = defineOperation<z.infer<typeof axReviewAddSchema>,
   },
   mcp: {
     toolName: 'canvas_add_review_annotation',
-    description: 'Add a canvas-bound review annotation: a comment or finding anchored to a node, file, or region. Review annotations participate in snapshots and are exposed via canvas://ax-work.',
+    description:
+      'Add a canvas-bound review annotation: a comment or finding anchored to a node, file, or region. Review annotations participate in snapshots and are exposed via canvas://ax-work.',
     extraShape: {
       body: z.string().describe('Annotation body text.'),
       kind: z.enum(['comment', 'finding']).optional().describe('Annotation kind. Default comment.'),
@@ -248,11 +252,14 @@ const axReviewAddOperation = defineOperation<z.infer<typeof axReviewAddSchema>,
       anchorType: z.enum(['node', 'file', 'region']).optional().describe('Anchor type. Default node.'),
       nodeId: z.string().optional().describe('Node ID when anchorType is node.'),
       file: z.string().optional().describe('File path when anchorType is file.'),
-      region: z.object({
-        line: z.number().optional(),
-        endLine: z.number().optional(),
-        label: z.string().optional(),
-      }).optional().describe('Region descriptor when anchorType is region.'),
+      region: z
+        .object({
+          line: z.number().optional(),
+          endLine: z.number().optional(),
+          label: z.string().optional(),
+        })
+        .optional()
+        .describe('Region descriptor when anchorType is region.'),
       author: z.string().optional().describe('Optional author label.'),
       source: AX_SOURCE_SHAPE,
     },
@@ -356,7 +363,8 @@ const axApprovalRequestOperation = defineOperation<z.infer<typeof axApprovalRequ
   },
   mcp: {
     toolName: 'canvas_request_approval',
-    description: 'Request human approval before a high-impact AX action: creates a pending approval gate tied to nodes. Canvas-bound and snapshotted; exposed via canvas://ax-work.',
+    description:
+      'Request human approval before a high-impact AX action: creates a pending approval gate tied to nodes. Canvas-bound and snapshotted; exposed via canvas://ax-work.',
     extraShape: {
       title: z.string().describe('Short title of what needs approval.'),
       detail: z.string().optional().describe('Optional explanation of the action and its impact.'),
@@ -407,7 +415,8 @@ const axApprovalResolveOperation = defineOperation<z.infer<typeof axApprovalReso
   },
   mcp: {
     toolName: 'canvas_resolve_approval',
-    description: 'Resolve a pending approval gate by ID with approved or rejected. Returns null if the gate does not exist or is already resolved.',
+    description:
+      'Resolve a pending approval gate by ID with approved or rejected. Returns null if the gate does not exist or is already resolved.',
     extraShape: {
       id: z.string().describe('Approval gate ID to resolve.'),
       decision: z.enum(['approved', 'rejected']).describe('Approval decision.'),
@@ -422,14 +431,10 @@ const axApprovalResolveOperation = defineOperation<z.infer<typeof axApprovalReso
     if (input.decision !== 'approved' && input.decision !== 'rejected') {
       throw new OperationError('resolve requires decision approved or rejected.');
     }
-    const approvalGate = canvasState.resolveApproval(
-      id,
-      input.decision,
-      {
-        ...(typeof input.resolution === 'string' ? { resolution: input.resolution } : {}),
-        source: normalizeAxSource(input.source, 'api'),
-      },
-    );
+    const approvalGate = canvasState.resolveApproval(id, input.decision, {
+      ...(typeof input.resolution === 'string' ? { resolution: input.resolution } : {}),
+      source: normalizeAxSource(input.source, 'api'),
+    });
     if (!approvalGate) throw new OperationError('approval gate not found or already resolved.', 404);
     ctx.emit('ax-state-changed', { approvalGate });
     return { ok: true, approvalGate } as unknown as Record<string, unknown>;
@@ -447,7 +452,10 @@ const axElicitationRequestShape = {
 
 const axElicitationRequestSchema = z.looseObject(axElicitationRequestShape);
 
-const axElicitationRequestOperation = defineOperation<z.infer<typeof axElicitationRequestSchema>, Record<string, unknown>>({
+const axElicitationRequestOperation = defineOperation<
+  z.infer<typeof axElicitationRequestSchema>,
+  Record<string, unknown>
+>({
   name: 'ax.elicitation.request',
   mutates: false,
   input: axElicitationRequestSchema,
@@ -458,7 +466,8 @@ const axElicitationRequestOperation = defineOperation<z.infer<typeof axElicitati
   },
   mcp: {
     toolName: 'canvas_request_elicitation',
-    description: 'Request structured human input (an elicitation): a pending question/form tied to nodes. Canvas-bound and snapshotted; exposed via canvas://ax-work. Answer it with canvas_respond_elicitation.',
+    description:
+      'Request structured human input (an elicitation): a pending question/form tied to nodes. Canvas-bound and snapshotted; exposed via canvas://ax-work. Answer it with canvas_respond_elicitation.',
     extraShape: {
       prompt: z.string().describe('The question or instruction for the human.'),
       fields: z.array(z.string()).optional().describe('Optional field names to request (a simple structured form).'),
@@ -475,7 +484,9 @@ const axElicitationRequestOperation = defineOperation<z.infer<typeof axElicitati
     const elicitation = canvasState.requestElicitation(
       {
         prompt: input.prompt,
-        ...(Array.isArray(input.fields) ? { fields: input.fields.filter((f): f is string => typeof f === 'string') } : {}),
+        ...(Array.isArray(input.fields)
+          ? { fields: input.fields.filter((f): f is string => typeof f === 'string') }
+          : {}),
         ...(Array.isArray(input.nodeIds) ? { nodeIds: normalizeAxNodeIds(input.nodeIds) } : {}),
       },
       { source: normalizeAxSource(input.source, 'api') },
@@ -495,7 +506,10 @@ const axElicitationRespondShape = {
 
 const axElicitationRespondSchema = z.looseObject(axElicitationRespondShape);
 
-const axElicitationRespondOperation = defineOperation<z.infer<typeof axElicitationRespondSchema>, Record<string, unknown>>({
+const axElicitationRespondOperation = defineOperation<
+  z.infer<typeof axElicitationRespondSchema>,
+  Record<string, unknown>
+>({
   name: 'ax.elicitation.respond',
   mutates: false,
   input: axElicitationRespondSchema,
@@ -518,7 +532,9 @@ const axElicitationRespondOperation = defineOperation<z.infer<typeof axElicitati
   handler: (input, ctx) => {
     const id = typeof input.id === 'string' ? input.id : '';
     const response = isRecord(input.response) ? input.response : {};
-    const elicitation = canvasState.respondElicitation(id, response, { source: normalizeAxSource(input.source, 'api') });
+    const elicitation = canvasState.respondElicitation(id, response, {
+      source: normalizeAxSource(input.source, 'api'),
+    });
     if (!elicitation) throw new OperationError('elicitation not found or already answered.', 404);
     ctx.emit('ax-state-changed', { elicitation });
     return { ok: true, elicitation } as unknown as Record<string, unknown>;
@@ -547,7 +563,8 @@ const axModeRequestOperation = defineOperation<z.infer<typeof axModeRequestSchem
   },
   mcp: {
     toolName: 'canvas_request_mode',
-    description: 'Request a workflow mode transition (plan/execute/autonomous): a pending mode request tied to nodes. Canvas-bound and snapshotted; exposed via canvas://ax-work. Resolve with canvas_resolve_mode.',
+    description:
+      'Request a workflow mode transition (plan/execute/autonomous): a pending mode request tied to nodes. Canvas-bound and snapshotted; exposed via canvas://ax-work. Resolve with canvas_resolve_mode.',
     extraShape: {
       mode: z.enum(['plan', 'execute', 'autonomous']).describe('Requested target mode.'),
       reason: z.string().optional(),

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

@@ -24,10 +24,7 @@
  */
 import { z } from 'zod';
 import { canvasState } from '../../canvas-state.js';
-import {
-  serializeCanvasNode,
-  serializeCanvasNodeCompact,
-} from '../../canvas-serialization.js';
+import { serializeCanvasNode, serializeCanvasNodeCompact } from '../../canvas-serialization.js';
 import { addCanvasNode } from '../../canvas-operations.js';
 import { executeOperation, runWithSuppressedEmits } from '../registry.js';
 import { defineOperation, type Operation, type OperationContext } from '../types.js';
@@ -261,12 +258,19 @@ async function runBatch(operations: BatchEntry[]): Promise<BatchEnvelope> {
 }
 
 const batchShape = {
-  operations: z.array(z.object({
-    op: z.string().describe('Operation name, e.g. "node.add" or "edge.add"'),
-    assign: z.string().optional().describe('Optional reference name for later operations'),
-    args: z.record(z.string(), z.unknown()).optional().describe('Operation arguments'),
-  })).describe('Ordered array of batch operations'),
-  full: z.boolean().optional().describe('Return full batch operation results. Default false compacts node-like payloads.'),
+  operations: z
+    .array(
+      z.object({
+        op: z.string().describe('Operation name, e.g. "node.add" or "edge.add"'),
+        assign: z.string().optional().describe('Optional reference name for later operations'),
+        args: z.record(z.string(), z.unknown()).optional().describe('Operation arguments'),
+      }),
+    )
+    .describe('Ordered array of batch operations'),
+  full: z
+    .boolean()
+    .optional()
+    .describe('Return full batch operation results. Default false compacts node-like payloads.'),
   verbose: z.boolean().optional().describe('Alias for full:true.'),
 };
 
@@ -287,7 +291,25 @@ function compactBatchValue(value: unknown): unknown {
   const record = value as Record<string, unknown>;
   const nodeLike = typeof record.id === 'string' && typeof record.type === 'string';
   const compact: Record<string, unknown> = {};
-  for (const key of ['ok', 'id', 'type', 'kind', 'title', 'content', 'position', 'size', 'fetch', 'error', 'from', 'to', 'groupId', 'nodeIds', 'snapshot', 'arranged', 'layout']) {
+  for (const key of [
+    'ok',
+    'id',
+    'type',
+    'kind',
+    'title',
+    'content',
+    'position',
+    'size',
+    'fetch',
+    'error',
+    'from',
+    'to',
+    'groupId',
+    'nodeIds',
+    'snapshot',
+    'arranged',
+    'layout',
+  ]) {
     if (record[key] !== undefined) compact[key] = record[key];
   }
   if (nodeLike) return compact;
@@ -325,13 +347,16 @@ const batchOperation = defineOperation<z.infer<typeof batchSchema>, BatchEnvelop
       const body = await readJsonValue(req);
       const operations = Array.isArray(body)
         ? body
-        : isRecord(body) && Array.isArray(body.operations) ? body.operations : [];
+        : isRecord(body) && Array.isArray(body.operations)
+          ? body.operations
+          : [];
       return { operations };
     },
   },
   mcp: {
     toolName: 'canvas_batch',
-    description: 'Run a non-atomic batch of canvas operations with optional assigned references. Use assign to name a result, then reference it later as "$name" for the created node id or "$name.id" for a specific result field. On failure, earlier successful operations remain applied and the response includes ok:false, failedIndex, error, results, and refs. Supports node.add, node.update, node.remove, graph.add, edge.add, group.create, group.add, group.remove, pin.set/add/remove, snapshot.save, and arrange.',
+    description:
+      'Run a non-atomic batch of canvas operations with optional assigned references. Use assign to name a result, then reference it later as "$name" for the created node id or "$name.id" for a specific result field. On failure, earlier successful operations remain applied and the response includes ok:false, failedIndex, error, results, and refs. Supports node.add, node.update, node.remove, graph.add, edge.add, group.create, group.add, group.remove, pin.set/add/remove, snapshot.save, and arrange.',
     formatResult: (result, input) => {
       const envelope = result as BatchEnvelope;
       const payload = wantsFullBatch(input) ? envelope : compactBatchResult(envelope);
@@ -361,5 +386,5 @@ export const batchOperations: Operation[] = [batchOperation];
 export async function runCanvasBatchOperation(
   operations: Array<{ op: string; assign?: string; args?: Record<string, unknown> }>,
 ): Promise<BatchEnvelope> {
-  return await executeOperation('canvas.batch', { operations }) as BatchEnvelope;
+  return (await executeOperation('canvas.batch', { operations })) as BatchEnvelope;
 }

package/src/server/operations/ops/canvas-wire.ts

@@ -0,0 +1,91 @@
+/**
+ * Canvas wire ops (plan-009 C1 slice 3): theme.get / theme.set /
+ * canvas.apply-updates — the remaining simple browser-client routes
+ * (GET+POST /api/canvas/theme, POST /api/canvas/update), wire-identical to
+ * the legacy server.ts handlers they replace. HTTP-only: no MCP tools.
+ *
+ * This module must never import server.ts or index.ts.
+ */
+import { z } from 'zod';
+import { normalizeCanvasTheme } from '../../canvas-db.js';
+import { applyCanvasNodeUpdates } from '../../canvas-operations.js';
+import { canvasState } from '../../canvas-state.js';
+import { defineOperation, type Operation } from '../types.js';
+
+const emptyShape = {};
+const emptySchema = z.looseObject(emptyShape);
+
+const themeGetOperation = defineOperation<z.infer<typeof emptySchema>, Record<string, unknown>>({
+  name: 'theme.get',
+  mutates: false,
+  input: emptySchema,
+  inputShape: emptyShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/theme',
+  },
+  handler: () => ({ ok: true, theme: canvasState.theme }),
+});
+
+const themeSetShape = {
+  theme: z.unknown().optional().describe('Theme: dark, light, or high-contrast'),
+};
+const themeSetSchema = z.looseObject(themeSetShape);
+
+const themeSetOperation = defineOperation<z.infer<typeof themeSetSchema>, Record<string, unknown>>({
+  name: 'theme.set',
+  mutates: false,
+  input: themeSetSchema,
+  inputShape: themeSetShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/theme',
+  },
+  handler: (input, ctx) => {
+    const theme = normalizeCanvasTheme(input.theme, canvasState.theme);
+    const next = canvasState.setTheme(theme);
+    ctx.emit('theme-changed', { theme: next });
+    return { ok: true, theme: next };
+  },
+});
+
+const applyUpdatesShape = {
+  updates: z.unknown().optional().describe('Array of node updates: { id, position?, size?, … }'),
+  recordHistory: z.unknown().optional().describe('Pass false to skip the undo-history entries'),
+};
+const applyUpdatesSchema = z.looseObject(applyUpdatesShape);
+
+const applyUpdatesOperation = defineOperation<z.infer<typeof applyUpdatesSchema>, Record<string, unknown>>({
+  name: 'canvas.apply-updates',
+  mutates: false,
+  input: applyUpdatesSchema,
+  inputShape: applyUpdatesShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/update',
+  },
+  // Legacy wire: one layout update only when something actually applied.
+  handler: (input, ctx) => {
+    const body: Record<string, unknown> = input;
+    const updates = Array.isArray(body.updates) ? body.updates : [];
+    const result =
+      body.recordHistory === false
+        ? (() => {
+            let suppressedResult: ReturnType<typeof applyCanvasNodeUpdates> = {
+              applied: 0,
+              skipped: updates.length,
+            };
+            canvasState.withSuppressedRecording(() => {
+              suppressedResult = applyCanvasNodeUpdates(updates);
+            });
+            return suppressedResult;
+          })()
+        : applyCanvasNodeUpdates(updates);
+    if (result.applied > 0) {
+      ctx.emit('canvas-layout-update', { layout: canvasState.getLayout() });
+    }
+    return { ok: true, ...result };
+  },
+});
+
+export const canvasWireOperations: Operation[] = [themeGetOperation, themeSetOperation, applyUpdatesOperation];