pmx-canvas 0.2.7 → 0.3.0

package/src/server/index.ts

@@ -885,7 +885,7 @@ export class PmxCanvas extends EventEmitter {
 
   setContextPins(nodeIds: string[], mode: 'set' | 'add' | 'remove' = 'set'): { count: number; nodeIds: string[] } {
     const result = setCanvasContextPins(nodeIds, mode);
-    emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    emitPrimaryWorkbenchEvent('context-pins-changed', { count: result.count, nodeIds: result.nodeIds });
     return result;
   }
 

package/src/server/intent-registry.ts

@@ -4,7 +4,7 @@
  * Intents are EPHEMERAL PRESENCE, deliberately modelled like the attention /
  * timeline ephemerality layer rather than canvas-bound state:
  *  - an in-memory Map (NOT CanvasStateManager) — never serialized, never
- *    snapshotted, never returned by canvas_get_layout;
+ *    snapshotted, never returned by canvas_query (layout action);
  *  - count-capped (oldest evicted) and TTL-swept so a ghost can never linger;
  *  - emitted over the same workbench SSE stream as `ax-intent` /
  *    `ax-intent-clear` frames via an INJECTED emitter (server.ts wires it,

package/src/server/operations/composites.ts

@@ -9,17 +9,22 @@
  * to the standalone `canvas_add_edge` — same op, same arg mapping, same result
  * shape — by construction. No handler logic lives here.
  *
- * Migration (docs/api-stability.md + plan-006): composites land ADDITIVELY in
- * v0.2 alongside the legacy single-purpose tools (the tool surface grows, then
- * shrinks when the legacy tools are removed in v0.3). Every action here maps to a
- * registry-backed operation (plan-005 slices 1–7 + plan-008 Wave 1).
+ * Migration (docs/api-stability.md + plan-006): composites landed ADDITIVELY in
+ * v0.2 alongside the legacy single-purpose tools. As of v0.3.0 the legacy tools
+ * those composites fold are REMOVED (registration-suppressed — see
+ * `compositeFoldedOpNames` below); every action here maps to a registry-backed
+ * operation (plan-005 slices 1–7 + plan-008 Wave 1) that is now reachable ONLY
+ * through its composite (or `canvas_batch`).
  *
- * Still deferred (its legacy standalone tool keeps working; see plan-008): the
- * `canvas_snapshot` composite (the v0.3 name collision). The action enums are
- * forward-compatible: adding an action later is additive. (`canvas_webview`
- * shipped in plan-008 Wave 3 via runner injection; `canvas_app` shipped in Wave 4
- * — open-mcp-app / diagram / build-artifact. Wave 5 folded the last three legacy
- * tools deprecate-only — NO per-action input-injection mechanism was needed:
+ * Deferred to v0.4: the `canvas_snapshot` composite (still a name collision —
+ * see below). Its 6 legacy snapshot standalones (`canvas_snapshot`,
+ * `canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`,
+ * `canvas_gc_snapshots`, `canvas_diff`) stay registered in v0.3.0 but are marked
+ * deprecated (description-prefixed) per docs/api-stability.md's
+ * deprecate-one-minor-before-removal rule. (`canvas_webview` shipped in plan-008
+ * Wave 3 via runner injection; `canvas_app` shipped in Wave 4 — open-mcp-app /
+ * diagram / build-artifact. Wave 5 folded the last three legacy tools
+ * deprecate-only — NO per-action input-injection mechanism was needed:
  * `canvas_add_html_node` / `canvas_add_html_primitive` → `canvas_node` action
  * "add" (type:"html" [+ primitive]); `canvas_refresh_webpage_node` → `canvas_node`
  * action "update" (refresh:true). `canvas_screenshot` stays standalone — it
@@ -30,8 +35,8 @@
  * name is ALREADY a legacy standalone tool (the save-snapshot tool, op
  * `snapshot.save`), so it cannot be added additively without a name clash, and
  * repurposing `canvas_snapshot` to be action-discriminated now would break
- * existing callers. It lands in v0.3, in the same change that removes the legacy
- * single-purpose snapshot tools and frees the name.
+ * existing callers. It lands in v0.4, in the same change that removes the 6
+ * kept-but-deprecated legacy snapshot tools and frees the name.
  *
  * This module must never import server.ts or index.ts.
  */
@@ -47,7 +52,7 @@ import { z, type ZodRawShape, type ZodTypeAny } from 'zod';
  *  - Two-discriminator (`canvas_ax_gate`, plan-007 Slice C): a `kind` × `action`
  *    matrix folds 9 ops into one tool. Set `extraDiscriminatorShape` (the `kind`
  *    enum), `memberOps` (the op names — used to derive the schema union + the
- *    deprecation notes), `actionEnum` (the action discriminator values), and
+ *    folded-op set), `actionEnum` (the action discriminator values), and
  *    `resolveOp` (maps `{ kind, action }` → op name, or undefined for an invalid
  *    combo → a loud error at dispatch). The flat `actions` map is left empty for
  *    these; the matrix path uses `resolveOp` instead.
@@ -78,8 +83,9 @@ export interface CompositeToolDefinition {
   actionEnum?: readonly string[];
   /**
    * Two-discriminator extension: every member op name. Used to build the schema
-   * union (all member-op fields, optional) and to derive a deprecation note per
-   * member op (each mapped back to its (kind, action) by `describeOp`).
+   * union (all member-op fields, optional) and to populate the folded-op set
+   * (`compositeFoldedOpNames`) that suppresses each member op's standalone
+   * registration.
    */
   memberOps?: string[];
   /**
@@ -331,36 +337,30 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
 ];
 
 /**
- * Deprecation notes for the legacy single-purpose tools, DERIVED from the
- * composites: every operation a composite folds gets a `Deprecated: use
- * canvas_x with action "y".` prefix on its standalone tool description, steering
- * agents to the composite during the v0.2 overlap window (the legacy tools and
- * these notes are removed together in v0.3). Keyed by registry operation name.
- * Deriving it keeps the deprecation list in lockstep with the composites — a new
- * folded action automatically deprecates the tool it replaces.
+ * Operation names FOLDED by a composite, DERIVED from the composites: every op
+ * a composite folds had its standalone single-purpose tool REMOVED in v0.3.0
+ * (see docs/api-stability.md). This set is the do-not-register list —
+ * `registerOperationTools` skips any op whose name is in it, since the op is
+ * only reachable through its composite (and through `canvas_batch`) now.
+ * Deriving it from the composites keeps suppression in lockstep with them — a
+ * newly folded action is automatically suppressed from standalone registration.
  */
-export function buildCompositeDeprecationNotes(
+export function compositeFoldedOpNames(
   definitions: CompositeToolDefinition[] = compositeToolDefinitions,
-): Map<string, string> {
-  const notes = new Map<string, string>();
+): Set<string> {
+  const names = new Set<string>();
   for (const def of definitions) {
-    // Single-discriminator composites: one note per (action → op).
-    for (const [action, opName] of Object.entries(def.actions)) {
-      notes.set(opName, `Deprecated: use ${def.toolName} with action "${action}". `);
+    // Single-discriminator composites: the flat `actions` map values.
+    for (const opName of Object.values(def.actions)) {
+      names.add(opName);
     }
-    // Two-discriminator composites (canvas_ax_gate): one note per member op,
-    // each mapped back to its (kind, action) so the deprecation points exactly
-    // at the composite invocation that replaces the legacy tool.
-    if (def.memberOps && def.describeOp) {
+    // Two-discriminator composites (canvas_ax_gate): the explicit `memberOps`
+    // list (the flat `actions` map is empty for these).
+    if (def.memberOps) {
       for (const opName of def.memberOps) {
-        const combo = def.describeOp(opName);
-        if (!combo) continue;
-        notes.set(
-          opName,
-          `Deprecated: use ${def.toolName} with kind "${combo.kind}" action "${combo.action}". `,
-        );
+        names.add(opName);
       }
     }
   }
-  return notes;
+  return names;
 }

package/src/server/operations/http.ts

@@ -38,7 +38,8 @@ function matchPath(template: string, pathname: string): Record<string, string> |
 /**
  * Shared body reader: preserves the parsed JSON value as-is (object, array,
  * or primitive) — per-op `readInput` decides what to do with non-object
- * bodies; the shared reader never coerces.
+ * bodies; the shared reader never coerces. A non-empty body that fails to
+ * parse is a 400 (OperationError), never a silent empty input.
  */
 export async function readJsonValue(req: Request): Promise<unknown> {
   let text = '';
@@ -51,7 +52,7 @@ export async function readJsonValue(req: Request): Promise<unknown> {
   try {
     return JSON.parse(text) as unknown;
   } catch {
-    return undefined;
+    throw new OperationError('Malformed JSON body.');
   }
 }
 

package/src/server/operations/mcp.ts

@@ -12,7 +12,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { getOperation, listOperations } from './registry.js';
 import type { OperationInvoker } from './invoker.js';
 import { OperationError, type OperationMcpToolHost } from './types.js';
-import { buildCompositeDeprecationNotes, compositeToolDefinitions, type CompositeToolDefinition } from './composites.js';
+import { compositeFoldedOpNames, compositeToolDefinitions, type CompositeToolDefinition } from './composites.js';
 
 export interface OperationToolHost extends OperationMcpToolHost {
   invoker(): OperationInvoker;
@@ -22,16 +22,17 @@ export function registerOperationTools(
   server: McpServer,
   getHost: () => Promise<OperationToolHost>,
 ): void {
-  // Legacy tools folded by a composite get a "Deprecated: use canvas_x …" prefix
-  // (plan-006 step 2) so agents migrate during the v0.2 overlap window.
-  const deprecations = buildCompositeDeprecationNotes();
+  // Ops folded by a composite are NOT registered standalone: their legacy
+  // single-purpose tools were removed in v0.3.0 (docs/api-stability.md). The op
+  // itself is untouched — it stays reachable via its composite and canvas_batch.
+  const foldedOpNames = compositeFoldedOpNames();
   for (const op of listOperations()) {
+    if (foldedOpNames.has(op.name)) continue;
     const tool = op.mcp;
     if (!tool) continue;
-    const note = deprecations.get(op.name);
     server.tool(
       tool.toolName,
-      note ? note + tool.description : tool.description,
+      tool.description,
       { ...op.inputShape, ...(tool.extraShape ?? {}) },
       async (input: Record<string, unknown>) => {
         try {

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

@@ -94,10 +94,10 @@ export async function openMcpAppCore(
   // 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).
+  // not batchable — call canvas_app (action "open-mcp-app" / "diagram") instead.
   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).',
+      '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 canvas_app with action "open-mcp-app" or "diagram" outside the batch.',
     );
   }
   const targetNode = input.nodeId ? canvasState.getNode(input.nodeId) : undefined;
@@ -246,7 +246,7 @@ const openMcpAppOperation = defineOperation<z.infer<typeof openMcpAppSchema>, Op
   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.',
+      '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_app action "diagram" for the built-in Excalidraw preset.',
     formatResult: (result) => ({
       content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
     }),
@@ -283,7 +283,7 @@ const diagramOperation = defineOperation<z.infer<typeof diagramSchema>, OpenMcpA
   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.',
+      '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_app action "open-mcp-app".',
     formatResult: (result) => ({
       content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
     }),

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

@@ -654,7 +654,7 @@ function createGroupNode(body: Record<string, unknown>): NodeAddResult {
 
 const nodeAddShape = {
   intentId: z.string().optional().catch(undefined).describe('Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.'),
-  type: z.string().optional().catch(undefined).describe('Node type (prefer canvas_create_group for groups)'),
+  type: z.string().optional().catch(undefined).describe('Node type (prefer canvas_group {action:"create"} for groups)'),
   title: z.string().optional().catch(undefined).describe('Node title'),
   content: z.string().optional().catch(undefined).describe('Node content (markdown for markdown nodes, file path for file nodes, image path/URL/data-URI for image nodes, URL for webpage nodes)'),
   path: z.string().optional().catch(undefined).describe('Compatibility alias for image node content. Prefer content for image paths.'),
@@ -665,7 +665,7 @@ const nodeAddShape = {
   height: z.number().optional().catch(undefined).describe('Height in pixels (default: 600)'),
   strictSize: z.boolean().optional().catch(undefined).describe('Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting'),
   children: z.unknown().optional().describe('Group-only alias for childIds. Node IDs to include in a generic group node.'),
-  childIds: z.unknown().optional().describe('Group-only field. Node IDs to include in a generic group node. Prefer canvas_create_group for groups.'),
+  childIds: z.unknown().optional().describe('Group-only field. Node IDs to include in a generic group node. Prefer canvas_group {action:"create"} for groups.'),
   childLayout: z.enum(['grid', 'column', 'flow']).optional().catch(undefined).describe('Group-only optional layout for grouped children.'),
   color: z.string().optional().catch(undefined).describe('Group-only frame accent color.'),
   toolName: z.string().optional().catch(undefined).describe('Trace node tool or operation label'),
@@ -708,12 +708,12 @@ const nodeAddOperation = defineOperation<z.infer<typeof nodeAddSchema>, NodeAddR
   },
   mcp: {
     toolName: 'canvas_add_node',
-    description: 'Add a basic node to the canvas. Returns the created node with normalized title/content and rendered geometry. Supported here: markdown, status, context, ledger, trace, file, image, webpage, mcp-app, html, group. Dedicated node tools: json-render -> canvas_add_json_render_node, graph -> canvas_add_graph_node, web-artifact -> canvas_build_web_artifact, external apps -> canvas_open_mcp_app, html (preferred) -> canvas_add_html_node, groups -> canvas_create_group. Call canvas_describe_schema for the full nodeTypeRouting table.',
+    description: 'Add a basic node to the canvas. Returns the created node with normalized title/content and rendered geometry. Supported here: markdown, status, context, ledger, trace, file, image, webpage, mcp-app, html, group. Dedicated routes: json-render -> canvas_render {action:"add-json-render"}, graph -> canvas_render {action:"add-graph"}, web-artifact -> canvas_app {action:"build-artifact"}, external apps -> canvas_app {action:"open-mcp-app"}, groups -> canvas_group {action:"create"}. Call canvas_render {action:"describe-schema"} for the full nodeTypeRouting table.',
     extraShape: {
       type: z.enum(['markdown', 'status', 'context', 'ledger', 'trace', 'file', 'image', 'webpage', 'mcp-app', 'html', 'group'])
-        .describe('Node type (prefer canvas_create_group for groups)'),
+        .describe('Node type (prefer canvas_group {action:"create"} for groups)'),
       children: z.array(z.string()).optional().describe('Group-only alias for childIds. Node IDs to include in a generic group node.'),
-      childIds: z.array(z.string()).optional().describe('Group-only field. Node IDs to include in a generic group node. Prefer canvas_create_group for groups.'),
+      childIds: z.array(z.string()).optional().describe('Group-only field. Node IDs to include in a generic group node. Prefer canvas_group {action:"create"} for groups.'),
       axCapabilities: z.object({
         enabled: z.boolean().optional(),
         allowed: z.array(z.string()).optional(),

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

@@ -6,9 +6,9 @@
  * - pin.set: legacy POST /api/canvas/context-pins emitted ONLY
  *   context-pins-changed (no canvas-layout-update), so mutates: false with a
  *   manual ctx.emit. The injected emitter adds the sessionId/timestamp fields
- *   the legacy handler set explicitly. (The SDK's setContextPins emits a
- *   layout update instead — that local/remote drift is erased here in favor of
- *   the HTTP wire behavior.)
+ *   the legacy handler set explicitly. (The SDK's setContextPins emits the
+ *   same context-pins-changed event — its old layout-update drift was erased
+ *   in v0.3.0.)
  * - canvas.undo / canvas.redo: legacy handlers emitted canvas-viewport-update
  *   then canvas-layout-update only after an entry was actually undone/redone,
  *   so mutates: false with conditional manual emits. (The SDK's undo/redo also
@@ -87,7 +87,7 @@ const pinOperation = defineOperation<z.infer<typeof pinSchema>, Record<string, u
 
 const searchShape = {
   q: z.unknown().optional().describe('Search query — matches against node titles, content, and file paths'),
-  limit: z.unknown().optional().describe('Max results to return (default: 10). Applied by the MCP tool only; the HTTP route returns all matches.'),
+  limit: z.unknown().optional().describe('Max results to return (default: all over HTTP, 10 via the MCP tool).'),
 };
 
 const searchSchema = z.looseObject(searchShape);
@@ -108,9 +108,12 @@ const searchOperation = defineOperation<z.infer<typeof searchSchema>, Record<str
       query: z.string().describe('Search query — matches against node titles, content, and file paths'),
       limit: z.number().optional().describe('Max results to return (default: 10)'),
     },
-    // The HTTP route only reads ?q= (legacy behavior); map the MCP-facing
-    // `query` arg onto it. The limit cap stays MCP-side, like the legacy tool.
-    buildInput: (input) => ({ q: typeof input.query === 'string' ? input.query : '' }),
+    // Map the MCP-facing `query` arg onto the wire's `q`. The handler caps by
+    // `limit` on every transport; the MCP tool additionally defaults it to 10.
+    buildInput: (input) => ({
+      q: typeof input.query === 'string' ? input.query : '',
+      ...(typeof input.limit === 'number' ? { limit: input.limit } : {}),
+    }),
     formatResult: (result, input) => {
       const body = isRecord(result) ? result : {};
       const results = Array.isArray(body.results) ? body.results : [];
@@ -132,7 +135,15 @@ const searchOperation = defineOperation<z.infer<typeof searchSchema>, Record<str
     if (!q.trim()) {
       return { results: [], query: q };
     }
-    return { results: searchNodes(canvasState.getLayout().nodes, q), query: q };
+    const rawLimit = input.limit;
+    const limit = typeof rawLimit === 'number'
+      ? rawLimit
+      : typeof rawLimit === 'string' && rawLimit.trim() !== '' ? Number(rawLimit) : Number.NaN;
+    const results = searchNodes(canvasState.getLayout().nodes, q);
+    return {
+      results: Number.isFinite(limit) && limit > 0 ? results.slice(0, Math.floor(limit)) : results,
+      query: q,
+    };
   },
 });
 

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

@@ -69,7 +69,7 @@ const snapshotListOperation = defineOperation<z.infer<typeof snapshotListSchema>
   },
   mcp: {
     toolName: 'canvas_list_snapshots',
-    description: 'List saved canvas snapshots with IDs, names, timestamps, and node/edge counts. Defaults to the 20 newest snapshots; pass all=true to return every snapshot.',
+    description: 'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). List saved canvas snapshots with IDs, names, timestamps, and node/edge counts. Defaults to the 20 newest snapshots; pass all=true to return every snapshot.',
     extraShape: {
       limit: z.number().optional().describe('Maximum snapshots to return (default: 20)'),
       query: z.string().optional().describe('Optional case-insensitive ID/name filter'),
@@ -117,7 +117,7 @@ const snapshotSaveOperation = defineOperation<z.infer<typeof snapshotSaveSchema>
   },
   mcp: {
     toolName: 'canvas_snapshot',
-    description: 'Save the current canvas state as a named snapshot. Snapshots persist to disk and can be restored later.',
+    description: 'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Save the current canvas state as a named snapshot. Snapshots persist to disk and can be restored later.',
     extraShape: {
       name: z.string().describe('Name for this snapshot (e.g., "before refactor", "investigation v2")'),
     },
@@ -154,7 +154,7 @@ const snapshotGcOperation = defineOperation<z.infer<typeof snapshotGcSchema>, Re
   },
   mcp: {
     toolName: 'canvas_gc_snapshots',
-    description: 'Delete old saved canvas snapshots, keeping the newest N snapshots. Use dryRun=true to preview deletions.',
+    description: 'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Delete old saved canvas snapshots, keeping the newest N snapshots. Use dryRun=true to preview deletions.',
     extraShape: {
       keep: z.number().optional().describe('Number of newest snapshots to keep (default: 20)'),
       dryRun: z.boolean().optional().describe('Preview deletions without removing snapshot files'),
@@ -207,7 +207,7 @@ const snapshotDiffOperation = defineOperation<z.infer<typeof snapshotDiffSchema>
   },
   mcp: {
     toolName: 'canvas_diff',
-    description: 'Compare the current canvas state against a saved snapshot. Shows added/removed/modified nodes and edges. Pass either a snapshot name or ID.',
+    description: 'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Compare the current canvas state against a saved snapshot. Shows added/removed/modified nodes and edges. Pass either a snapshot name or ID.',
     extraShape: {
       snapshot: z.string().describe('Snapshot name or ID to compare against'),
     },
@@ -289,7 +289,7 @@ const snapshotRestoreOperation = defineOperation<z.infer<typeof snapshotRestoreS
   },
   mcp: {
     toolName: 'canvas_restore',
-    description: 'Restore the canvas to a previously saved snapshot. Use canvas_snapshot to save first. Pass either the snapshot ID or name to restore.',
+    description: 'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Restore the canvas to a previously saved snapshot. Use canvas_snapshot to save first. Pass either the snapshot ID or name to restore.',
     extraShape: {
       id: z.string().describe('Snapshot ID or name to restore (from canvas_snapshot or snapshot list)'),
     },
@@ -338,7 +338,7 @@ const snapshotDeleteOperation = defineOperation<z.infer<typeof snapshotDeleteSch
   },
   mcp: {
     toolName: 'canvas_delete_snapshot',
-    description: 'Delete a saved snapshot by ID.',
+    description: 'Deprecated: folds into the canvas_snapshot composite in v0.4 (actions save|list|restore|delete|gc|diff). Delete a saved snapshot by ID.',
     extraShape: {
       id: z.string().describe('Snapshot ID to delete'),
     },

package/src/server/server.ts

@@ -920,7 +920,8 @@ function rotatePrimaryWorkbenchSessionIfNeeded(): void {
   primaryWorkbenchSessionId = `pmx-${Date.now().toString(36)}`;
 }
 
-async function readJson(req: Request): Promise<Record<string, unknown>> {
+/** Null means a non-empty body failed to parse — handlers must 400, not silently no-op. */
+async function readJson(req: Request): Promise<Record<string, unknown> | null> {
   let text = '';
   try {
     text = await req.text();
@@ -937,10 +938,14 @@ async function readJson(req: Request): Promise<Record<string, unknown>> {
     return value as Record<string, unknown>;
   } catch (error) {
     logWorkbenchWarning('readJson', error);
-    return {};
+    return null;
   }
 }
 
+function malformedJsonResponse(): Response {
+  return responseJson({ ok: false, error: 'Malformed JSON body.' }, 400);
+}
+
 function htmlEscape(value: string): string {
   return value
     .replaceAll('&', '&amp;')
@@ -1228,6 +1233,7 @@ function addFrameDocument(html: string, sandbox: string): string {
 
 async function handleCreateFrameDocument(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const html = body.html;
   if (typeof html !== 'string' || !html) {
     return responseJson({ ok: false, error: 'Frame document requires non-empty html.' }, 400);
@@ -1370,6 +1376,7 @@ function handleNodeSurface(pathname: string, url: URL): Response {
 
 async function handleCanvasUpdate(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const updates = Array.isArray(body.updates) ? body.updates : [];
   const result = body.recordHistory === false
     ? (() => {
@@ -1388,6 +1395,7 @@ async function handleCanvasUpdate(req: Request): Promise<Response> {
 
 async function handleCanvasViewport(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const next = {
     x: typeof body.x === 'number' ? body.x : canvasState.viewport.x,
     y: typeof body.y === 'number' ? body.y : canvasState.viewport.y,
@@ -1438,6 +1446,7 @@ function parseAnnotationPoints(value: unknown): CanvasAnnotation['points'] {
 
 async function handleCanvasAddAnnotation(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const type = body.type === 'text' ? 'text' : 'freehand';
   const points = parseAnnotationPoints(body.points);
   if (points.length < (type === 'text' ? 1 : 2)) {
@@ -1524,6 +1533,7 @@ async function handleCanvasRefreshWebpageNode(nodeId: string, req: Request): Pro
   }
 
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const rawUrl = typeof body.url === 'string' ? body.url : undefined;
   let url: string | undefined;
   if (rawUrl && rawUrl.trim().length > 0) {
@@ -1544,6 +1554,7 @@ async function handleCanvasRefreshWebpageNode(nodeId: string, req: Request): Pro
 
 async function handleCanvasThemeUpdate(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const theme = normalizeCanvasTheme(body.theme, canvasState.theme);
   const next = canvasState.setTheme(theme);
   broadcastWorkbenchEvent('theme-changed', {
@@ -1823,6 +1834,7 @@ function handleRead(pathLike: string): Response {
 
 async function handleExtAppCallTool(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const sessionId = typeof body.sessionId === 'string' ? body.sessionId.trim() : '';
   const toolName = typeof body.toolName === 'string' ? body.toolName.trim() : '';
   if (!sessionId || !toolName) {
@@ -1893,6 +1905,7 @@ async function handleExtAppCallTool(req: Request): Promise<Response> {
 
 async function handleExtAppReadResource(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const sessionId = typeof body.sessionId === 'string' ? body.sessionId.trim() : '';
   const uri = typeof body.uri === 'string' ? body.uri.trim() : '';
   if (!sessionId || !uri) {
@@ -1909,6 +1922,7 @@ async function handleExtAppReadResource(req: Request): Promise<Response> {
 
 async function handleExtAppListTools(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const sessionId = typeof body.sessionId === 'string' ? body.sessionId.trim() : '';
   if (!sessionId) return responseJson({ ok: false, error: 'Missing sessionId.' }, 400);
 
@@ -1922,6 +1936,7 @@ async function handleExtAppListTools(req: Request): Promise<Response> {
 
 async function handleExtAppListResources(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const sessionId = typeof body.sessionId === 'string' ? body.sessionId.trim() : '';
   if (!sessionId) return responseJson({ ok: false, error: 'Missing sessionId.' }, 400);
 
@@ -1935,6 +1950,7 @@ async function handleExtAppListResources(req: Request): Promise<Response> {
 
 async function handleExtAppListResourceTemplates(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const sessionId = typeof body.sessionId === 'string' ? body.sessionId.trim() : '';
   if (!sessionId) return responseJson({ ok: false, error: 'Missing sessionId.' }, 400);
 
@@ -1948,6 +1964,7 @@ async function handleExtAppListResourceTemplates(req: Request): Promise<Response
 
 async function handleExtAppListPrompts(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const sessionId = typeof body.sessionId === 'string' ? body.sessionId.trim() : '';
   if (!sessionId) return responseJson({ ok: false, error: 'Missing sessionId.' }, 400);
 
@@ -1961,6 +1978,7 @@ async function handleExtAppListPrompts(req: Request): Promise<Response> {
 
 async function handleExtAppModelContext(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const nodeId = typeof body.nodeId === 'string' ? body.nodeId.trim() : '';
   if (!nodeId) return responseJson({ ok: false, error: 'Missing nodeId.' }, 400);
 
@@ -2033,6 +2051,7 @@ function currentWorkbenchUrl(): string | null {
 
 async function handleWorkbenchWebViewScreenshot(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const format = body.format === 'jpeg' || body.format === 'webp' || body.format === 'png'
     ? body.format
     : 'png';
@@ -2063,6 +2082,7 @@ async function handleWorkbenchWebViewScreenshot(req: Request): Promise<Response>
 
 async function handleWorkbenchOpen(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const pathLike = typeof body.path === 'string' ? body.path : '';
   const safePath = resolveWorkspaceMarkdownPath(pathLike);
   if (!safePath) return responseText('Invalid path', 400);
@@ -2074,6 +2094,7 @@ async function handleWorkbenchOpen(req: Request): Promise<Response> {
 
 async function handleWorkbenchIntent(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const rawType = typeof body.type === 'string' ? body.type.trim() : '';
   if (!rawType) return responseText('Missing intent type', 400);
   if (!ALLOWED_WORKBENCH_INTENTS.has(rawType as PrimaryWorkbenchIntent['type'])) {
@@ -2234,6 +2255,7 @@ function handleWorkbenchEvents(req: Request): Response {
 
 async function handleSave(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const pathLike = typeof body.path === 'string' ? body.path : '';
   const safePath = resolveWorkspaceMarkdownPath(pathLike);
   if (!safePath) return responseText('Invalid path', 400);
@@ -2250,6 +2272,7 @@ async function handleSave(req: Request): Promise<Response> {
 
 async function handleRender(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const markdown = typeof body.markdown === 'string' ? body.markdown : '';
   const html =
     (marked.parse(normalizeMarkdownExternalUrls(markdown), {
@@ -2271,6 +2294,7 @@ function buildSelectionContextPreamble(contextNodeIds: string[]): string {
 
 async function handleCanvasPrompt(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const text = typeof body.text === 'string' ? body.text.trim() : '';
   if (!text) return responseText('Missing prompt text', 400);
 
@@ -2604,6 +2628,7 @@ function normalizeActivityReactions(input: Record<string, unknown>): {
 // Report primitive A: ingest a harness-forwarded agent activity; the board auto-reacts.
 async function handleAxActivityIngest(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   if (!isAxActivityKind(body.kind)) {
     return responseJson({ ok: false, error: "activity requires a valid 'kind': one of tool-start, tool-result, failure, error, session-start, session-end, command, note." }, 400);
   }
@@ -2650,6 +2675,7 @@ function handleGetAxSurfaceSnapshot(): Response {
 // safe presentation query params like the current theme.
 async function handleOpenExternalSurface(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const nodeId = typeof body.nodeId === 'string' ? body.nodeId : '';
   if (!nodeId) return responseJson({ ok: false, error: 'nodeId is required.' }, 400);
   const node = canvasState.getNode(nodeId);
@@ -2670,6 +2696,7 @@ async function handleOpenExternalSurface(req: Request): Promise<Response> {
 
 async function handleAxInteraction(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   const { result, events } = applyAxInteraction(canvasState, body, normalizeAxSource(body.source, 'api'));
   for (const e of events) {
     broadcastWorkbenchEvent(e.event, {
@@ -2711,6 +2738,7 @@ function handleAxPolicyGet(): Response {
 
 async function handleAxStatePatch(req: Request): Promise<Response> {
   const body = await readJson(req);
+  if (body === null) return malformedJsonResponse();
   if (!body.focus || typeof body.focus !== 'object' || Array.isArray(body.focus)) {
     return responseJson({ ok: false, error: 'PATCH /api/canvas/ax currently requires a focus object.' }, 400);
   }

package/src/shared/ax-intent.ts

@@ -5,7 +5,7 @@
  * agent is ABOUT to make (create / move / connect / remove / edit) so the canvas
  * can paint a faint placeholder before the real mutation lands. Like a
  * multiplayer cursor, it auto-expires, is count-capped, and never enters
- * `canvas_get_layout`, `state.json`, or snapshots.
+ * `canvas_query` (`layout` action), `state.json`, or snapshots.
  *
  * This module is import-shared by the server (IntentRegistry + the intent ops)
  * and the client (intent-store + IntentLayer); it must stay free of any