pmx-canvas 0.3.0 → 0.3.2

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

@@ -85,10 +85,7 @@ export interface OpenMcpAppCoreResult {
  * call it. The diagram.open op delegates here after building the Excalidraw input
  * (the SSE pair fires ONCE — diagram.open does not re-emit).
  */
-export async function openMcpAppCore(
-  input: OpenMcpAppCoreInput,
-  ctx: OperationContext,
-): Promise<OpenMcpAppCoreResult> {
+export async function openMcpAppCore(input: OpenMcpAppCoreInput, ctx: OperationContext): Promise<OpenMcpAppCoreResult> {
   // The canvas node is created as a side-effect of the `ext-app-open` SSE event
   // (syncEventToCanvasState). Inside a suppressed-emit run (canvas.batch) that
   // event is dropped, so the node would never be created and the just-opened
@@ -155,10 +152,12 @@ export async function openMcpAppCore(
     success: toolResult.isError !== true,
     result: toolResult,
   });
-  const nodeId = input.nodeId ?? findCanvasExtAppNodeId(toolCallId, {
-    getNode: (id) => canvasState.getNode(id),
-    listNodes: () => canvasState.getLayout().nodes,
-  });
+  const nodeId =
+    input.nodeId ??
+    findCanvasExtAppNodeId(toolCallId, {
+      getNode: (id) => canvasState.getNode(id),
+      listNodes: () => canvasState.getLayout().nodes,
+    });
   return {
     ok: true,
     ...(nodeId ? { id: nodeId } : {}),
@@ -180,15 +179,10 @@ function buildOpenMcpAppInput(body: Record<string, unknown>): OpenMcpAppCoreInpu
     throw new OperationError('Missing valid transport or toolName.');
   }
   const toolArguments = isRecord(body.toolArguments) ? body.toolArguments : undefined;
-  const serverName = typeof body.serverName === 'string' && body.serverName.trim().length > 0
-    ? body.serverName.trim()
-    : undefined;
-  const title = typeof body.title === 'string' && body.title.trim().length > 0
-    ? body.title.trim()
-    : undefined;
-  const nodeId = typeof body.nodeId === 'string' && body.nodeId.trim().length > 0
-    ? body.nodeId.trim()
-    : undefined;
+  const serverName =
+    typeof body.serverName === 'string' && body.serverName.trim().length > 0 ? body.serverName.trim() : undefined;
+  const title = typeof body.title === 'string' && body.title.trim().length > 0 ? body.title.trim() : undefined;
+  const nodeId = typeof body.nodeId === 'string' && body.nodeId.trim().length > 0 ? body.nodeId.trim() : undefined;
   return {
     transport,
     toolName,
@@ -216,21 +210,26 @@ const openMcpAppShape = {
   y: z.number().optional().describe('Y position (auto-placed if omitted)'),
   width: z.number().optional().describe('Width in pixels (default: 720)'),
   height: z.number().optional().describe('Height in pixels (default: 500)'),
-  timeoutMs: z.number().optional().describe('Optional MCP request timeout in milliseconds for cold external app servers'),
-  transport: z.union([
-    z.object({
-      type: z.literal('stdio'),
-      command: z.string().describe('Executable used to start the external MCP server'),
-      args: z.array(z.string()).optional().describe('Arguments for the executable'),
-      cwd: z.string().optional().describe('Optional working directory'),
-      env: z.record(z.string(), z.string()).optional().describe('Optional environment overrides'),
-    }),
-    z.object({
-      type: z.literal('http'),
-      url: z.string().describe('Streamable HTTP MCP endpoint URL'),
-      headers: z.record(z.string(), z.string()).optional().describe('Optional HTTP headers'),
-    }),
-  ]).describe('How PMX Canvas should connect to the external MCP server'),
+  timeoutMs: z
+    .number()
+    .optional()
+    .describe('Optional MCP request timeout in milliseconds for cold external app servers'),
+  transport: z
+    .union([
+      z.object({
+        type: z.literal('stdio'),
+        command: z.string().describe('Executable used to start the external MCP server'),
+        args: z.array(z.string()).optional().describe('Arguments for the executable'),
+        cwd: z.string().optional().describe('Optional working directory'),
+        env: z.record(z.string(), z.string()).optional().describe('Optional environment overrides'),
+      }),
+      z.object({
+        type: z.literal('http'),
+        url: z.string().describe('Streamable HTTP MCP endpoint URL'),
+        headers: z.record(z.string(), z.string()).optional().describe('Optional HTTP headers'),
+      }),
+    ])
+    .describe('How PMX Canvas should connect to the external MCP server'),
 };
 const openMcpAppSchema = z.looseObject(openMcpAppShape);
 
@@ -257,17 +256,29 @@ const openMcpAppOperation = defineOperation<z.infer<typeof openMcpAppSchema>, Op
 // ── diagram.open (Excalidraw preset → mcpapp.open core) ───────
 
 const diagramShape = {
-  elements: z.union([
-    z.string().describe('JSON array string of Excalidraw elements'),
-    z.array(z.record(z.string(), z.unknown())).describe('Array of Excalidraw elements'),
-  ]).describe('Excalidraw elements to render. See https://github.com/excalidraw/excalidraw-mcp for the element format.'),
-  nodeId: z.string().optional().describe('Existing Excalidraw mcp-app node ID to update in place instead of creating a new node.'),
+  elements: z
+    .union([
+      z.string().describe('JSON array string of Excalidraw elements'),
+      z.array(z.record(z.string(), z.unknown())).describe('Array of Excalidraw elements'),
+    ])
+    .describe(
+      'Excalidraw elements to render. See https://github.com/excalidraw/excalidraw-mcp for the element format.',
+    ),
+  nodeId: z
+    .string()
+    .optional()
+    .describe('Existing Excalidraw mcp-app node ID to update in place instead of creating a new node.'),
   title: z.string().optional().describe('Optional canvas node title override'),
   x: z.number().optional().describe('X position (auto-placed if omitted)'),
   y: z.number().optional().describe('Y position (auto-placed if omitted)'),
   width: z.number().optional().describe('Width in pixels (default: 720)'),
   height: z.number().optional().describe('Height in pixels (default: 500)'),
-  timeoutMs: z.number().optional().describe('Optional MCP request timeout in milliseconds for Excalidraw cold starts. Client-side MCP hosts may still enforce their own total request timeout.'),
+  timeoutMs: z
+    .number()
+    .optional()
+    .describe(
+      'Optional MCP request timeout in milliseconds for Excalidraw cold starts. Client-side MCP hosts may still enforce their own total request timeout.',
+    ),
 };
 const diagramSchema = z.looseObject(diagramShape);
 
@@ -289,7 +300,7 @@ const diagramOperation = defineOperation<z.infer<typeof diagramSchema>, OpenMcpA
     }),
   },
   handler: (input, ctx) => {
-    let built;
+    let built: ReturnType<typeof buildExcalidrawOpenMcpAppInput>;
     try {
       built = buildExcalidrawOpenMcpAppInput(input);
     } catch (error) {
@@ -297,19 +308,22 @@ const diagramOperation = defineOperation<z.infer<typeof diagramSchema>, OpenMcpA
     }
     // Delegate to the shared open core (the SSE pair fires once — diagram.open
     // does not re-emit).
-    return openMcpAppCore({
-      transport: built.transport,
-      toolName: built.toolName,
-      toolArguments: built.toolArguments,
-      serverName: built.serverName,
-      ...(built.nodeId ? { nodeId: built.nodeId } : {}),
-      ...(built.title ? { title: built.title } : {}),
-      ...(typeof built.x === 'number' ? { x: built.x } : {}),
-      ...(typeof built.y === 'number' ? { y: built.y } : {}),
-      ...(typeof built.width === 'number' ? { width: built.width } : {}),
-      ...(typeof built.height === 'number' ? { height: built.height } : {}),
-      ...(typeof built.timeoutMs === 'number' ? { timeoutMs: built.timeoutMs } : {}),
-    }, ctx);
+    return openMcpAppCore(
+      {
+        transport: built.transport,
+        toolName: built.toolName,
+        toolArguments: built.toolArguments,
+        serverName: built.serverName,
+        ...(built.nodeId ? { nodeId: built.nodeId } : {}),
+        ...(built.title ? { title: built.title } : {}),
+        ...(typeof built.x === 'number' ? { x: built.x } : {}),
+        ...(typeof built.y === 'number' ? { y: built.y } : {}),
+        ...(typeof built.width === 'number' ? { width: built.width } : {}),
+        ...(typeof built.height === 'number' ? { height: built.height } : {}),
+        ...(typeof built.timeoutMs === 'number' ? { timeoutMs: built.timeoutMs } : {}),
+      },
+      ctx,
+    );
   },
 });
 
@@ -321,23 +335,42 @@ const webArtifactShape = {
   indexCss: z.string().optional().describe('Optional contents for src/index.css'),
   mainTsx: z.string().optional().describe('Optional contents for src/main.tsx'),
   indexHtml: z.string().optional().describe('Optional contents for index.html'),
-  files: z.record(z.string(), z.string()).optional().describe('Optional map of additional project-relative file paths to file contents'),
-  deps: z.array(z.string()).optional().describe('Optional npm dependencies to install before bundling (e.g. ["recharts", "framer-motion@^11"]). Validated against npm-name format; flags and shell metacharacters are rejected.'),
-  projectPath: z.string().optional().describe('Optional workspace-relative reusable project path. Defaults to .pmx-canvas/artifacts/.web-artifacts/<slug>'),
-  outputPath: z.string().optional().describe('Optional workspace-relative HTML output path. Defaults to .pmx-canvas/artifacts/<slug>.html'),
+  files: z
+    .record(z.string(), z.string())
+    .optional()
+    .describe('Optional map of additional project-relative file paths to file contents'),
+  deps: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Optional npm dependencies to install before bundling (e.g. ["recharts", "framer-motion@^11"]). Validated against npm-name format; flags and shell metacharacters are rejected.',
+    ),
+  projectPath: z
+    .string()
+    .optional()
+    .describe(
+      'Optional workspace-relative reusable project path. Defaults to .pmx-canvas/artifacts/.web-artifacts/<slug>',
+    ),
+  outputPath: z
+    .string()
+    .optional()
+    .describe('Optional workspace-relative HTML output path. Defaults to .pmx-canvas/artifacts/<slug>.html'),
   openInCanvas: z.boolean().optional().describe('Open the generated artifact in canvas after build (default true)'),
   includeLogs: z.boolean().optional().describe('Include raw build stdout/stderr in the response (default false)'),
-  initScriptPath: z.string().optional().describe('Optional script path override for tests/debugging. Must resolve inside the workspace.'),
-  bundleScriptPath: z.string().optional().describe('Optional script path override for tests/debugging. Must resolve inside the workspace.'),
+  initScriptPath: z
+    .string()
+    .optional()
+    .describe('Optional script path override for tests/debugging. Must resolve inside the workspace.'),
+  bundleScriptPath: z
+    .string()
+    .optional()
+    .describe('Optional script path override for tests/debugging. Must resolve inside the workspace.'),
   timeoutMs: z.number().optional().describe('Optional timeout in milliseconds for init and bundle commands'),
 };
 const webArtifactSchema = z.looseObject(webArtifactShape);
 
 /** Shape the byte-identical web-artifact response envelope from the build result. */
-function webArtifactEnvelope(
-  result: WebArtifactCanvasBuildResult,
-  includeLogs: boolean,
-): Record<string, unknown> {
+function webArtifactEnvelope(result: WebArtifactCanvasBuildResult, includeLogs: boolean): Record<string, unknown> {
   return {
     ok: true,
     path: result.filePath,
@@ -415,12 +448,8 @@ const webArtifactOperation = defineOperation<z.infer<typeof webArtifactSchema>,
         // legacy HTTP handler used resolveWorkspacePath; the MCP tool used its
         // own safeWorkspacePath — both enforce containment). resolveWorkspacePath
         // resolves against the active canvas workspace root.
-        ...(typeof input.projectPath === 'string'
-          ? { projectPath: resolveWorkspacePath(input.projectPath) }
-          : {}),
-        ...(typeof input.outputPath === 'string'
-          ? { outputPath: resolveWorkspacePath(input.outputPath) }
-          : {}),
+        ...(typeof input.projectPath === 'string' ? { projectPath: resolveWorkspacePath(input.projectPath) } : {}),
+        ...(typeof input.outputPath === 'string' ? { outputPath: resolveWorkspacePath(input.outputPath) } : {}),
         // Script-path overrides are honored only when contained inside the
         // workspace (enforced by resolveTrustedScriptPath in
         // executeWebArtifactBuild), so they cannot point at an arbitrary host
@@ -440,8 +469,4 @@ const webArtifactOperation = defineOperation<z.infer<typeof webArtifactSchema>,
   },
 });
 
-export const appOperations: Operation[] = [
-  openMcpAppOperation,
-  diagramOperation,
-  webArtifactOperation,
-];
+export const appOperations: Operation[] = [openMcpAppOperation, diagramOperation, webArtifactOperation];

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

@@ -92,7 +92,13 @@ const awaitInputSchema = z.looseObject(awaitInputShape);
 
 const awaitMcpExtraShape = {
   id: z.string(),
-  timeoutMs: z.number().int().min(0).max(120000).optional().describe('Max ms to block (default 30000; 0 = immediate read; capped at 120000).'),
+  timeoutMs: z
+    .number()
+    .int()
+    .min(0)
+    .max(120000)
+    .optional()
+    .describe('Max ms to block (default 30000; 0 = immediate read; capped at 120000).'),
 };
 
 // ── ax.approval.get (canvas_await_approval) ───────────────────
@@ -110,7 +116,8 @@ const axApprovalGetOperation = defineOperation<z.infer<typeof awaitInputSchema>,
   },
   mcp: {
     toolName: 'canvas_await_approval',
-    description: 'Block until an approval gate resolves (the human approves/rejects it in the browser) or the timeout elapses — primitive D, gates that actually gate. timeoutMs 0 = read immediately without waiting. Returns { approvalGate, pending } (pending=true → still unresolved after the wait).',
+    description:
+      'Block until an approval gate resolves (the human approves/rejects it in the browser) or the timeout elapses — primitive D, gates that actually gate. timeoutMs 0 = read immediately without waiting. Returns { approvalGate, pending } (pending=true → still unresolved after the wait).',
     extraShape: awaitMcpExtraShape,
     buildInput: buildAwaitInput,
     formatResult: (result) => {
@@ -118,7 +125,9 @@ const axApprovalGetOperation = defineOperation<z.infer<typeof awaitInputSchema>,
       const approvalGate = (body.approvalGate ?? null) as PmxAxApprovalGate | null;
       const pending = body.pending === true;
       return {
-        content: [{ type: 'text' as const, text: JSON.stringify({ ok: approvalGate !== null, approvalGate, pending }) }],
+        content: [
+          { type: 'text' as const, text: JSON.stringify({ ok: approvalGate !== null, approvalGate, pending }) },
+        ],
       };
     },
   },
@@ -148,7 +157,8 @@ const axElicitationGetOperation = defineOperation<z.infer<typeof awaitInputSchem
   },
   mcp: {
     toolName: 'canvas_await_elicitation',
-    description: 'Block until an elicitation is answered (the human responds in the browser) or the timeout elapses — primitive D. timeoutMs 0 = read immediately. Returns { elicitation, pending }.',
+    description:
+      'Block until an elicitation is answered (the human responds in the browser) or the timeout elapses — primitive D. timeoutMs 0 = read immediately. Returns { elicitation, pending }.',
     extraShape: awaitMcpExtraShape,
     buildInput: buildAwaitInput,
     formatResult: (result) => {
@@ -186,7 +196,8 @@ const axModeGetOperation = defineOperation<z.infer<typeof awaitInputSchema>, Rec
   },
   mcp: {
     toolName: 'canvas_await_mode',
-    description: 'Block until a mode request resolves (approved/rejected in the browser) or the timeout elapses — primitive D. timeoutMs 0 = read immediately. Returns { modeRequest, pending }.',
+    description:
+      'Block until a mode request resolves (approved/rejected in the browser) or the timeout elapses — primitive D. timeoutMs 0 = read immediately. Returns { modeRequest, pending }.',
     extraShape: awaitMcpExtraShape,
     buildInput: buildAwaitInput,
     formatResult: (result) => {
@@ -209,8 +220,4 @@ const axModeGetOperation = defineOperation<z.infer<typeof awaitInputSchema>, Rec
   },
 });
 
-export const axAwaitOperations: Operation[] = [
-  axApprovalGetOperation,
-  axElicitationGetOperation,
-  axModeGetOperation,
-];
+export const axAwaitOperations: Operation[] = [axApprovalGetOperation, axElicitationGetOperation, axModeGetOperation];

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,
+];