pmx-canvas 0.1.29 → 0.1.31

package/src/server/ax-state.ts

@@ -13,7 +13,7 @@ export interface PmxAxFocusState {
 // ── New enums ──────────────────────────────────────────────────────
 export type PmxAxEventKind =
   | 'prompt' | 'assistant-message' | 'tool-start' | 'tool-result'
-  | 'failure' | 'approval' | 'steering';
+  | 'failure' | 'approval' | 'steering' | 'command';
 export type PmxAxEvidenceKind =
   | 'logs' | 'tool-result' | 'screenshot' | 'file' | 'diff' | 'test-output';
 export type PmxAxWorkItemStatus = 'todo' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
@@ -141,6 +141,9 @@ export interface PmxAxState {
   workItems: PmxAxWorkItem[];
   approvalGates: PmxAxApprovalGate[];
   reviewAnnotations: PmxAxReviewAnnotation[];
+  elicitations: PmxAxElicitation[];
+  modeRequests: PmxAxModeRequest[];
+  policy: PmxAxPolicy;
 }
 
 export interface PmxAxPinnedContext {
@@ -166,6 +169,9 @@ export interface PmxAxContext {
   workItems: PmxAxWorkItem[];
   approvalGates: PmxAxApprovalGate[];
   reviewAnnotations: PmxAxReviewAnnotation[];
+  elicitations: PmxAxElicitation[];
+  modeRequests: PmxAxModeRequest[];
+  policy: PmxAxPolicy;
   timeline: PmxAxTimelineSummary;
   host: PmxAxHostCapability | null;
 }
@@ -199,7 +205,69 @@ function normalizeNodeIds(value: unknown, validNodeIds?: Set<string>): string[]
   return ids;
 }
 
-const AX_EVENT_KINDS = new Set<PmxAxEventKind>(['prompt', 'assistant-message', 'tool-start', 'tool-result', 'failure', 'approval', 'steering']);
+const AX_EVENT_KINDS = new Set<PmxAxEventKind>(['prompt', 'assistant-message', 'tool-start', 'tool-result', 'failure', 'approval', 'steering', 'command']);
+
+// ── Command registry (plan-004 Phase 5) ────────────────────────
+// Named, registry-gated PMX intents — NOT arbitrary execution. Invoking a command
+// records a timeline event a host/agent can observe and act on; unknown names are
+// rejected. Seeded with conservative built-ins; project-extensible later.
+export interface PmxAxCommandDescriptor {
+  name: string;
+  description: string;
+}
+
+export const AX_COMMAND_REGISTRY: Record<string, PmxAxCommandDescriptor> = {
+  'pmx.plan': { name: 'pmx.plan', description: 'Enter planning: outline the approach before executing.' },
+  'pmx.execute': { name: 'pmx.execute', description: 'Proceed from plan to execution.' },
+  'pmx.promote-context': { name: 'pmx.promote-context', description: 'Promote focused/pinned nodes into durable agent context.' },
+  'pmx.summarize': { name: 'pmx.summarize', description: 'Summarize the current canvas/work state.' },
+  'pmx.review': { name: 'pmx.review', description: 'Start a review pass over the focused nodes.' },
+};
+
+export function isAxCommand(name: unknown): name is string {
+  return typeof name === 'string' && Object.prototype.hasOwnProperty.call(AX_COMMAND_REGISTRY, name);
+}
+
+export function listAxCommands(): PmxAxCommandDescriptor[] {
+  return Object.values(AX_COMMAND_REGISTRY);
+}
+
+// ── Tool/prompt policy (plan-004 Phase 5) ──────────────────────
+// Declarative policy PMX stores and exposes; host adapters READ and enforce it.
+// PMX does not mutate host prompts or block tools itself. Default = empty (no
+// restrictions) — that is the conservative answer to "how much by default".
+export interface PmxAxPolicy {
+  tools: { allowed: string[]; excluded: string[]; approvalRequired: string[] };
+  prompt: { systemAppend: string | null; mode: string | null };
+}
+
+export function createEmptyAxPolicy(): PmxAxPolicy {
+  return {
+    tools: { allowed: [], excluded: [], approvalRequired: [] },
+    prompt: { systemAppend: null, mode: null },
+  };
+}
+
+function normalizeStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : [];
+}
+
+export function normalizeAxPolicy(input: unknown): PmxAxPolicy {
+  if (!isRecord(input)) return createEmptyAxPolicy();
+  const tools = isRecord(input.tools) ? input.tools : {};
+  const prompt = isRecord(input.prompt) ? input.prompt : {};
+  return {
+    tools: {
+      allowed: normalizeStringArray(tools.allowed),
+      excluded: normalizeStringArray(tools.excluded),
+      approvalRequired: normalizeStringArray(tools.approvalRequired),
+    },
+    prompt: {
+      systemAppend: optionalString(prompt.systemAppend),
+      mode: optionalString(prompt.mode),
+    },
+  };
+}
 const AX_EVIDENCE_KINDS = new Set<PmxAxEvidenceKind>(['logs', 'tool-result', 'screenshot', 'file', 'diff', 'test-output']);
 const AX_WORK_STATUSES = new Set<PmxAxWorkItemStatus>(['todo', 'in-progress', 'blocked', 'done', 'cancelled']);
 const AX_APPROVAL_STATUSES = new Set<PmxAxApprovalStatus>(['pending', 'approved', 'rejected']);
@@ -241,6 +309,108 @@ export function createEmptyAxFocusState(): PmxAxFocusState {
   };
 }
 
+// ── Elicitation (structured human input request) — plan-004 Phase 5 ──
+
+export type PmxAxElicitationStatus = 'pending' | 'answered' | 'cancelled';
+const AX_ELICITATION_STATUSES = new Set<PmxAxElicitationStatus>(['pending', 'answered', 'cancelled']);
+
+export interface PmxAxElicitation {
+  id: string;
+  prompt: string;
+  fields: string[];
+  status: PmxAxElicitationStatus;
+  response: Record<string, unknown> | null;
+  nodeIds: string[];
+  createdAt: string;
+  resolvedAt: string | null;
+  source: PmxAxSource | null;
+}
+
+export function normalizeAxElicitation(input: unknown, validNodeIds?: Set<string>): PmxAxElicitation | null {
+  if (!isRecord(input) || typeof input.id !== 'string') return null;
+  return {
+    id: input.id,
+    prompt: typeof input.prompt === 'string' ? input.prompt : '(input requested)',
+    fields: Array.isArray(input.fields) ? input.fields.filter((f): f is string => typeof f === 'string') : [],
+    status: AX_ELICITATION_STATUSES.has(input.status as PmxAxElicitationStatus) ? input.status as PmxAxElicitationStatus : 'pending',
+    response: isRecord(input.response) ? input.response : null,
+    nodeIds: normalizeNodeIds(input.nodeIds, validNodeIds),
+    createdAt: normalizeTimestamp(input.createdAt) ?? nowIso(),
+    resolvedAt: normalizeTimestamp(input.resolvedAt),
+    source: normalizeSource(input.source),
+  };
+}
+
+export function createAxElicitation(
+  input: { prompt: string; fields?: string[]; nodeIds?: string[] },
+  source: PmxAxSource | null,
+  validNodeIds?: Set<string>,
+): PmxAxElicitation {
+  return {
+    id: axId('elic'),
+    prompt: input.prompt,
+    fields: Array.isArray(input.fields) ? input.fields.filter((f) => typeof f === 'string') : [],
+    status: 'pending',
+    response: null,
+    nodeIds: normalizeNodeIds(input.nodeIds, validNodeIds),
+    createdAt: nowIso(),
+    resolvedAt: null,
+    source,
+  };
+}
+
+// ── Mode request (plan/execute/autonomous transition) — plan-004 Phase 5 ──
+
+export type PmxAxMode = 'plan' | 'execute' | 'autonomous';
+export type PmxAxModeRequestStatus = 'pending' | 'approved' | 'rejected';
+const AX_MODES = new Set<PmxAxMode>(['plan', 'execute', 'autonomous']);
+const AX_MODE_REQUEST_STATUSES = new Set<PmxAxModeRequestStatus>(['pending', 'approved', 'rejected']);
+
+export interface PmxAxModeRequest {
+  id: string;
+  mode: PmxAxMode;
+  reason: string | null;
+  status: PmxAxModeRequestStatus;
+  nodeIds: string[];
+  createdAt: string;
+  resolvedAt: string | null;
+  resolution: string | null;
+  source: PmxAxSource | null;
+}
+
+export function normalizeAxModeRequest(input: unknown, validNodeIds?: Set<string>): PmxAxModeRequest | null {
+  if (!isRecord(input) || typeof input.id !== 'string') return null;
+  return {
+    id: input.id,
+    mode: AX_MODES.has(input.mode as PmxAxMode) ? input.mode as PmxAxMode : 'execute',
+    reason: optionalString(input.reason),
+    status: AX_MODE_REQUEST_STATUSES.has(input.status as PmxAxModeRequestStatus) ? input.status as PmxAxModeRequestStatus : 'pending',
+    nodeIds: normalizeNodeIds(input.nodeIds, validNodeIds),
+    createdAt: normalizeTimestamp(input.createdAt) ?? nowIso(),
+    resolvedAt: normalizeTimestamp(input.resolvedAt),
+    resolution: optionalString(input.resolution),
+    source: normalizeSource(input.source),
+  };
+}
+
+export function createAxModeRequest(
+  input: { mode: PmxAxMode; reason?: string | null; nodeIds?: string[] },
+  source: PmxAxSource | null,
+  validNodeIds?: Set<string>,
+): PmxAxModeRequest {
+  return {
+    id: axId('mode'),
+    mode: input.mode,
+    reason: input.reason ?? null,
+    status: 'pending',
+    nodeIds: normalizeNodeIds(input.nodeIds, validNodeIds),
+    createdAt: nowIso(),
+    resolvedAt: null,
+    resolution: null,
+    source,
+  };
+}
+
 export function createEmptyAxState(): PmxAxState {
   return {
     version: 1,
@@ -248,6 +418,9 @@ export function createEmptyAxState(): PmxAxState {
     workItems: [],
     approvalGates: [],
     reviewAnnotations: [],
+    elicitations: [],
+    modeRequests: [],
+    policy: createEmptyAxPolicy(),
   };
 }
 
@@ -538,6 +711,13 @@ export function normalizeAxState(input: unknown, validNodeIds?: Set<string>): Pm
     reviewAnnotations: Array.isArray(input.reviewAnnotations)
       ? input.reviewAnnotations.map((r) => normalizeAxReviewAnnotation(r, validNodeIds)).filter((r): r is PmxAxReviewAnnotation => r !== null)
       : [],
+    elicitations: Array.isArray(input.elicitations)
+      ? input.elicitations.map((e) => normalizeAxElicitation(e, validNodeIds)).filter((e): e is PmxAxElicitation => e !== null)
+      : [],
+    modeRequests: Array.isArray(input.modeRequests)
+      ? input.modeRequests.map((m) => normalizeAxModeRequest(m, validNodeIds)).filter((m): m is PmxAxModeRequest => m !== null)
+      : [],
+    policy: normalizeAxPolicy(input.policy),
   };
 }
 
@@ -549,6 +729,9 @@ export function buildAxContext(input: {
   workItems: PmxAxWorkItem[];
   approvalGates: PmxAxApprovalGate[];
   reviewAnnotations: PmxAxReviewAnnotation[];
+  elicitations: PmxAxElicitation[];
+  modeRequests: PmxAxModeRequest[];
+  policy: PmxAxPolicy;
   timeline: PmxAxTimelineSummary;
   host: PmxAxHostCapability | null;
 }): PmxAxContext {
@@ -567,6 +750,9 @@ export function buildAxContext(input: {
     workItems: input.workItems,
     approvalGates: input.approvalGates,
     reviewAnnotations: input.reviewAnnotations,
+    elicitations: input.elicitations,
+    modeRequests: input.modeRequests,
+    policy: input.policy,
     timeline: input.timeline,
     host: input.host,
   };

package/src/server/canvas-db.ts

@@ -901,6 +901,26 @@ export function loadAxSteeringFromDB(db: Database, q: AxTimelineQuery & { onlyPe
     .filter((s): s is PmxAxSteeringMessage => s !== null);
 }
 
+export function loadPendingAxSteeringFromDB(
+  db: Database,
+  options: { consumer?: string; limit?: number } = {},
+): PmxAxSteeringMessage[] {
+  interface Row { seq: number; id: string; message: string; delivered: number; created_at: string; source: string | null }
+  // FIFO (oldest undelivered first); exclude the consumer's own steering in SQL
+  // so the LIMIT is applied AFTER loop-prevention, not before.
+  const limit = clampTimelineLimit(options.limit);
+  const rows = options.consumer
+    ? db.query<Row, [string, number]>(
+        'SELECT * FROM ax_steering WHERE delivered = 0 AND (source IS NULL OR source != ?) ORDER BY seq ASC LIMIT ?',
+      ).all(options.consumer, limit)
+    : db.query<Row, [number]>(
+        'SELECT * FROM ax_steering WHERE delivered = 0 ORDER BY seq ASC LIMIT ?',
+      ).all(limit);
+  return rows
+    .map((r) => normalizeAxSteeringMessage({ ...r, createdAt: r.created_at, delivered: r.delivered === 1 }))
+    .filter((s): s is PmxAxSteeringMessage => s !== null);
+}
+
 function countRows(db: Database, table: 'ax_events' | 'ax_evidence' | 'ax_steering'): number {
   return Number(db.query<{ n: number }, []>(`SELECT COUNT(*) AS n FROM ${table}`).get()?.n ?? 0);
 }

package/src/server/canvas-operations.ts

@@ -1467,6 +1467,10 @@ export function groupCanvasNodes(
 ): { ok: boolean } {
   return {
     ok: canvasState.groupNodes(groupId, childIds, {
+      // Preserve existing child positions unless an explicit layout is asked
+      // for — matching createCanvasGroup and the batch group.add path. Without
+      // this, grouping silently auto-packs the nodes into a grid.
+      preservePositions: options.childLayout === undefined,
       ...(options.childLayout ? { layout: options.childLayout } : {}),
     }),
   };
@@ -1836,6 +1840,13 @@ export async function executeCanvasBatch(
           result = { ok: true, ...(updated ? serializeCreatedNode(updated) : { id }) };
           break;
         }
+        case 'node.remove': {
+          const id = typeof args.id === 'string' ? args.id : '';
+          const { removed } = removeCanvasNode(id);
+          if (!removed) throw new Error(`Node "${id}" not found.`);
+          result = { ok: true, id, removed: true };
+          break;
+        }
         case 'graph.add': {
           const created = createCanvasGraphNode({
             graphType: String(args.graphType ?? 'line'),

package/src/server/canvas-serialization.ts

@@ -6,6 +6,7 @@ import {
   type CanvasNodeProvenance,
 } from './canvas-provenance.js';
 import { getCanvasNodeKind as getSharedCanvasNodeKind } from '../shared/canvas-node-kind.js';
+import { canOpenNodeAsSurface } from '../shared/surface.js';
 
 export interface SerializedCanvasNode extends CanvasNodeState {
   kind: string;
@@ -13,6 +14,7 @@ export interface SerializedCanvasNode extends CanvasNodeState {
   content: string | null;
   path: string | null;
   url: string | null;
+  surfaceUrl: string | null;
   provenance: CanvasNodeProvenance | null;
 }
 
@@ -101,6 +103,12 @@ export function getCanvasNodeContent(node: CanvasNodeState): string | null {
     ?? null;
 }
 
+export function getCanvasNodeSurfaceUrl(node: CanvasNodeState, data: Record<string, unknown>): string | null {
+  return canOpenNodeAsSurface(node.type, data)
+    ? `/api/canvas/surface/${encodeURIComponent(node.id)}`
+    : null;
+}
+
 export function serializeCanvasNode(node: CanvasNodeState): SerializedCanvasNode {
   const data = normalizeCanvasNodeData(node.type, node.data);
   const normalizedNode = { ...node, data };
@@ -112,6 +120,7 @@ export function serializeCanvasNode(node: CanvasNodeState): SerializedCanvasNode
     content: getCanvasNodeContent(normalizedNode),
     path: pickString(data.path),
     url: pickString(data.url),
+    surfaceUrl: getCanvasNodeSurfaceUrl(node, data),
     provenance: pickProvenance(data.provenance),
   };
 }

package/src/server/canvas-state.ts

@@ -36,6 +36,7 @@ import {
   loadAxEventsFromDB,
   loadAxEvidenceFromDB,
   loadAxSteeringFromDB,
+  loadPendingAxSteeringFromDB,
   loadAxTimelineSummaryFromDB,
   upsertAxHostCapabilityToDB,
   loadAxHostCapabilityFromDB,
@@ -63,6 +64,17 @@ import {
   createAxEvent,
   createAxEvidence,
   createAxSteeringMessage,
+  createAxElicitation,
+  createAxModeRequest,
+  isAxCommand,
+  listAxCommands,
+  AX_COMMAND_REGISTRY,
+  normalizeAxPolicy,
+  type PmxAxElicitation,
+  type PmxAxModeRequest,
+  type PmxAxMode,
+  type PmxAxCommandDescriptor,
+  type PmxAxPolicy,
   type PmxAxFocusState,
   type PmxAxSource,
   type PmxAxState,
@@ -247,7 +259,7 @@ export interface CanvasNodeUpdate {
 export type CanvasChangeType = 'pins' | 'nodes' | 'ax' | 'ax-timeline';
 
 export interface MutationRecordInfo {
-  operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'addWorkItem' | 'updateWorkItem' | 'requestApproval' | 'resolveApproval' | 'addReviewAnnotation' | 'updateReviewAnnotation' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
+  operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'addWorkItem' | 'updateWorkItem' | 'requestApproval' | 'resolveApproval' | 'addReviewAnnotation' | 'updateReviewAnnotation' | 'requestElicitation' | 'respondElicitation' | 'requestMode' | 'resolveModeRequest' | 'setPolicy' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
   description: string;
   forward: () => void;
   inverse: () => void;
@@ -430,18 +442,14 @@ class CanvasStateManager {
   }
 
   private normalizeNode(node: CanvasNodeState): CanvasNodeState {
-    const normalized: CanvasNodeState = {
+    // Context nodes default to a right-docked, collapsed pill (see DockedNode.tsx),
+    // but that default is applied at CREATE time only — it must not be re-forced on
+    // every write, or the node could never be undocked. Undocking (dockPosition →
+    // null) is a deliberate user action and is respected here.
+    return {
       ...node,
       data: normalizeCanvasNodeData(node.type, node.data),
     };
-    // Context nodes are always docked to the right side as a pill/panel widget
-    // (see DockedNode.tsx). They start collapsed so the user sees the slim
-    // pill first; expanding reveals the full context overview panel.
-    if (normalized.type === 'context' && normalized.dockPosition !== 'right') {
-      normalized.dockPosition = 'right';
-      normalized.collapsed = true;
-    }
-    return normalized;
   }
 
   private nodeForRead(node: CanvasNodeState): CanvasNodeState {
@@ -918,6 +926,16 @@ class CanvasStateManager {
     return false;
   }
 
+  /**
+   * Whether this workspace's canvas DB already holds saved state. Used to gate
+   * brand-new-workspace seeding (e.g. the default docked status/context widgets)
+   * so we never add nodes to a canvas that already has content. Reflects the
+   * pre-run persisted flag until the next save.
+   */
+  hasPersistedState(): boolean {
+    return this._db ? isDbPopulated(this._db) : false;
+  }
+
   /** Debounced save — coalesces rapid mutations into a single write. */
   private scheduleSave(): void {
     if (!this._db) return;
@@ -1331,7 +1349,15 @@ class CanvasStateManager {
   }
 
   addNode(node: CanvasNodeState): void {
-    const cloned = structuredClone(this.normalizeNode(node));
+    // Context nodes default to a right-docked, collapsed pill when created without
+    // an explicit dock position. CREATE-time default only — once placed, updates
+    // (including undock → dockPosition null) are respected (see normalizeNode).
+    // Skip during suppressed replay (undo/redo re-add) so a deliberately-undocked
+    // context node is restored verbatim instead of being snapped back to the dock.
+    const seeded = node.type === 'context' && node.dockPosition == null && this._suppressRecordingDepth === 0
+      ? { ...node, dockPosition: 'right' as const, collapsed: true }
+      : node;
+    const cloned = structuredClone(this.normalizeNode(seeded));
     this.nodes.set(node.id, cloned);
     this.scheduleSave();
     this.notifyChange('nodes');
@@ -1366,11 +1392,11 @@ class CanvasStateManager {
     this.nodes.set(id, nextNode);
     const parentGroupId = existing.data.parentGroup as string | undefined;
     if (parentGroupId) {
-      if (patch.size) {
-        this.compactGroupChildren(parentGroupId);
-      } else {
-        this.recomputeParentGroupBounds(parentGroupId);
-      }
+      // Moving or resizing a grouped child re-fits the group frame but must NOT
+      // repack siblings — that would discard their explicit positions and the
+      // moved child's requested coordinates. Compaction is opt-in (group
+      // create/add with childLayout, or arrange).
+      this.recomputeParentGroupBounds(parentGroupId);
       this.reflowAllGroups();
     }
     this.scheduleSave();
@@ -1561,7 +1587,7 @@ class CanvasStateManager {
   applyUpdates(updates: CanvasNodeUpdate[], options: ApplyUpdatesOptions = {}): { applied: number; skipped: number } {
     let applied = 0;
     let skipped = 0;
-    const touchedParentGroups = new Map<string, { compact: boolean }>();
+    const touchedParentGroups = new Set<string>();
     const oldSnapshots = new Map<string, CanvasNodeState>();
     const appliedUpdates: CanvasNodeUpdate[] = [];
     const explicitPositionUpdateIds = new Set(
@@ -1615,19 +1641,17 @@ class CanvasStateManager {
       }));
       const parentGroupId = existing.data.parentGroup as string | undefined;
       if (parentGroupId) {
-        const entry = touchedParentGroups.get(parentGroupId) ?? { compact: false };
-        entry.compact = entry.compact || nextPatch.size !== undefined;
-        touchedParentGroups.set(parentGroupId, entry);
+        touchedParentGroups.add(parentGroupId);
       }
       applied++;
     }
 
-    for (const [groupId, entry] of touchedParentGroups) {
-      if (entry.compact) {
-        this.compactGroupChildren(groupId);
-      } else {
-        this.recomputeParentGroupBounds(groupId);
-      }
+    // Moving or resizing a grouped child re-fits the group frame, but must NOT
+    // repack siblings — that would discard their explicit positions and the
+    // moved child's requested coordinates. Compaction is opt-in, applied only
+    // through an explicit layout (group create/add with childLayout, or arrange).
+    for (const groupId of touchedParentGroups) {
+      this.recomputeParentGroupBounds(groupId);
     }
     if (touchedParentGroups.size > 0) this.reflowAllGroups();
 
@@ -1918,6 +1942,148 @@ class CanvasStateManager {
     return this._axHostCapability;
   }
 
+  getElicitations(): PmxAxElicitation[] {
+    return this.getAxState().elicitations;
+  }
+
+  requestElicitation(
+    input: { prompt: string; fields?: string[]; nodeIds?: string[] },
+    options: { source?: PmxAxSource } = {},
+  ): PmxAxElicitation {
+    const oldAxState = this.getAxState();
+    const elicitation = createAxElicitation(input, options.source ?? 'api', this.currentNodeIdSet());
+    this.applyAxState({ ...oldAxState, elicitations: [...oldAxState.elicitations, elicitation] });
+    const applied = this.getAxState();
+    this.scheduleSave();
+    this.notifyChange('ax');
+    this.recordMutation({
+      operationType: 'requestElicitation',
+      description: `Requested elicitation "${elicitation.prompt}"`,
+      forward: this.suppressed(() => { this.applyAxState(applied); this.scheduleSave(); this.notifyChange('ax'); }),
+      inverse: this.suppressed(() => { this.applyAxState(oldAxState); this.scheduleSave(); this.notifyChange('ax'); }),
+    });
+    return applied.elicitations.find((e) => e.id === elicitation.id) ?? elicitation;
+  }
+
+  respondElicitation(
+    id: string,
+    response: Record<string, unknown>,
+    options: { source?: PmxAxSource } = {},
+  ): PmxAxElicitation | null {
+    const oldAxState = this.getAxState();
+    const existing = oldAxState.elicitations.find((e) => e.id === id);
+    if (!existing || existing.status !== 'pending') return null;
+    const merged: PmxAxElicitation = {
+      ...existing,
+      status: 'answered',
+      response,
+      resolvedAt: new Date().toISOString(),
+      source: options.source ?? existing.source,
+    };
+    this.applyAxState({ ...oldAxState, elicitations: replaceById(oldAxState.elicitations, merged) });
+    const applied = this.getAxState();
+    this.scheduleSave();
+    this.notifyChange('ax');
+    this.recordMutation({
+      operationType: 'respondElicitation',
+      description: `Answered elicitation ${id}`,
+      forward: this.suppressed(() => { this.applyAxState(applied); this.scheduleSave(); this.notifyChange('ax'); }),
+      inverse: this.suppressed(() => { this.applyAxState(oldAxState); this.scheduleSave(); this.notifyChange('ax'); }),
+    });
+    return applied.elicitations.find((e) => e.id === id) ?? null;
+  }
+
+  getModeRequests(): PmxAxModeRequest[] {
+    return this.getAxState().modeRequests;
+  }
+
+  requestMode(
+    input: { mode: PmxAxMode; reason?: string | null; nodeIds?: string[] },
+    options: { source?: PmxAxSource } = {},
+  ): PmxAxModeRequest {
+    const oldAxState = this.getAxState();
+    const request = createAxModeRequest(input, options.source ?? 'api', this.currentNodeIdSet());
+    this.applyAxState({ ...oldAxState, modeRequests: [...oldAxState.modeRequests, request] });
+    const applied = this.getAxState();
+    this.scheduleSave();
+    this.notifyChange('ax');
+    this.recordMutation({
+      operationType: 'requestMode',
+      description: `Requested mode "${request.mode}"`,
+      forward: this.suppressed(() => { this.applyAxState(applied); this.scheduleSave(); this.notifyChange('ax'); }),
+      inverse: this.suppressed(() => { this.applyAxState(oldAxState); this.scheduleSave(); this.notifyChange('ax'); }),
+    });
+    return applied.modeRequests.find((m) => m.id === request.id) ?? request;
+  }
+
+  resolveModeRequest(
+    id: string,
+    decision: 'approved' | 'rejected',
+    options: { resolution?: string; source?: PmxAxSource } = {},
+  ): PmxAxModeRequest | null {
+    const oldAxState = this.getAxState();
+    const existing = oldAxState.modeRequests.find((m) => m.id === id);
+    if (!existing || existing.status !== 'pending') return null;
+    const merged: PmxAxModeRequest = {
+      ...existing,
+      status: decision,
+      resolvedAt: new Date().toISOString(),
+      resolution: options.resolution ?? null,
+      source: options.source ?? existing.source,
+    };
+    this.applyAxState({ ...oldAxState, modeRequests: replaceById(oldAxState.modeRequests, merged) });
+    const applied = this.getAxState();
+    this.scheduleSave();
+    this.notifyChange('ax');
+    this.recordMutation({
+      operationType: 'resolveModeRequest',
+      description: `Resolved mode request ${id} -> ${decision}`,
+      forward: this.suppressed(() => { this.applyAxState(applied); this.scheduleSave(); this.notifyChange('ax'); }),
+      inverse: this.suppressed(() => { this.applyAxState(oldAxState); this.scheduleSave(); this.notifyChange('ax'); }),
+    });
+    return applied.modeRequests.find((m) => m.id === id) ?? null;
+  }
+
+  getCommandRegistry(): PmxAxCommandDescriptor[] {
+    return listAxCommands();
+  }
+
+  /** Invoke a registry-gated PMX command intent — records a timeline event (no execution). */
+  invokeCommand(name: string, args: Record<string, unknown> | null = null, options: { source?: PmxAxSource } = {}): PmxAxEvent | null {
+    if (!isAxCommand(name)) return null;
+    return this.recordAxEvent(
+      { kind: 'command', summary: name, detail: AX_COMMAND_REGISTRY[name].description, data: { command: name, ...(args ? { args } : {}) } },
+      options,
+    );
+  }
+
+  getPolicy(): PmxAxPolicy {
+    return this.getAxState().policy;
+  }
+
+  /** Merge a declarative tool/prompt policy patch (canvas-bound, snapshotted). */
+  setPolicy(
+    patch: { tools?: Partial<PmxAxPolicy['tools']>; prompt?: Partial<PmxAxPolicy['prompt']> },
+    _options: { source?: PmxAxSource } = {},
+  ): PmxAxPolicy {
+    const oldAxState = this.getAxState();
+    const merged = normalizeAxPolicy({
+      tools: { ...oldAxState.policy.tools, ...(patch.tools ?? {}) },
+      prompt: { ...oldAxState.policy.prompt, ...(patch.prompt ?? {}) },
+    });
+    this.applyAxState({ ...oldAxState, policy: merged });
+    const applied = this.getAxState();
+    this.scheduleSave();
+    this.notifyChange('ax');
+    this.recordMutation({
+      operationType: 'setPolicy',
+      description: 'Updated AX policy',
+      forward: this.suppressed(() => { this.applyAxState(applied); this.scheduleSave(); this.notifyChange('ax'); }),
+      inverse: this.suppressed(() => { this.applyAxState(oldAxState); this.scheduleSave(); this.notifyChange('ax'); }),
+    });
+    return applied.policy;
+  }
+
   setHostCapability(input: unknown, _options: { source?: PmxAxSource } = {}): PmxAxHostCapability {
     const cap = normalizeAxHostCapability(
       isRecord(input)
@@ -2012,6 +2178,15 @@ class CanvasStateManager {
     return this._db ? loadAxSteeringFromDB(this._db, q) : [];
   }
 
+  /**
+   * Undelivered steering for a consumer (Phase 4 delivery). Excludes messages
+   * whose source equals the consumer to prevent delivery loops (e.g. Copilot
+   * should not be handed back steering it originated).
+   */
+  getPendingSteering(options: { consumer?: string; limit?: number } = {}): PmxAxSteeringMessage[] {
+    return this._db ? loadPendingAxSteeringFromDB(this._db, options) : [];
+  }
+
   getAxTimelineSummary(): PmxAxTimelineSummary {
     return this._db
       ? loadAxTimelineSummaryFromDB(this._db)