pmx-canvas 0.2.1 → 0.2.2

package/src/server/intent-registry.ts

@@ -0,0 +1,324 @@
+/**
+ * IntentRegistry — the server-side home of the Ghost Cursor of Intent.
+ *
+ * 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;
+ *  - 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,
+ *    mirroring setOperationEventEmitter) so this module never imports server.ts.
+ *
+ * The single trust boundary is `signal()` / `update()`: every envelope is
+ * zod-validated and per-kind-checked here, so HTTP, MCP, and the SDK all funnel
+ * through the same validation (consistent with applyAxInteraction).
+ */
+import { z } from 'zod';
+import {
+  DEFAULT_INTENT_TTL_MS,
+  INTENT_EDGE_TYPES,
+  INTENT_KINDS,
+  MAX_INTENT_TTL_MS,
+  MAX_LIVE_INTENTS,
+  type PmxAxIntent,
+  type PmxAxIntentKind,
+} from '../shared/ax-intent.js';
+import { OperationError } from './operations/types.js';
+
+type IntentEmitter = (event: string, payload: Record<string, unknown>) => void;
+const MAX_VETO_TOMBSTONES = 128;
+
+const positionSchema = z.object({ x: z.number().finite(), y: z.number().finite() });
+
+const intentSignalSchema = z.looseObject({
+  id: z.string().min(1).max(200).optional(),
+  kind: z.enum(INTENT_KINDS),
+  position: positionSchema.optional(),
+  nodeId: z.string().min(1).max(200).optional(),
+  edge: z
+    .object({
+      from: z.string().min(1).max(200),
+      to: z.string().min(1).max(200),
+      type: z.enum(INTENT_EDGE_TYPES),
+    })
+    .optional(),
+  nodeType: z.string().max(60).optional(),
+  label: z.string().max(120).optional(),
+  reason: z.string().max(400).optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  seq: z.number().int().min(0).max(9999).optional(),
+  ttlMs: z.number().positive().max(MAX_INTENT_TTL_MS).optional(),
+  source: z.string().max(60).optional(),
+});
+
+const intentUpdateSchema = z.looseObject({
+  position: positionSchema.optional(),
+  nodeType: z.string().max(60).optional(),
+  label: z.string().max(120).optional(),
+  reason: z.string().max(400).optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  seq: z.number().int().min(0).max(9999).optional(),
+  ttlMs: z.number().positive().max(MAX_INTENT_TTL_MS).optional(),
+});
+
+function parseOrThrow<T>(schema: z.ZodType<T>, raw: unknown, label: string): T {
+  const parsed = schema.safeParse(raw ?? {});
+  if (!parsed.success) {
+    const detail = parsed.error.issues
+      .map((issue) => (issue.path.length > 0 ? `${issue.path.map(String).join('.')}: ${issue.message}` : issue.message))
+      .join('; ');
+    throw new OperationError(`Invalid ${label}: ${detail}`);
+  }
+  return parsed.data;
+}
+
+/** Each kind needs the spatial anchor it renders against — fail loud otherwise. */
+function requireKindFields(kind: PmxAxIntentKind, value: z.infer<typeof intentSignalSchema>): void {
+  switch (kind) {
+    case 'create':
+      if (!value.position) throw new OperationError('intent kind "create" requires a position.');
+      break;
+    case 'move':
+      if (!value.nodeId) throw new OperationError('intent kind "move" requires a nodeId.');
+      if (!value.position) throw new OperationError('intent kind "move" requires a destination position.');
+      break;
+    case 'connect':
+      if (!value.edge) throw new OperationError('intent kind "connect" requires an edge { from, to, type }.');
+      break;
+    case 'remove':
+    case 'edit':
+      if (!value.nodeId) throw new OperationError(`intent kind "${kind}" requires a nodeId.`);
+      break;
+  }
+}
+
+let intentSeq = 0;
+
+function nextIntentId(): string {
+  intentSeq += 1;
+  return `intent-${Date.now().toString(36)}-${intentSeq.toString(36)}`;
+}
+
+export class IntentRegistry {
+  private readonly intents = new Map<string, PmxAxIntent>();
+  private readonly vetoedIntentIds = new Map<string, number>();
+  private readonly committingIntentIds = new Set<string>();
+  private emit: IntentEmitter = () => {};
+  private sweepTimer: ReturnType<typeof setInterval> | null = null;
+
+  /** Inject the workbench SSE emitter (server.ts wires this at module load). */
+  setEmitter(emitter: IntentEmitter | null): void {
+    this.emit = emitter ?? (() => {});
+  }
+
+  list(): PmxAxIntent[] {
+    return [...this.intents.values()];
+  }
+
+  /** Signal a new (or replace an existing) intent. Returns the stored envelope. */
+  signal(raw: unknown): PmxAxIntent {
+    const input = parseOrThrow(intentSignalSchema, raw, 'intent');
+    requireKindFields(input.kind, input);
+
+    const now = Date.now();
+    const ttl = typeof input.ttlMs === 'number' ? input.ttlMs : DEFAULT_INTENT_TTL_MS;
+    const id = input.id && this.intents.has(input.id) ? input.id : input.id ?? nextIntentId();
+    this.pruneVetoTombstones();
+    if (this.vetoedIntentIds.has(id)) {
+      throw new OperationError(`Intent "${id}" was vetoed. Use a new id for a revised intent.`, 409);
+    }
+    if (this.committingIntentIds.has(id)) {
+      throw new OperationError(`Intent "${id}" is already committing.`, 409);
+    }
+    const existing = this.intents.get(id);
+
+    const intent: PmxAxIntent = {
+      id,
+      kind: input.kind,
+      ...(input.position ? { position: input.position } : {}),
+      ...(input.nodeId ? { nodeId: input.nodeId } : {}),
+      ...(input.edge ? { edge: input.edge } : {}),
+      ...(input.nodeType ? { nodeType: input.nodeType } : {}),
+      ...(input.label ? { label: input.label } : {}),
+      ...(input.reason ? { reason: input.reason } : {}),
+      ...(typeof input.confidence === 'number' ? { confidence: input.confidence } : {}),
+      ...(typeof input.seq === 'number' ? { seq: input.seq } : {}),
+      ...(input.source ? { source: input.source } : {}),
+      createdAt: existing?.createdAt ?? now,
+      expiresAt: now + ttl,
+    };
+
+    this.intents.set(id, intent);
+    this.evictOverflow();
+    this.ensureSweeper();
+    this.emit('ax-intent', { intent });
+    return intent;
+  }
+
+  /** Patch a live intent (position/label/reason/confidence/seq) and bump its TTL. */
+  update(id: string, raw: unknown): PmxAxIntent {
+    if (this.committingIntentIds.has(id)) {
+      throw new OperationError(`Intent "${id}" is already committing.`, 409);
+    }
+    const existing = this.intents.get(id);
+    if (!existing) throw new OperationError(`No live intent "${id}".`, 404);
+    const patch = parseOrThrow(intentUpdateSchema, raw, 'intent update');
+    const now = Date.now();
+    const ttl = typeof patch.ttlMs === 'number' ? patch.ttlMs : DEFAULT_INTENT_TTL_MS;
+
+    const intent: PmxAxIntent = {
+      ...existing,
+      ...(patch.position ? { position: patch.position } : {}),
+      ...(patch.nodeType ? { nodeType: patch.nodeType } : {}),
+      ...(patch.label ? { label: patch.label } : {}),
+      ...(patch.reason ? { reason: patch.reason } : {}),
+      ...(typeof patch.confidence === 'number' ? { confidence: patch.confidence } : {}),
+      ...(typeof patch.seq === 'number' ? { seq: patch.seq } : {}),
+      expiresAt: now + ttl,
+    };
+    this.intents.set(id, intent);
+    this.emit('ax-intent', { intent });
+    return intent;
+  }
+
+  /**
+   * Clear an intent. `settledNodeId` resolves it INTO a real node (the settle
+   * morph); `vetoed` marks a human pre-emptive veto. Either way the ghost
+   * dissolves. Returns true when an intent was actually removed.
+   */
+  clear(id: string, opts: { settledNodeId?: string; vetoed?: boolean } = {}): boolean {
+    if (this.committingIntentIds.has(id)) return false;
+    if (!this.intents.delete(id)) return false;
+    if (opts.vetoed) this.rememberVeto(id);
+    this.emit('ax-intent-clear', {
+      id,
+      ...(opts.settledNodeId ? { nodeId: opts.settledNodeId, settled: true } : {}),
+      ...(opts.vetoed ? { vetoed: true } : {}),
+    });
+    this.maybeStopSweeper();
+    return true;
+  }
+
+  /**
+   * Gate one real mutation behind a live, non-vetoed intent. The claim is
+   * synchronous: once this method has accepted the intent, a later veto cannot
+   * race in between the check and the mutation.
+   */
+  beginCommit(id: string, allowedKinds: readonly PmxAxIntentKind[]): PmxAxIntent {
+    this.pruneVetoTombstones();
+    if (this.committingIntentIds.has(id)) {
+      throw new OperationError(`Intent "${id}" is already committing.`, 409);
+    }
+    if (this.vetoedIntentIds.has(id)) {
+      throw new OperationError(`Intent "${id}" was vetoed.`, 409);
+    }
+    const intent = this.intents.get(id);
+    if (!intent) {
+      throw new OperationError(`No live intent "${id}" to commit.`, 409);
+    }
+    if (!allowedKinds.includes(intent.kind)) {
+      throw new OperationError(
+        `Intent "${id}" has kind "${intent.kind}", which cannot commit this mutation.`,
+        409,
+      );
+    }
+    this.committingIntentIds.add(id);
+    return intent;
+  }
+
+  completeCommit(id: string, settledNodeId?: string): void {
+    this.committingIntentIds.delete(id);
+    this.clear(id, { ...(settledNodeId ? { settledNodeId } : {}) });
+  }
+
+  abortCommit(id: string): void {
+    this.committingIntentIds.delete(id);
+  }
+
+  async runCommit<T>(
+    id: string,
+    allowedKinds: readonly PmxAxIntentKind[],
+    mutate: () => T | Promise<T>,
+    settledNodeId: (result: T, intent: PmxAxIntent) => string | undefined,
+  ): Promise<T> {
+    const intent = this.beginCommit(id, allowedKinds);
+    try {
+      const result = await mutate();
+      this.completeCommit(id, settledNodeId(result, intent));
+      return result;
+    } catch (error) {
+      this.abortCommit(id);
+      throw error;
+    }
+  }
+
+  /** Drop every live intent without per-id SSE (used on hard resets). */
+  reset(): void {
+    this.intents.clear();
+    this.vetoedIntentIds.clear();
+    this.committingIntentIds.clear();
+    this.maybeStopSweeper();
+  }
+
+  private rememberVeto(id: string): void {
+    this.vetoedIntentIds.delete(id);
+    this.vetoedIntentIds.set(id, Date.now() + MAX_INTENT_TTL_MS);
+    while (this.vetoedIntentIds.size > MAX_VETO_TOMBSTONES) {
+      const oldest = this.vetoedIntentIds.keys().next().value as string | undefined;
+      if (!oldest) break;
+      this.vetoedIntentIds.delete(oldest);
+    }
+  }
+
+  private pruneVetoTombstones(): void {
+    const now = Date.now();
+    for (const [id, expiresAt] of this.vetoedIntentIds) {
+      if (expiresAt <= now) this.vetoedIntentIds.delete(id);
+    }
+  }
+
+  private evictOverflow(): void {
+    while (this.intents.size > MAX_LIVE_INTENTS) {
+      // Map preserves insertion order; the first key is the oldest live intent.
+      let oldest: string | undefined;
+      for (const id of this.intents.keys()) {
+        if (!this.committingIntentIds.has(id)) {
+          oldest = id;
+          break;
+        }
+      }
+      if (!oldest) break;
+      this.intents.delete(oldest);
+      this.emit('ax-intent-clear', { id: oldest, evicted: true });
+    }
+  }
+
+  private sweep(): void {
+    const now = Date.now();
+    for (const [id, intent] of this.intents) {
+      if (!this.committingIntentIds.has(id) && intent.expiresAt <= now) {
+        this.intents.delete(id);
+        this.emit('ax-intent-clear', { id, expired: true });
+      }
+    }
+    this.maybeStopSweeper();
+  }
+
+  private ensureSweeper(): void {
+    if (this.sweepTimer || this.intents.size === 0) return;
+    this.sweepTimer = setInterval(() => this.sweep(), 1000);
+    // Don't keep the process (or a test runner) alive just for ghost expiry.
+    (this.sweepTimer as { unref?: () => void }).unref?.();
+  }
+
+  private maybeStopSweeper(): void {
+    if (this.sweepTimer && this.intents.size === 0) {
+      clearInterval(this.sweepTimer);
+      this.sweepTimer = null;
+    }
+  }
+}
+
+/** Process-wide singleton, shared across HTTP handlers, MCP ops, and the SDK. */
+export const intentRegistry = new IntentRegistry();

package/src/server/operations/composites.ts

@@ -317,6 +317,17 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
       mark: 'ax.delivery.mark',
     },
   },
+  {
+    toolName: 'canvas_intent',
+    description:
+      'Ghost Cursor of Intent — announce the spatial move you are ABOUT to make so the canvas paints a faint pre-commit placeholder (legibility: the human sees the next move forming, and can veto it). Action "signal" registers an intent (kind create|move|connect|remove|edit; pass position for create/move, nodeId for move/edit/remove, edge for connect; optional label, reason, confidence 0..1, seq, ttlMs, and a stable id); "update" patches a live intent by id; "clear" abandons/dissolves it. To make veto authoritative, pass the returned id as intentId on the real canvas_node/canvas_edge/canvas_group/canvas_render mutation: vetoed or expired intents are rejected, and a successful linked mutation settles the ghost automatically. Intents are ephemeral presence: never persisted, never snapshotted, auto-expire (~8s).',
+    actionSummary: 'signal | update | clear',
+    actions: {
+      signal: 'intent.signal',
+      update: 'intent.update',
+      clear: 'intent.clear',
+    },
+  },
 ];
 
 /**

package/src/server/operations/index.ts

@@ -19,6 +19,7 @@ import { axAwaitOperations } from './ops/ax-await.js';
 import { batchOperations } from './ops/batch.js';
 import { webviewOperations } from './ops/webview.js';
 import { appOperations } from './ops/app.js';
+import { intentOperations } from './ops/intent.js';
 
 for (const op of [
   ...nodeOperations,
@@ -37,6 +38,7 @@ for (const op of [
   ...batchOperations,
   ...webviewOperations,
   ...appOperations,
+  ...intentOperations,
 ]) {
   registerOperation(op);
 }

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

@@ -16,6 +16,7 @@ const VALID_EDGE_STYLES = new Set(['solid', 'dashed', 'dotted']);
 // ── edge.add ──────────────────────────────────────────────────
 
 const edgeAddShape = {
+  intentId: z.string().optional().catch(undefined).describe('Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.'),
   from: z.string().optional().catch(undefined).describe('Source node ID'),
   to: z.string().optional().catch(undefined).describe('Target node ID'),
   fromSearch: z.string().optional().catch(undefined).describe('Resolve the source node by exact or fuzzy title/content search'),

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

@@ -25,6 +25,7 @@ function pickChildLayout(value: unknown): 'grid' | 'column' | 'flow' | undefined
 // ── group.create ──────────────────────────────────────────────
 
 const groupCreateShape = {
+  intentId: z.string().optional().catch(undefined).describe('Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.'),
   title: z.string().optional().catch(undefined).describe('Group title (default: "Group")'),
   childIds: z.unknown().optional().describe('Node IDs to include in the group. Group auto-sizes to fit them.'),
   color: z.string().optional().catch(undefined).describe('Group accent color (CSS color string, e.g. "#4a9eff")'),
@@ -90,6 +91,7 @@ const groupCreateOperation = defineOperation<z.infer<typeof groupCreateSchema>,
 // ── group.add ─────────────────────────────────────────────────
 
 const groupAddShape = {
+  intentId: z.string().optional().catch(undefined).describe('Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.'),
   groupId: z.string().optional().catch(undefined).describe('The group node ID'),
   childIds: z.unknown().optional().describe('Node IDs to add to the group'),
   childLayout: z.enum(['grid', 'column', 'flow']).optional().catch(undefined).describe('Optional child layout to apply while grouping'),
@@ -136,6 +138,7 @@ const groupAddOperation = defineOperation<z.infer<typeof groupAddSchema>, Record
 // ── group.remove (ungroup) ────────────────────────────────────
 
 const groupRemoveShape = {
+  intentId: z.string().optional().catch(undefined).describe('Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.'),
   groupId: z.string().optional().catch(undefined).describe('The group node ID to ungroup'),
 };
 

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

@@ -0,0 +1,132 @@
+/**
+ * Ghost Cursor of Intent operations: signal / update / clear a pre-commit
+ * intent. Surfaced over HTTP (POST/PATCH/DELETE /api/canvas/ax/intent) and,
+ * folded into the `canvas_intent` composite, over MCP.
+ *
+ * Intents are ephemeral presence — every op is `mutates: false` (NO
+ * `canvas-layout-update`; the ghost lives on its own `ax-intent` /
+ * `ax-intent-clear` channel, emitted by the IntentRegistry). These ops have no
+ * standalone `mcp` block on purpose: the composite reuses `op.inputShape` for
+ * advertising and dispatches by op name, so the only new MCP tool is the
+ * composite itself.
+ *
+ * The IntentRegistry is the single trust boundary (zod + per-kind validation);
+ * these handlers stay thin. This module must never import server.ts or index.ts.
+ */
+import { z } from 'zod';
+import { INTENT_EDGE_TYPES, INTENT_KINDS } from '../../../shared/ax-intent.js';
+import { intentRegistry } from '../../intent-registry.js';
+import { readJsonValue } from '../http.js';
+import { defineOperation, OperationError, type Operation } from '../types.js';
+
+const positionShape = z.object({ x: z.number(), y: z.number() });
+
+// ── intent.signal (canvas_intent action "signal") ─────────────
+
+const intentSignalShape = {
+  kind: z.enum(INTENT_KINDS).optional().describe('create | move | connect | remove | edit — the move about to be made.'),
+  position: positionShape.optional().describe('World coords: where a create forms, or the destination of a move.'),
+  nodeId: z.string().optional().describe('The existing node a move/edit/remove targets.'),
+  edge: z
+    .object({ from: z.string(), to: z.string(), type: z.enum(INTENT_EDGE_TYPES) })
+    .optional()
+    .describe('connect: the edge about to be drawn (from/to node ids + type).'),
+  nodeType: z.string().optional().describe('Node type the ghost renders (icon + type badge).'),
+  label: z.string().optional().describe('Short action label shown on the ghost chip ("Add evidence").'),
+  reason: z.string().optional().describe('Why — shown beneath the ghost. The legibility payoff.'),
+  confidence: z.number().optional().describe('0..1 → ghost opacity/solidity.'),
+  seq: z.number().optional().describe('Ordering hint for staged-batch ghosts (numbered previsualization).'),
+  ttlMs: z.number().optional().describe('Auto-expire after this many ms (default 8000, max 60000).'),
+  id: z.string().optional().describe('Stable id to update/clear/veto later; auto-generated if omitted.'),
+  source: z.string().optional().describe('Optional source label of the signalling surface.'),
+};
+
+const intentSignalSchema = z.looseObject(intentSignalShape);
+
+const intentSignalOperation = defineOperation<z.infer<typeof intentSignalSchema>, Record<string, unknown>>({
+  name: 'intent.signal',
+  mutates: false,
+  input: intentSignalSchema,
+  inputShape: intentSignalShape,
+  http: { method: 'POST', path: '/api/canvas/ax/intent' },
+  handler: (input) => {
+    const intent = intentRegistry.signal(input);
+    return { ok: true, intent } as unknown as Record<string, unknown>;
+  },
+});
+
+// ── intent.update (canvas_intent action "update") ─────────────
+
+const intentUpdateShape = {
+  id: z.string().optional().describe('The intent id to update.'),
+  position: positionShape.optional().describe('New world coords for the ghost.'),
+  nodeType: z.string().optional().describe('New node type for the ghost.'),
+  label: z.string().optional().describe('New ghost chip label.'),
+  reason: z.string().optional().describe('New rationale shown beneath the ghost.'),
+  confidence: z.number().optional().describe('0..1 → ghost opacity/solidity.'),
+  seq: z.number().optional().describe('New ordering hint.'),
+  ttlMs: z.number().optional().describe('Reset the TTL to this many ms from now.'),
+};
+
+const intentUpdateSchema = z.looseObject(intentUpdateShape);
+
+const intentUpdateOperation = defineOperation<z.infer<typeof intentUpdateSchema>, Record<string, unknown>>({
+  name: 'intent.update',
+  mutates: false,
+  input: intentUpdateSchema,
+  inputShape: intentUpdateShape,
+  http: { method: 'PATCH', path: '/api/canvas/ax/intent/:id' },
+  handler: (input) => {
+    const id = typeof input.id === 'string' ? input.id : '';
+    if (!id) throw new OperationError('intent update requires an id.');
+    const intent = intentRegistry.update(id, input);
+    return { ok: true, intent } as unknown as Record<string, unknown>;
+  },
+});
+
+// ── intent.clear (canvas_intent action "clear") ───────────────
+
+const intentClearShape = {
+  id: z.string().optional().describe('The intent id to clear.'),
+  settledNodeId: z.string().optional().describe('The real node this intent became — triggers the settle morph.'),
+  vetoed: z.boolean().optional().describe('Mark this as a human pre-emptive veto (dissolve).'),
+};
+
+const intentClearSchema = z.looseObject(intentClearShape);
+
+const intentClearOperation = defineOperation<z.infer<typeof intentClearSchema>, Record<string, unknown>>({
+  name: 'intent.clear',
+  mutates: false,
+  input: intentClearSchema,
+  inputShape: intentClearShape,
+  http: {
+    method: 'DELETE',
+    path: '/api/canvas/ax/intent/:id',
+    readInput: async (req, params, url) => {
+      const query: Record<string, string> = {};
+      url.searchParams.forEach((value, key) => {
+        query[key] = value;
+      });
+      const body = await readJsonValue(req);
+      const record = body !== null && typeof body === 'object' && !Array.isArray(body)
+        ? body as Record<string, unknown>
+        : {};
+      return { ...query, ...record, ...params };
+    },
+  },
+  handler: (input) => {
+    const id = typeof input.id === 'string' ? input.id : '';
+    if (!id) throw new OperationError('intent clear requires an id.');
+    const cleared = intentRegistry.clear(id, {
+      ...(typeof input.settledNodeId === 'string' ? { settledNodeId: input.settledNodeId } : {}),
+      ...(input.vetoed === true ? { vetoed: true } : {}),
+    });
+    return { ok: true, cleared } as unknown as Record<string, unknown>;
+  },
+});
+
+export const intentOperations: Operation[] = [
+  intentSignalOperation,
+  intentUpdateOperation,
+  intentClearOperation,
+];

package/src/server/operations/ops/json-render.ts

@@ -89,6 +89,7 @@ function structuredNodeToolResult(result: unknown): { content: Array<{ type: 'te
 // ── jsonrender.add ────────────────────────────────────────────
 
 const jsonRenderAddShape = {
+  intentId: z.string().optional().catch(undefined).describe('Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.'),
   title: z.string().optional().catch(undefined).describe('Optional node title. If omitted, PMX Canvas infers one from the root element.'),
   spec: z.unknown().describe('json-render spec. Prefer a complete {root, elements, state?} document; a single bare component object is accepted for legacy callers.'),
   x: z.number().optional().catch(undefined).describe('Optional X position'),
@@ -193,6 +194,7 @@ export function streamJsonRenderCore(input: StreamJsonRenderInput): StreamJsonRe
 }
 
 const jsonRenderStreamShape = {
+  intentId: z.string().optional().catch(undefined).describe('Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.'),
   nodeId: z.string().optional().catch(undefined).describe('Existing streaming node id to append to; omit to create a new streaming node'),
   title: z.string().optional().catch(undefined).describe('Title when creating a new streaming node'),
   patches: z.unknown().optional().describe('SpecStream patches to apply this call: JSON-Patch objects ({op,path,value}) or raw JSONL patch lines'),
@@ -277,6 +279,7 @@ const jsonRenderStreamOperation = defineOperation<
 // ── graph.add ─────────────────────────────────────────────────
 
 const graphAddShape = {
+  intentId: z.string().optional().catch(undefined).describe('Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.'),
   title: z.string().optional().catch(undefined).describe('Optional node title'),
   graphType: z.string().optional().catch(undefined).describe('Graph type: line, bar, pie, area, scatter, radar, stacked-bar (or "stack"), composed (or "combo"), sparkline, dot-plot (or "dot"), bullet, slopegraph (or "slope")'),
   data: z.unknown().optional().describe('Array of chart data objects'),

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

@@ -653,6 +653,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)'),
   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)'),
@@ -834,6 +835,7 @@ const nodeGetOperation = defineOperation<z.infer<typeof nodeGetSchema>, Serializ
 
 const nodeUpdateShape = {
   id: z.string().describe('Node ID to update'),
+  intentId: z.string().optional().catch(undefined).describe('Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.'),
   title: z.unknown().optional().describe('New title'),
   content: z.unknown().optional().describe('New content'),
   x: z.number().optional().catch(undefined).describe('New X position'),
@@ -965,6 +967,7 @@ const nodeUpdateOperation = defineOperation<z.infer<typeof nodeUpdateSchema>, Re
 
 const nodeRemoveShape = {
   id: z.string().describe('Node ID to remove'),
+  intentId: z.string().optional().catch(undefined).describe('Ghost intent id returned by canvas_intent signal. A vetoed or expired intent blocks this mutation.'),
 };
 
 const nodeRemoveSchema = z.looseObject(nodeRemoveShape);

package/src/server/operations/registry.ts

@@ -8,6 +8,8 @@
  * `mutates: true` is the single source; extra events go through `ctx.emit`.
  */
 import { canvasState } from '../canvas-state.js';
+import { intentRegistry } from '../intent-registry.js';
+import type { PmxAxIntent, PmxAxIntentKind } from '../../shared/ax-intent.js';
 import { OperationError, type Operation, type OperationContext } from './types.js';
 
 const operations = new Map<string, Operation>();
@@ -69,11 +71,74 @@ export async function runWithSuppressedEmits<T>(fn: () => Promise<T>): Promise<T
 
 const operationContext: OperationContext = { emit: emitOperationEvent };
 
+const INTENT_KINDS_BY_OPERATION: Record<string, readonly PmxAxIntentKind[]> = {
+  'node.add': ['create'],
+  'jsonrender.add': ['create'],
+  'graph.add': ['create'],
+  'group.create': ['create'],
+  'node.update': ['move', 'edit'],
+  'group.add': ['edit'],
+  'group.remove': ['edit'],
+  'edge.add': ['connect'],
+  'node.remove': ['remove'],
+};
+
+function linkedIntentId(rawInput: unknown): string | undefined {
+  if (!rawInput || typeof rawInput !== 'object' || Array.isArray(rawInput)) return undefined;
+  const record = rawInput as Record<string, unknown>;
+  if (record.intentId === undefined) return undefined;
+  if (typeof record.intentId !== 'string' || record.intentId.trim().length === 0) {
+    throw new OperationError('intentId must be a non-empty string.');
+  }
+  return record.intentId;
+}
+
+function allowedIntentKinds(name: string, rawInput: unknown): readonly PmxAxIntentKind[] | undefined {
+  if (name === 'jsonrender.stream') {
+    const input = rawInput && typeof rawInput === 'object' && !Array.isArray(rawInput)
+      ? rawInput as Record<string, unknown>
+      : {};
+    return typeof input.nodeId === 'string' && input.nodeId.length > 0 ? ['edit'] : ['create'];
+  }
+  return INTENT_KINDS_BY_OPERATION[name];
+}
+
+function settledNodeId(result: unknown, intent: PmxAxIntent): string | undefined {
+  if (intent.kind === 'connect' || intent.kind === 'remove') return undefined;
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return undefined;
+  const record = result as Record<string, unknown>;
+  if (typeof record.nodeId === 'string') return record.nodeId;
+  if (record.node && typeof record.node === 'object' && !Array.isArray(record.node)) {
+    const id = (record.node as Record<string, unknown>).id;
+    if (typeof id === 'string') return id;
+  }
+  if (typeof record.groupId === 'string') return record.groupId;
+  return typeof record.id === 'string' ? record.id : undefined;
+}
+
 export async function executeOperation(name: string, rawInput: unknown): Promise<unknown> {
   const op = getOperation(name);
-  const result = await op.execute(rawInput, operationContext);
-  if (op.mutates) {
-    emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+  const intentId = linkedIntentId(rawInput);
+  const allowedKinds = intentId ? allowedIntentKinds(name, rawInput) : undefined;
+  if (intentId && !allowedKinds) {
+    throw new OperationError(`Operation "${name}" cannot be committed through a ghost intent.`);
   }
+  if (intentId) {
+    return intentRegistry.runCommit(
+      intentId,
+      allowedKinds!,
+      async () => {
+        const result = await op.execute(rawInput, operationContext);
+        if (op.mutates) {
+          emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+        }
+        return result;
+      },
+      settledNodeId,
+    );
+  }
+
+  const result = await op.execute(rawInput, operationContext);
+  if (op.mutates) emitOperationEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   return result;
 }