pmx-canvas 0.2.7 → 0.3.1

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

@@ -0,0 +1,347 @@
+/**
+ * AX read + wire-compat operations (plan-009 C1 slice 2): the GET read
+ * surface (`ax/work`, `ax/approval`, `ax/review`, `ax/elicitation`,
+ * `ax/mode`, `ax/command`, `ax/policy`, `ax/host-capability`, `ax/context`,
+ * `ax/surface-snapshot`, `pinned-context`, `code-graph`) plus the three
+ * remaining AX writes (`ax/activity` ingest, `ax/interaction` submit, and
+ * the legacy `PATCH /api/canvas/ax` focus shape). Wire envelopes are
+ * byte-identical to the legacy server.ts handlers they replace. HTTP-only:
+ * the MCP read surface stays the composites/resources — no new tools, the
+ * frozen 27-tool surface is untouched.
+ *
+ * This module must never import server.ts or index.ts.
+ */
+import { z } from 'zod';
+import { buildAgentContextPreamble, serializeNodeForAgentContext } from '../../agent-context.js';
+import { buildCanvasAxContext, buildCanvasAxSurfaceSnapshot } from '../../ax-context.js';
+import { applyAxInteraction } from '../../ax-interaction.js';
+import {
+  isAxActivityKind,
+  isAxEvidenceKind,
+  type PmxAxEvidenceKind,
+  type PmxAxReviewAnchorType,
+  type PmxAxReviewKind,
+  type PmxAxReviewSeverity,
+  type PmxAxWorkItemStatus,
+} from '../../ax-state.js';
+import { canvasState, type CanvasNodeState } from '../../canvas-state.js';
+import { buildCodeGraphSummary } from '../../code-graph.js';
+import { defineOperation, OperationError, type Operation, type OperationContext } from '../types.js';
+import { normalizeAxNodeIds, normalizeAxSource } from './ax-shared.js';
+import { isRecord } from './nodes.js';
+
+// ── Activity-reaction validation (moved from server.ts) ───────
+
+const AX_WORK_STATUSES = new Set(['todo', 'in-progress', 'blocked', 'done', 'cancelled']);
+
+function normalizeAxWorkItemStatus(value: unknown): PmxAxWorkItemStatus | undefined {
+  return typeof value === 'string' && AX_WORK_STATUSES.has(value) ? (value as PmxAxWorkItemStatus) : undefined;
+}
+
+function isReviewSeverity(v: unknown): v is PmxAxReviewSeverity {
+  return v === 'info' || v === 'warning' || v === 'error';
+}
+function isReviewKind(v: unknown): v is PmxAxReviewKind {
+  return v === 'comment' || v === 'finding';
+}
+function isReviewAnchor(v: unknown): v is PmxAxReviewAnchorType {
+  return v === 'node' || v === 'file' || v === 'region';
+}
+
+// Validate untrusted activity `reactions` from an HTTP body into the typed override
+// shape ingestActivity expects. `false` suppresses a default reaction; an object
+// overrides its fields (invalid fields are dropped, not stored raw).
+function normalizeActivityReactions(input: Record<string, unknown>): {
+  workItem?: false | { status?: PmxAxWorkItemStatus; detail?: string | null };
+  evidence?: false | { kind?: PmxAxEvidenceKind; body?: string | null };
+  review?:
+    | false
+    | {
+        severity?: PmxAxReviewSeverity;
+        kind?: PmxAxReviewKind;
+        anchorType?: PmxAxReviewAnchorType;
+        nodeId?: string | null;
+      };
+} {
+  const out: ReturnType<typeof normalizeActivityReactions> = {};
+  if (input.workItem === false) out.workItem = false;
+  else if (isRecord(input.workItem)) {
+    const status = normalizeAxWorkItemStatus(input.workItem.status);
+    out.workItem = {
+      ...(status ? { status } : {}),
+      ...(typeof input.workItem.detail === 'string' ? { detail: input.workItem.detail } : {}),
+    };
+  }
+  if (input.evidence === false) out.evidence = false;
+  else if (isRecord(input.evidence)) {
+    out.evidence = {
+      ...(isAxEvidenceKind(input.evidence.kind) ? { kind: input.evidence.kind } : {}),
+      ...(typeof input.evidence.body === 'string' ? { body: input.evidence.body } : {}),
+    };
+  }
+  if (input.review === false) out.review = false;
+  else if (isRecord(input.review)) {
+    out.review = {
+      ...(isReviewSeverity(input.review.severity) ? { severity: input.review.severity } : {}),
+      ...(isReviewKind(input.review.kind) ? { kind: input.review.kind } : {}),
+      ...(isReviewAnchor(input.review.anchorType) ? { anchorType: input.review.anchorType } : {}),
+      ...(typeof input.review.nodeId === 'string' ? { nodeId: input.review.nodeId } : {}),
+    };
+  }
+  return out;
+}
+
+// ── GET list/read factory ─────────────────────────────────────
+
+const emptyShape = {};
+const emptySchema = z.looseObject(emptyShape);
+
+/** A no-input GET whose body is `{ ok: true, ...read() }` (legacy list shape). */
+function defineAxListOperation(name: string, path: string, read: () => Record<string, unknown>): Operation {
+  return defineOperation<z.infer<typeof emptySchema>, Record<string, unknown>>({
+    name,
+    mutates: false,
+    input: emptySchema,
+    inputShape: emptyShape,
+    http: {
+      method: 'GET',
+      path,
+    },
+    handler: () => ({ ok: true, ...read() }),
+  });
+}
+
+// ── ax.context.get / ax.surface-snapshot.get ──────────────────
+
+const axContextShape = {
+  consumer: z.unknown().optional().describe('Optional consumer label filtering the pending-delivery lead block'),
+};
+const axContextSchema = z.looseObject(axContextShape);
+
+const axContextGetOperation = defineOperation<z.infer<typeof axContextSchema>, Record<string, unknown>>({
+  name: 'ax.context.get',
+  mutates: false,
+  input: axContextSchema,
+  inputShape: axContextShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/ax/context',
+  },
+  // Optional ?consumer= filters the compact `delivery` lead block (loop-safe — a
+  // consumer never sees steering/activity it originated), so a host adapter can
+  // inject its own un-truncated pending block per turn (report #54 hardening).
+  handler: (input) => {
+    const consumer = typeof input.consumer === 'string' ? input.consumer : undefined;
+    return buildCanvasAxContext(consumer) as unknown as Record<string, unknown>;
+  },
+});
+
+const axSurfaceSnapshotOperation = defineOperation<z.infer<typeof emptySchema>, Record<string, unknown>>({
+  name: 'ax.surface-snapshot.get',
+  mutates: false,
+  input: emptySchema,
+  inputShape: emptyShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/ax/surface-snapshot',
+  },
+  // Compact AX state for surfaces (the same shape seeded into AX-enabled iframes).
+  // The client fetches this and pushes it to surfaces over the ax-update channel.
+  handler: () => buildCanvasAxSurfaceSnapshot() as unknown as Record<string, unknown>,
+});
+
+// ── pinned-context.get ────────────────────────────────────────
+
+const pinnedContextOperation = defineOperation<z.infer<typeof emptySchema>, Record<string, unknown>>({
+  name: 'pinned-context.get',
+  mutates: false,
+  input: emptySchema,
+  inputShape: emptyShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/pinned-context',
+  },
+  handler: () => {
+    const pinnedIds = Array.from(canvasState.contextPinnedNodeIds);
+    const nodes = pinnedIds
+      .map((id) => canvasState.getNode(id))
+      .filter((node): node is CanvasNodeState => node !== undefined);
+    const preamble =
+      pinnedIds.length > 0 ? buildAgentContextPreamble(nodes, { defaultTextLength: 700, webpageTextLength: 1600 }) : '';
+    const serialized = nodes.map((node) =>
+      serializeNodeForAgentContext(node, {
+        defaultTextLength: 700,
+        webpageTextLength: 1600,
+        includePosition: true,
+      }),
+    );
+    return { preamble, nodeIds: pinnedIds, count: pinnedIds.length, nodes: serialized };
+  },
+});
+
+// ── code-graph.get ────────────────────────────────────────────
+
+const codeGraphOperation = defineOperation<z.infer<typeof emptySchema>, Record<string, unknown>>({
+  name: 'code-graph.get',
+  mutates: false,
+  input: emptySchema,
+  inputShape: emptyShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/code-graph',
+  },
+  handler: () => buildCodeGraphSummary() as unknown as Record<string, unknown>,
+});
+
+// ── ax.activity.ingest ────────────────────────────────────────
+
+const activityShape = {
+  kind: z
+    .unknown()
+    .optional()
+    .describe('Activity kind: tool-start, tool-result, failure, error, session-start, session-end, command, note'),
+  title: z.unknown().optional().describe('Activity title'),
+  summary: z.unknown().optional(),
+  outcome: z.unknown().optional().describe('success or failure'),
+  ref: z.unknown().optional().describe('File path, URL, or commit the activity refers to'),
+  nodeIds: z.unknown().optional(),
+  data: z.unknown().optional(),
+  reactions: z.unknown().optional().describe('Override or suppress the kind-driven default reactions'),
+  source: z.unknown().optional(),
+};
+const activitySchema = z.looseObject(activityShape);
+
+// Report primitive A: ingest a harness-forwarded agent activity; the board auto-reacts.
+const activityIngestOperation = defineOperation<z.infer<typeof activitySchema>, Record<string, unknown>>({
+  name: 'ax.activity.ingest',
+  mutates: false,
+  input: activitySchema,
+  inputShape: activityShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/ax/activity',
+  },
+  handler: (input, ctx: OperationContext) => {
+    const body: Record<string, unknown> = input;
+    if (!isAxActivityKind(body.kind)) {
+      throw new OperationError(
+        "activity requires a valid 'kind': one of tool-start, tool-result, failure, error, session-start, session-end, command, note.",
+      );
+    }
+    if (typeof body.title !== 'string' || !body.title.trim()) {
+      throw new OperationError('activity requires a title.');
+    }
+    const result = canvasState.ingestActivity(
+      {
+        kind: body.kind,
+        title: body.title,
+        ...(typeof body.summary === 'string' ? { summary: body.summary } : {}),
+        ...(body.outcome === 'success' || body.outcome === 'failure' ? { outcome: body.outcome } : {}),
+        ...(typeof body.ref === 'string' ? { ref: body.ref } : {}),
+        ...(Array.isArray(body.nodeIds) ? { nodeIds: normalizeAxNodeIds(body.nodeIds) } : {}),
+        ...(isRecord(body.data) ? { data: body.data } : {}),
+        ...(isRecord(body.reactions) ? { reactions: normalizeActivityReactions(body.reactions) } : {}),
+      },
+      { source: normalizeAxSource(body.source, 'api') },
+    );
+    ctx.emit('ax-event-created', { event: result.event });
+    if (result.workItem) ctx.emit('ax-state-changed', { workItem: result.workItem });
+    if (result.evidence) ctx.emit('ax-event-created', { evidence: result.evidence });
+    if (result.review) ctx.emit('ax-state-changed', { reviewAnnotation: result.review });
+    return { ok: true, ...result };
+  },
+});
+
+// ── ax.interaction.submit ─────────────────────────────────────
+
+const interactionShape = {
+  type: z.unknown().optional().describe('Interaction type, e.g. ax.work.create'),
+  sourceNodeId: z.unknown().optional(),
+  payload: z.unknown().optional(),
+  sourceSurface: z.unknown().optional(),
+  correlationId: z.unknown().optional(),
+  source: z.unknown().optional(),
+};
+const interactionSchema = z.looseObject(interactionShape);
+
+const interactionOperation = defineOperation<z.infer<typeof interactionSchema>, Record<string, unknown>>({
+  name: 'ax.interaction.submit',
+  mutates: false,
+  input: interactionSchema,
+  inputShape: interactionShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/ax/interaction',
+    // 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,
+  },
+  handler: (input, ctx: OperationContext) => {
+    const body: Record<string, unknown> = input;
+    const { result, events } = applyAxInteraction(canvasState, body, normalizeAxSource(body.source, 'api'));
+    for (const e of events) {
+      ctx.emit(e.event, e.payload);
+    }
+    return result as unknown as Record<string, unknown>;
+  },
+});
+
+// ── ax.state.patch (legacy PATCH /api/canvas/ax focus shape) ──
+
+const statePatchShape = {
+  focus: z.unknown().optional().describe('Focus object: { nodeIds, source? }'),
+};
+const statePatchSchema = z.looseObject(statePatchShape);
+
+const statePatchOperation = defineOperation<z.infer<typeof statePatchSchema>, Record<string, unknown>>({
+  name: 'ax.state.patch',
+  mutates: false,
+  input: statePatchSchema,
+  inputShape: statePatchShape,
+  http: {
+    method: 'PATCH',
+    path: '/api/canvas/ax',
+  },
+  handler: (input, ctx: OperationContext) => {
+    const body: Record<string, unknown> = input;
+    if (!body.focus || typeof body.focus !== 'object' || Array.isArray(body.focus)) {
+      throw new OperationError('PATCH /api/canvas/ax currently requires a focus object.');
+    }
+    const focusInput = body.focus as Record<string, unknown>;
+    const focus = canvasState.setAxFocus(normalizeAxNodeIds(focusInput.nodeIds), {
+      source: normalizeAxSource(focusInput.source, 'api'),
+    });
+    ctx.emit('ax-state-changed', { focus });
+    return { ok: true, state: canvasState.getAxState() };
+  },
+});
+
+export const axReadOperations: Operation[] = [
+  defineAxListOperation('ax.work.list', '/api/canvas/ax/work', () => ({ workItems: canvasState.getWorkItems() })),
+  defineAxListOperation('ax.approval.list', '/api/canvas/ax/approval', () => ({
+    approvalGates: canvasState.getApprovalGates(),
+  })),
+  defineAxListOperation('ax.review.list', '/api/canvas/ax/review', () => ({
+    reviewAnnotations: canvasState.getReviewAnnotations(),
+  })),
+  defineAxListOperation('ax.elicitation.list', '/api/canvas/ax/elicitation', () => ({
+    elicitations: canvasState.getElicitations(),
+  })),
+  defineAxListOperation('ax.mode.list', '/api/canvas/ax/mode', () => ({
+    modeRequests: canvasState.getModeRequests(),
+  })),
+  defineAxListOperation('ax.command.list', '/api/canvas/ax/command', () => ({
+    commands: canvasState.getCommandRegistry(),
+  })),
+  defineAxListOperation('ax.policy.get', '/api/canvas/ax/policy', () => ({ policy: canvasState.getPolicy() })),
+  defineAxListOperation('ax.host-capability.get', '/api/canvas/ax/host-capability', () => ({
+    host: canvasState.getHostCapability(),
+  })),
+  axContextGetOperation,
+  axSurfaceSnapshotOperation,
+  pinnedContextOperation,
+  codeGraphOperation,
+  activityIngestOperation,
+  interactionOperation,
+  statePatchOperation,
+];

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 });