pmx-canvas 0.1.35 → 0.2.0

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

@@ -0,0 +1,447 @@
+/**
+ * External / built-content app operations (plan-008 Wave 4):
+ *   mcpapp.open      → canvas_open_mcp_app      → POST /api/canvas/mcp-app/open
+ *   diagram.open     → canvas_add_diagram       → POST /api/canvas/diagram
+ *   webartifact.build → canvas_build_web_artifact → POST /api/canvas/web-artifact
+ *
+ * These were deferred in plan-005/006 as "poor fits" (stateful external MCP
+ * session + custom SSE; long-running build). On reflection they migrate cleanly:
+ * `executeOperation` is async (the long-running build fits — its "long-running"
+ * caveat is about MCP client timeouts, not registry fit), and their runtimes are
+ * server-independent DOMAIN modules (mcp-app-runtime, diagram-presets,
+ * web-artifacts), not server.ts. So the op handlers call those modules directly
+ * — no runner injection needed.
+ *
+ * SSE parity (these are NOT canvas node/edge state mutations, so `mutates:false`
+ * — the registry must NOT emit canvas-layout-update):
+ *  - mcpapp.open / diagram.open emit `ext-app-open` + `ext-app-result` via
+ *    ctx.emit, byte-identical to the legacy emitPrimaryWorkbenchEvent calls.
+ *  - webartifact.build's node creation emits its own `canvas-layout-update` from
+ *    inside web-artifacts.ts (the injected canvas-operations emitter), so the op
+ *    must not re-emit.
+ *
+ * Local-vs-remote asymmetry (the only allowed unification — documented):
+ * mcpapp.open's node-precondition failures THROW an OperationError here (404 for
+ * a missing node, 400 for a non-ext-app node). Over HTTP that becomes
+ * `{ ok:false, error }` with the right status (matching the legacy handler's
+ * explicit 404/400 responses); over MCP it becomes a bare-message isError result.
+ * The legacy SDK threw a plain Error for the same case; the registry's
+ * OperationError carries the status so the HTTP surface is unchanged.
+ *
+ * This module must never import server.ts or index.ts.
+ */
+import { z } from 'zod';
+import { canvasState } from '../../canvas-state.js';
+import {
+  closeMcpAppSession,
+  openMcpApp as openExternalMcpApp,
+  type ExternalMcpTransportConfig,
+} from '../../mcp-app-runtime.js';
+import {
+  buildExcalidrawOpenMcpAppInput,
+  ensureExcalidrawCheckpointId,
+  isExcalidrawCreateView,
+} from '../../diagram-presets.js';
+import { findCanvasExtAppNodeId } from '../../ext-app-lookup.js';
+import {
+  buildWebArtifactOnCanvas,
+  resolveWorkspacePath,
+  type WebArtifactCanvasBuildResult,
+} from '../../web-artifacts.js';
+import { isEmitSuppressed } from '../registry.js';
+import { defineOperation, OperationError, type Operation, type OperationContext } from '../types.js';
+import { isRecord } from './nodes.js';
+
+// ── shared open-mcp-app core ──────────────────────────────────
+
+export interface OpenMcpAppCoreInput {
+  transport: ExternalMcpTransportConfig;
+  toolName: string;
+  toolArguments?: Record<string, unknown>;
+  nodeId?: string;
+  serverName?: string;
+  title?: string;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  timeoutMs?: number;
+}
+
+export interface OpenMcpAppCoreResult {
+  ok: true;
+  id?: string;
+  nodeId: string | null;
+  toolCallId: string;
+  sessionId: string;
+  resourceUri: string;
+}
+
+/**
+ * Open an external MCP app: connect + call + read resource (openExternalMcpApp),
+ * close any prior session on an in-place node, emit `ext-app-open` +
+ * `ext-app-result`, then resolve the resulting canvas node id. This is the exact
+ * legacy SDK `openMcpApp` body, relocated; both the mcpapp.open op AND the SDK
+ * 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> {
+  // 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
+  // external session would leak with a null nodeId. Reject loudly BEFORE opening
+  // any session rather than silently corrupting. mcpapp.open / diagram.open are
+  // not batchable — call canvas_open_mcp_app / canvas_add_diagram (or canvas_app).
+  if (isEmitSuppressed()) {
+    throw new OperationError(
+      'mcpapp.open / diagram.open cannot run inside canvas_batch: the canvas node is created from the ext-app-open SSE event, which batch suppresses. Call the op directly (canvas_open_mcp_app / canvas_add_diagram, or canvas_app).',
+    );
+  }
+  const targetNode = input.nodeId ? canvasState.getNode(input.nodeId) : undefined;
+  if (input.nodeId && !targetNode) {
+    throw new OperationError(`Node "${input.nodeId}" not found.`, 404);
+  }
+  if (targetNode && (targetNode.type !== 'mcp-app' || targetNode.data.mode !== 'ext-app')) {
+    throw new OperationError(`Node "${input.nodeId}" is not an external app node.`);
+  }
+
+  const opened = await openExternalMcpApp({
+    transport: input.transport,
+    toolName: input.toolName,
+    ...(input.toolArguments ? { toolArguments: input.toolArguments } : {}),
+    ...(input.serverName ? { serverName: input.serverName } : {}),
+    ...(typeof input.timeoutMs === 'number' ? { timeoutMs: input.timeoutMs } : {}),
+  });
+  const toolCallId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const previousSessionId = targetNode?.data.appSessionId;
+  if (typeof previousSessionId === 'string' && previousSessionId.trim().length > 0) {
+    closeMcpAppSession(previousSessionId);
+  }
+  const nodeIdSeed = input.nodeId ?? `ext-app-${toolCallId}`;
+  const toolResult = isExcalidrawCreateView(opened.serverName, opened.toolName)
+    ? ensureExcalidrawCheckpointId(opened.toolResult, nodeIdSeed)
+    : opened.toolResult;
+  ctx.emit('ext-app-open', {
+    toolCallId,
+    nodeId: nodeIdSeed,
+    // Preserve an existing in-place node's title when no override is given (legacy
+    // runAndEmitOpenMcpApp fallback order) — otherwise an in-place update with no
+    // `title` would reset the node title to the external tool's name.
+    title: input.title ?? (targetNode?.data.title as string | undefined) ?? opened.tool.title ?? opened.tool.name,
+    html: opened.html,
+    toolInput: opened.toolInput,
+    serverName: opened.serverName,
+    toolName: opened.toolName,
+    appSessionId: opened.sessionId,
+    transportConfig: input.transport,
+    resourceUri: opened.resourceUri,
+    toolDefinition: opened.tool,
+    sessionStatus: 'ready',
+    sessionError: null,
+    ...(opened.resourceMeta ? { resourceMeta: opened.resourceMeta } : {}),
+    ...(typeof input.x === 'number' ? { x: input.x } : {}),
+    ...(typeof input.y === 'number' ? { y: input.y } : {}),
+    ...(typeof input.width === 'number' ? { width: input.width } : {}),
+    ...(typeof input.height === 'number' ? { height: input.height } : {}),
+  });
+  ctx.emit('ext-app-result', {
+    toolCallId,
+    nodeId: nodeIdSeed,
+    serverName: opened.serverName,
+    toolName: opened.toolName,
+    success: toolResult.isError !== true,
+    result: toolResult,
+  });
+  const nodeId = input.nodeId ?? findCanvasExtAppNodeId(toolCallId, {
+    getNode: (id) => canvasState.getNode(id),
+    listNodes: () => canvasState.getLayout().nodes,
+  });
+  return {
+    ok: true,
+    ...(nodeId ? { id: nodeId } : {}),
+    nodeId,
+    toolCallId,
+    sessionId: opened.sessionId,
+    resourceUri: opened.resourceUri,
+  };
+}
+
+/** Build the OpenMcpAppCoreInput from a raw HTTP/MCP arg object (mcpapp.open). */
+function buildOpenMcpAppInput(body: Record<string, unknown>): OpenMcpAppCoreInput {
+  const transport = body.transport as ExternalMcpTransportConfig | undefined;
+  if (!isRecord(transport)) {
+    throw new OperationError('Missing valid transport or toolName.');
+  }
+  const toolName = typeof body.toolName === 'string' ? body.toolName.trim() : '';
+  if (!toolName) {
+    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;
+  return {
+    transport,
+    toolName,
+    ...(toolArguments ? { toolArguments } : {}),
+    ...(serverName ? { serverName } : {}),
+    ...(title ? { title } : {}),
+    ...(nodeId ? { nodeId } : {}),
+    ...(typeof body.x === 'number' ? { x: body.x } : {}),
+    ...(typeof body.y === 'number' ? { y: body.y } : {}),
+    ...(typeof body.width === 'number' ? { width: body.width } : {}),
+    ...(typeof body.height === 'number' ? { height: body.height } : {}),
+    ...(typeof body.timeoutMs === 'number' ? { timeoutMs: body.timeoutMs } : {}),
+  };
+}
+
+// ── mcpapp.open ───────────────────────────────────────────────
+
+const openMcpAppShape = {
+  toolName: z.string().describe('Tool name on the external MCP server'),
+  serverName: z.string().optional().describe('Optional display name for the external MCP server'),
+  toolArguments: z.record(z.string(), z.unknown()).optional().describe('Arguments passed to the external tool call'),
+  nodeId: z.string().optional().describe('Existing 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 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);
+
+const openMcpAppOperation = defineOperation<z.infer<typeof openMcpAppSchema>, OpenMcpAppCoreResult>({
+  name: 'mcpapp.open',
+  mutates: false,
+  input: openMcpAppSchema,
+  inputShape: openMcpAppShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/mcp-app/open',
+  },
+  mcp: {
+    toolName: 'canvas_open_mcp_app',
+    description:
+      'Connect to an external MCP server that declares a ui:// app resource, call the specified tool, and open the resulting MCP App inside a canvas mcp-app node. This is a full external-MCP transport call, not the CLI kind shortcut; use canvas_add_diagram for the built-in Excalidraw preset.',
+    formatResult: (result) => ({
+      content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+    }),
+  },
+  handler: (input, ctx) => openMcpAppCore(buildOpenMcpAppInput(input), ctx),
+});
+
+// ── 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.'),
+  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.'),
+};
+const diagramSchema = z.looseObject(diagramShape);
+
+const diagramOperation = defineOperation<z.infer<typeof diagramSchema>, OpenMcpAppCoreResult>({
+  name: 'diagram.open',
+  mutates: false,
+  input: diagramSchema,
+  inputShape: diagramShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/diagram',
+  },
+  mcp: {
+    toolName: 'canvas_add_diagram',
+    description:
+      'Draw a hand-drawn diagram on the canvas via the hosted Excalidraw MCP app. Pass an array of Excalidraw elements (rectangles, ellipses, diamonds, arrows, text). The diagram opens inside an mcp-app node that supports fullscreen editing. For other MCP apps, use canvas_open_mcp_app.',
+    formatResult: (result) => ({
+      content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+    }),
+  },
+  handler: (input, ctx) => {
+    let built;
+    try {
+      built = buildExcalidrawOpenMcpAppInput(input);
+    } catch (error) {
+      throw new OperationError(error instanceof Error ? error.message : String(error));
+    }
+    // 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);
+  },
+});
+
+// ── webartifact.build ─────────────────────────────────────────
+
+const webArtifactShape = {
+  title: z.string().describe('Artifact title used for default project and output paths'),
+  appTsx: z.string().describe('Contents for src/App.tsx'),
+  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'),
+  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.'),
+  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> {
+  return {
+    ok: true,
+    path: result.filePath,
+    bytes: result.fileSize,
+    projectPath: result.projectPath,
+    openedInCanvas: result.openedInCanvas,
+    startedAt: result.startedAt,
+    completedAt: result.completedAt,
+    durationMs: result.durationMs,
+    timeoutMs: result.timeoutMs,
+    // `id` is the canvas node id alias used by every other add-style response.
+    // It is only present when a canvas node was actually created (openInCanvas
+    // not explicitly disabled), so consumers can `'id' in response` to detect
+    // the build-only case.
+    ...(typeof result.nodeId === 'string' ? { id: result.nodeId } : {}),
+    nodeId: result.nodeId,
+    url: result.url,
+    metadata: result.metadata,
+    logs: result.logs,
+    ...(includeLogs ? { stdout: result.stdout, stderr: result.stderr } : {}),
+  };
+}
+
+const webArtifactOperation = defineOperation<z.infer<typeof webArtifactSchema>, Record<string, unknown>>({
+  name: 'webartifact.build',
+  // mutates:false — web-artifacts.ts emits its own canvas-layout-update on node
+  // creation (the injected canvas-operations emitter); the registry must NOT
+  // double-emit.
+  mutates: false,
+  input: webArtifactSchema,
+  inputShape: webArtifactShape,
+  http: {
+    method: 'POST',
+    path: '/api/canvas/web-artifact',
+  },
+  mcp: {
+    toolName: 'canvas_build_web_artifact',
+    description:
+      'Build a bundled single-file HTML web artifact from React/Tailwind source files using the bundled web-artifacts-builder skill scripts. MCP callers pass source content in appTsx (the CLI app-file flag reads a file before calling this path). Builds can exceed default 60s MCP client timeouts on cold workspaces; set a long client timeout or retry with the same projectPath/outputPath if the client times out. Optionally opens the generated artifact as an embedded node on the canvas. Read canvas://skills/web-artifacts-builder for the full workflow, stack, and anti-slop design guidelines before calling.',
+    // formatResult receives the SERIALIZED wire envelope. Legacy
+    // canvas_build_web_artifact stringified a subset; the wire envelope IS that
+    // subset, so re-stringify it verbatim.
+    formatResult: (result) => ({
+      content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+    }),
+  },
+  handler: async (input) => {
+    const title = typeof input.title === 'string' ? input.title.trim() : '';
+    const appTsx = typeof input.appTsx === 'string' ? input.appTsx : '';
+    if (!title || !appTsx) {
+      throw new OperationError('Missing required fields: title, appTsx.');
+    }
+
+    const files: Record<string, string> = {};
+    if (isRecord(input.files)) {
+      for (const [pathKey, value] of Object.entries(input.files)) {
+        if (typeof value === 'string') files[pathKey] = value;
+      }
+    }
+
+    const includeLogs = input.includeLogs === true;
+    try {
+      // web-artifacts.ts emits its own canvas-layout-update on node creation (the
+      // injected canvas-operations emitter), so this op stays mutates:false and
+      // does not emit. The SDK buildWebArtifact calls buildWebArtifactOnCanvas
+      // directly with the same runtime.
+      const result = await buildWebArtifactOnCanvas({
+        title,
+        appTsx,
+        ...(typeof input.indexCss === 'string' ? { indexCss: input.indexCss } : {}),
+        ...(typeof input.mainTsx === 'string' ? { mainTsx: input.mainTsx } : {}),
+        ...(typeof input.indexHtml === 'string' ? { indexHtml: input.indexHtml } : {}),
+        ...(Object.keys(files).length > 0 ? { files } : {}),
+        // Sandbox projectPath/outputPath to the workspace on BOTH surfaces (the
+        // 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) }
+          : {}),
+        // Script-path overrides are honored only when contained inside the
+        // workspace (enforced by resolveTrustedScriptPath in
+        // executeWebArtifactBuild), so they cannot point at an arbitrary host
+        // script for bash execution.
+        ...(typeof input.initScriptPath === 'string' ? { initScriptPath: input.initScriptPath } : {}),
+        ...(typeof input.bundleScriptPath === 'string' ? { bundleScriptPath: input.bundleScriptPath } : {}),
+        ...(Array.isArray(input.deps)
+          ? { deps: input.deps.filter((dep): dep is string => typeof dep === 'string') }
+          : {}),
+        ...(typeof input.timeoutMs === 'number' ? { timeoutMs: input.timeoutMs } : {}),
+        ...(typeof input.openInCanvas === 'boolean' ? { openInCanvas: input.openInCanvas } : {}),
+      });
+      return webArtifactEnvelope(result, includeLogs);
+    } catch (error) {
+      throw new OperationError(error instanceof Error ? error.message : String(error));
+    }
+  },
+});
+
+export const appOperations: Operation[] = [
+  openMcpAppOperation,
+  diagramOperation,
+  webArtifactOperation,
+];

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

@@ -0,0 +1,216 @@
+/**
+ * Plan-007 Slice B (wave 4) operations: the three long-poll gate READS —
+ *   ax.approval.get     / canvas_await_approval
+ *   ax.elicitation.get  / canvas_await_elicitation
+ *   ax.mode.get         / canvas_await_mode
+ *
+ * Report primitive D ("gates that actually gate"): each blocks until the gate
+ * leaves `pending` or a timeout elapses, then returns `{ <key>, pending }`.
+ * These are READS — `mutates: false` and NO `ctx.emit` (resolution events are
+ * emitted by the resolve/respond ops in ax-work.ts).
+ *
+ * The HANDLER performs the wait via `waitForAxResolution` (executeOperation is
+ * async). All three legacy `isResolved` predicates are `status !== 'pending'`
+ * (HTTP handlers + SDK PmxCanvas await* agree — the elicitation `answered`/
+ * `cancelled` and mode `approved`/`rejected` states all satisfy `!= pending`).
+ *
+ * timeoutMs normalization (one field the handler reads, sourced per surface):
+ *  - HTTP: a custom `readInput` parses `?waitMs` (string→number) into `timeoutMs`.
+ *    Absent / non-positive ⇒ `0` (a plain immediate read), matching the legacy
+ *    `parseAxWaitMs`. waitForAxResolution clamps to [0, 120000].
+ *  - MCP: `buildInput` passes `timeoutMs` through, defaulting an OMITTED value to
+ *    30000 and clamping to [0, 120000] — byte-identical to the legacy await tools
+ *    (`timeoutMs ?? 30000` in PmxCanvas) plus the tool schema's `.min(0).max(120000)`.
+ *
+ * Missing gate (read returns null): handled WITHOUT throwing. Unlike the wave-2
+ * resolve/respond ops, "not found" is a normal await result, not an error — the
+ * legacy MCP tools returned a SUCCESS-shaped `{ ok:false, <key>:null, pending:false }`
+ * (parsed as JSON by the caller), and the legacy HTTP route returned 404. So:
+ *  - The handler always returns `{ ok: value !== null, <key>: value, pending }`.
+ *  - `http.status` maps `ok:false` → 404, preserving the legacy 404 STATUS (the
+ *    server-api long-poll test asserts `missing.status === 404`).
+ *  - MCP `formatResult` re-serializes the same body; an in-process (Local) MCP
+ *    call never throws, so `{ <key>:null }` round-trips as JSON, matching legacy.
+ *
+ * Wire-body reconciliation (one op = one wire body; documented, same class as
+ * the wave-1 `ax.get` aggregate / wave-3 delivery broadening):
+ *  - HTTP missing body changes from `{ ok:false, error:'<gate> not found.' }` to
+ *    `{ ok:false, <key>:null, pending:false }` (status stays 404). No test asserts
+ *    the legacy error body — server-api only reads `missing.status`.
+ *
+ * Documented behavior change (accepted long-poll tradeoff, plan-007 sub-slice):
+ *  - The legacy HTTP handler passed `req.signal` to waitForAxResolution, so a
+ *    client disconnect aborted the wait early. The registry handler has no access
+ *    to the HTTP Request, so the wait now runs to its (≤120s, subscription-based,
+ *    cheap) timeout instead of aborting on disconnect. Resolution detection,
+ *    timeout, and the `{ value, pending }` result are otherwise identical.
+ *  - Remote-MCP only (daemon mode, untested for these reads): the legacy
+ *    RemoteCanvasAccess.await* methods special-cased a 404 → `{ <key>:null }`. The
+ *    generic HttpOperationInvoker throws on 404, so an await-on-missing over a
+ *    remote transport now surfaces as an isError result rather than a null body.
+ *    The in-process (Local) MCP path — the only path the await tests exercise —
+ *    is unaffected.
+ *
+ * This module must never import server.ts or index.ts.
+ */
+import { z } from 'zod';
+import { canvasState } from '../../canvas-state.js';
+import type { PmxAxApprovalGate, PmxAxElicitation, PmxAxModeRequest } from '../../ax-state.js';
+import { waitForAxResolution, AX_WAIT_MAX_MS } from '../../ax-wait.js';
+import { defineOperation, type Operation } from '../types.js';
+import { isRecord } from './nodes.js';
+
+/** Legacy MCP/SDK default block when timeoutMs is omitted (0 = immediate read). */
+const AX_AWAIT_DEFAULT_MS = 30000;
+
+/** Coerce a raw timeout (MCP number or HTTP query string) to [0, AX_WAIT_MAX_MS]. */
+function clampTimeoutMs(value: unknown): number {
+  const ms = Number(value);
+  if (!Number.isFinite(ms) || ms <= 0) return 0;
+  return Math.min(ms, AX_WAIT_MAX_MS);
+}
+
+/** HTTP `?waitMs` → `timeoutMs`; absent/non-positive ⇒ 0 (plain read). Matches parseAxWaitMs. */
+function readWaitMsInput(_req: Request, params: Record<string, string>, url: URL): Record<string, unknown> {
+  return { ...params, timeoutMs: clampTimeoutMs(url.searchParams.get('waitMs') ?? '') };
+}
+
+/** MCP buildInput: forward id + timeoutMs (omitted ⇒ 30000), clamped to [0, max]. */
+function buildAwaitInput(input: Record<string, unknown>): Record<string, unknown> {
+  return {
+    ...(typeof input.id === 'string' ? { id: input.id } : {}),
+    timeoutMs: input.timeoutMs === undefined ? AX_AWAIT_DEFAULT_MS : clampTimeoutMs(input.timeoutMs),
+  };
+}
+
+const awaitInputShape = {
+  id: z.string().optional().catch(undefined).describe('The gate id.'),
+  timeoutMs: z.unknown().optional().describe('Max ms to block (0 = immediate read; capped at 120000).'),
+};
+
+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).'),
+};
+
+// ── ax.approval.get (canvas_await_approval) ───────────────────
+
+const axApprovalGetOperation = defineOperation<z.infer<typeof awaitInputSchema>, Record<string, unknown>>({
+  name: 'ax.approval.get',
+  mutates: false,
+  input: awaitInputSchema,
+  inputShape: awaitInputShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/ax/approval/:id',
+    readInput: readWaitMsInput,
+    status: (result) => (isRecord(result) && result.ok === false ? 404 : 200),
+  },
+  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).',
+    extraShape: awaitMcpExtraShape,
+    buildInput: buildAwaitInput,
+    formatResult: (result) => {
+      const body = isRecord(result) ? result : {};
+      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 }) }],
+      };
+    },
+  },
+  handler: async (input) => {
+    const id = typeof input.id === 'string' ? input.id : '';
+    const { value, pending } = await waitForAxResolution<PmxAxApprovalGate>({
+      read: () => canvasState.getApproval(id),
+      isResolved: (g) => g.status !== 'pending',
+      timeoutMs: clampTimeoutMs(input.timeoutMs),
+    });
+    return { ok: value !== null, approvalGate: value, pending } as unknown as Record<string, unknown>;
+  },
+});
+
+// ── ax.elicitation.get (canvas_await_elicitation) ─────────────
+
+const axElicitationGetOperation = defineOperation<z.infer<typeof awaitInputSchema>, Record<string, unknown>>({
+  name: 'ax.elicitation.get',
+  mutates: false,
+  input: awaitInputSchema,
+  inputShape: awaitInputShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/ax/elicitation/:id',
+    readInput: readWaitMsInput,
+    status: (result) => (isRecord(result) && result.ok === false ? 404 : 200),
+  },
+  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 }.',
+    extraShape: awaitMcpExtraShape,
+    buildInput: buildAwaitInput,
+    formatResult: (result) => {
+      const body = isRecord(result) ? result : {};
+      const elicitation = (body.elicitation ?? null) as PmxAxElicitation | null;
+      const pending = body.pending === true;
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify({ ok: elicitation !== null, elicitation, pending }) }],
+      };
+    },
+  },
+  handler: async (input) => {
+    const id = typeof input.id === 'string' ? input.id : '';
+    const { value, pending } = await waitForAxResolution<PmxAxElicitation>({
+      read: () => canvasState.getElicitation(id),
+      isResolved: (e) => e.status !== 'pending',
+      timeoutMs: clampTimeoutMs(input.timeoutMs),
+    });
+    return { ok: value !== null, elicitation: value, pending } as unknown as Record<string, unknown>;
+  },
+});
+
+// ── ax.mode.get (canvas_await_mode) ───────────────────────────
+
+const axModeGetOperation = defineOperation<z.infer<typeof awaitInputSchema>, Record<string, unknown>>({
+  name: 'ax.mode.get',
+  mutates: false,
+  input: awaitInputSchema,
+  inputShape: awaitInputShape,
+  http: {
+    method: 'GET',
+    path: '/api/canvas/ax/mode/:id',
+    readInput: readWaitMsInput,
+    status: (result) => (isRecord(result) && result.ok === false ? 404 : 200),
+  },
+  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 }.',
+    extraShape: awaitMcpExtraShape,
+    buildInput: buildAwaitInput,
+    formatResult: (result) => {
+      const body = isRecord(result) ? result : {};
+      const modeRequest = (body.modeRequest ?? null) as PmxAxModeRequest | null;
+      const pending = body.pending === true;
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify({ ok: modeRequest !== null, modeRequest, pending }) }],
+      };
+    },
+  },
+  handler: async (input) => {
+    const id = typeof input.id === 'string' ? input.id : '';
+    const { value, pending } = await waitForAxResolution<PmxAxModeRequest>({
+      read: () => canvasState.getModeRequest(id),
+      isResolved: (m) => m.status !== 'pending',
+      timeoutMs: clampTimeoutMs(input.timeoutMs),
+    });
+    return { ok: value !== null, modeRequest: value, pending } as unknown as Record<string, unknown>;
+  },
+});
+
+export const axAwaitOperations: Operation[] = [
+  axApprovalGetOperation,
+  axElicitationGetOperation,
+  axModeGetOperation,
+];