pmx-canvas 0.1.29 → 0.1.30

package/dist/types/server/index.d.ts

@@ -1,7 +1,8 @@
 import { EventEmitter } from 'node:events';
 import { canvasState } from './canvas-state.js';
 import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
-import type { PmxAxApprovalGate, PmxAxContext, PmxAxEvent, PmxAxEvidence, PmxAxEvidenceKind, PmxAxFocusState, PmxAxHostCapability, PmxAxReviewAnchorType, PmxAxReviewAnnotation, PmxAxReviewKind, PmxAxReviewRegion, PmxAxReviewSeverity, PmxAxReviewStatus, PmxAxSource, PmxAxState, PmxAxSteeringMessage, PmxAxWorkItem, PmxAxWorkItemStatus } from './ax-state.js';
+import { type AxInteractionInput, type AxInteractionPublicResult } from './ax-interaction.js';
+import type { PmxAxApprovalGate, PmxAxCommandDescriptor, PmxAxContext, PmxAxElicitation, PmxAxEvent, PmxAxEvidence, PmxAxEvidenceKind, PmxAxFocusState, PmxAxHostCapability, PmxAxMode, PmxAxModeRequest, PmxAxPolicy, PmxAxReviewAnchorType, PmxAxReviewAnnotation, PmxAxReviewKind, PmxAxReviewRegion, PmxAxReviewSeverity, PmxAxReviewStatus, PmxAxSource, PmxAxState, PmxAxSteeringMessage, PmxAxWorkItem, PmxAxWorkItemStatus } from './ax-state.js';
 import type { AxTimelineQuery } from './canvas-db.js';
 import { searchNodes } from './spatial-analysis.js';
 import { diffLayouts } from './mutation-history.js';
@@ -140,6 +141,19 @@ export declare class PmxCanvas extends EventEmitter {
         source?: PmxAxSource;
     }): PmxAxSteeringMessage;
     markSteeringDelivered(id: string): boolean;
+    /** Undelivered steering for a consumer (loop-safe; excludes consumer-originated). */
+    getPendingSteering(options?: {
+        consumer?: string;
+        limit?: number;
+    }): PmxAxSteeringMessage[];
+    /**
+     * Submit a node-originated AX interaction (plan-004 Phase 1). Validates the
+     * envelope + node capabilities, maps the interaction onto the matching AX
+     * operation, and emits the outcome + state SSE events.
+     */
+    submitAxInteraction(input: AxInteractionInput, options?: {
+        source?: PmxAxSource;
+    }): AxInteractionPublicResult;
     getAxTimeline(query?: AxTimelineQuery): ReturnType<typeof canvasState.getAxTimeline>;
     listWorkItems(): PmxAxWorkItem[];
     addWorkItem(input: {
@@ -206,6 +220,40 @@ export declare class PmxCanvas extends EventEmitter {
     reportHostCapability(input: unknown, options?: {
         source?: PmxAxSource;
     }): PmxAxHostCapability;
+    listElicitations(): PmxAxElicitation[];
+    requestElicitation(input: {
+        prompt: string;
+        fields?: string[];
+        nodeIds?: string[];
+    }, options?: {
+        source?: PmxAxSource;
+    }): PmxAxElicitation;
+    respondElicitation(id: string, response: Record<string, unknown>, options?: {
+        source?: PmxAxSource;
+    }): PmxAxElicitation | null;
+    listModeRequests(): PmxAxModeRequest[];
+    requestMode(input: {
+        mode: PmxAxMode;
+        reason?: string | null;
+        nodeIds?: string[];
+    }, options?: {
+        source?: PmxAxSource;
+    }): PmxAxModeRequest;
+    resolveModeRequest(id: string, decision: 'approved' | 'rejected', options?: {
+        resolution?: string;
+        source?: PmxAxSource;
+    }): PmxAxModeRequest | null;
+    getCommandRegistry(): PmxAxCommandDescriptor[];
+    invokeCommand(name: string, args?: Record<string, unknown> | null, options?: {
+        source?: PmxAxSource;
+    }): PmxAxEvent | null;
+    getPolicy(): PmxAxPolicy;
+    setPolicy(patch: {
+        tools?: Partial<PmxAxPolicy['tools']>;
+        prompt?: Partial<PmxAxPolicy['prompt']>;
+    }, options?: {
+        source?: PmxAxSource;
+    }): PmxAxPolicy;
     fitView(options?: {
         width?: number;
         height?: number;
@@ -439,5 +487,5 @@ export type { WebArtifactBuildInput, WebArtifactBuildOutput, WebArtifactCanvasBu
 export type { GraphNodeInput, JsonRenderNodeInput, JsonRenderSpec } from '../json-render/server.js';
 export type { HtmlPrimitiveKind, HtmlPrimitiveDescriptor, HtmlPrimitiveInput, HtmlPrimitiveBuildResult } from './html-primitives.js';
 export { traceManager } from './trace-manager.js';
-export type { PmxAxApprovalGate, PmxAxApprovalStatus, PmxAxContext, PmxAxEvent, PmxAxEventKind, PmxAxEvidence, PmxAxEvidenceKind, PmxAxFocusState, PmxAxHostCapability, PmxAxReviewAnchorType, PmxAxReviewAnnotation, PmxAxReviewKind, PmxAxReviewRegion, PmxAxReviewSeverity, PmxAxReviewStatus, PmxAxSource, PmxAxState, PmxAxSteeringMessage, PmxAxTimelineSummary, PmxAxWorkItem, PmxAxWorkItemStatus, } from './ax-state.js';
+export type { PmxAxApprovalGate, PmxAxApprovalStatus, PmxAxCommandDescriptor, PmxAxContext, PmxAxEvent, PmxAxElicitation, PmxAxElicitationStatus, PmxAxEventKind, PmxAxEvidence, PmxAxEvidenceKind, PmxAxFocusState, PmxAxHostCapability, PmxAxMode, PmxAxModeRequest, PmxAxModeRequestStatus, PmxAxPolicy, PmxAxReviewAnchorType, PmxAxReviewAnnotation, PmxAxReviewKind, PmxAxReviewRegion, PmxAxReviewSeverity, PmxAxReviewStatus, PmxAxSource, PmxAxState, PmxAxSteeringMessage, PmxAxTimelineSummary, PmxAxWorkItem, PmxAxWorkItemStatus, } from './ax-state.js';
 export type { AxTimelineQuery } from './canvas-db.js';

package/dist/types/server/mutation-history.d.ts

@@ -12,7 +12,7 @@
  * - _replaying flag prevents undo/redo from recording new entries
  */
 import type { CanvasNodeState, CanvasEdge } from './canvas-state.js';
-export type MutationOp = 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'arrange' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'addWorkItem' | 'updateWorkItem' | 'requestApproval' | 'resolveApproval' | 'addReviewAnnotation' | 'updateReviewAnnotation' | 'batch' | 'viewport' | 'groupNodes' | 'ungroupNodes';
+export type MutationOp = 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'arrange' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'addWorkItem' | 'updateWorkItem' | 'requestApproval' | 'resolveApproval' | 'addReviewAnnotation' | 'updateReviewAnnotation' | 'requestElicitation' | 'respondElicitation' | 'requestMode' | 'resolveModeRequest' | 'setPolicy' | 'batch' | 'viewport' | 'groupNodes' | 'ungroupNodes';
 export interface MutationEntry {
     id: string;
     timestamp: string;

package/dist/types/server/placement.d.ts

@@ -1,6 +1,6 @@
 import { type CanvasPlacementRect } from '../shared/placement.js';
 export { findOpenCanvasPosition, type CanvasPlacementRect } from '../shared/placement.js';
-export declare const GROUP_PAD = 40;
+export declare const GROUP_PAD = 56;
 export declare const GROUP_TITLEBAR_HEIGHT = 32;
 /**
  * Compute bounding box for a group that should contain the given child rects.

package/dist/types/shared/surface.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cross-cutting helpers for node "surfaces" — the standalone documents served at
+ * /api/canvas/surface/:nodeId. Shared by the server route, the server-side node
+ * serialization, and the client so the openability rule lives in exactly one
+ * place. The authoritative dispatch (serve vs redirect) lives in the server's
+ * handleNodeSurface; this predicate mirrors which node types it can open.
+ */
+/**
+ * Whether a node has an "Open as site" surface. Coarse by design (presence of the
+ * minimal field) — the route itself decides what to actually serve.
+ */
+export declare function canOpenNodeAsSurface(type: string, data: Record<string, unknown>): boolean;
+/**
+ * CSP sandbox tokens for a hosted ext-app surface, used both as the in-canvas
+ * iframe `sandbox` attribute and as the `Content-Security-Policy: sandbox` value
+ * when the surface route serves an ext-app standalone. All tokens are in the
+ * server's safe-sandbox allowlist; notably NOT allow-same-origin.
+ */
+export declare const DEFAULT_EXT_APP_SANDBOX = "allow-scripts allow-popups allow-popups-to-escape-sandbox";

package/docs/cli.md

@@ -157,6 +157,36 @@ pmx-canvas ax host report --host copilot --canvas --session-messaging
 pmx-canvas ax host status
 ```
 
+### AX interactions, delivery, elicitation, mode, commands & policy
+
+```bash
+# Node interaction — one capability-gated envelope (server re-validates + scopes)
+pmx-canvas ax interaction --type ax.work.create --node node-1 --payload '{"title":"Wire auth"}'
+
+# Delivery — claim pending steering for a consumer (loop-safe), then acknowledge
+pmx-canvas ax delivery list --consumer copilot --limit 20
+pmx-canvas ax delivery mark <steering-id>
+
+# Elicitation — request structured human input, then answer
+pmx-canvas ax elicitation request --prompt "Who owns this migration?" --fields owner
+pmx-canvas ax elicitation respond <id> --response '{"owner":"alice"}'
+pmx-canvas ax elicitation list
+
+# Mode — request a plan/execute/autonomous transition, then resolve
+pmx-canvas ax mode request --mode execute --reason "plan approved"
+pmx-canvas ax mode resolve <id> --decision approved
+pmx-canvas ax mode list
+
+# Commands — list the registry, invoke a registry-gated command
+pmx-canvas ax command list
+pmx-canvas ax command invoke pmx.plan
+pmx-canvas ax command invoke pmx.promote-context --args '{"nodeIds":["n1"]}'
+
+# Policy — read / patch the tool/prompt policy (stored by PMX, enforced by adapters)
+pmx-canvas ax policy get
+pmx-canvas ax policy set --excluded-tools shell,write --mode concise
+```
+
 ## Copilot adapter
 
 Install the bundled GitHub Copilot extension adapter into a repo. The adapter

package/docs/http-api.md

@@ -181,6 +181,61 @@ Validation: `/ax/event` requires a valid `kind` + `summary` (400 otherwise);
 and `PATCH /ax/review/:id` return 404 for unknown IDs; approval resolve returns
 404 if the gate is missing or already resolved.
 
+## AX interactions, delivery, elicitation, mode, commands & policy
+
+Node interactions are one normalized, capability-gated envelope that maps onto an
+AX operation. The server re-validates every interaction against the source node's
+effective capabilities and clamps sandboxed surfaces (`html-node`, `mcp-app`,
+`json-render`) to their own node.
+
+```bash
+# Node interaction — one envelope, validated + mapped to the matching AX op
+curl -X POST http://localhost:4313/api/canvas/ax/interaction \
+  -H "Content-Type: application/json" \
+  -d '{"type":"ax.work.create","sourceNodeId":"node-1","payload":{"title":"Wire auth"}}'
+
+# Delivery — claim pending steering for a consumer (loop-safe), then mark delivered
+curl "http://localhost:4313/api/canvas/ax/delivery/pending?consumer=copilot&limit=20"
+curl -X POST http://localhost:4313/api/canvas/ax/delivery/<steering-id>/mark \
+  -H "Content-Type: application/json" \
+  -d '{"consumer":"copilot"}'
+
+# Elicitation — request structured human input, then respond
+curl -X POST http://localhost:4313/api/canvas/ax/elicitation \
+  -H "Content-Type: application/json" \
+  -d '{"prompt":"Who owns this migration?","fields":["owner"],"source":"api"}'
+curl -X POST http://localhost:4313/api/canvas/ax/elicitation/<id>/respond \
+  -H "Content-Type: application/json" \
+  -d '{"response":{"owner":"alice"}}'
+curl http://localhost:4313/api/canvas/ax/elicitation
+
+# Mode — request a plan/execute/autonomous transition, then resolve
+curl -X POST http://localhost:4313/api/canvas/ax/mode \
+  -H "Content-Type: application/json" \
+  -d '{"mode":"plan","reason":"scope the change first","source":"api"}'
+curl -X POST http://localhost:4313/api/canvas/ax/mode/<id>/resolve \
+  -H "Content-Type: application/json" \
+  -d '{"decision":"approved"}'
+curl http://localhost:4313/api/canvas/ax/mode
+
+# Commands — list the registry, invoke a command (records a `command` agent-event)
+curl http://localhost:4313/api/canvas/ax/command
+curl -X POST http://localhost:4313/api/canvas/ax/command \
+  -H "Content-Type: application/json" \
+  -d '{"name":"pmx.plan","args":{"note":"draft a plan"},"source":"api"}'
+
+# Policy — read / patch the canvas-bound tool/prompt policy (patches merge)
+curl http://localhost:4313/api/canvas/ax/policy
+curl -X POST http://localhost:4313/api/canvas/ax/policy \
+  -H "Content-Type: application/json" \
+  -d '{"tools":{"excluded":["shell"]},"prompt":{"mode":"concise"},"source":"api"}'
+```
+
+Validation: `/ax/interaction` returns `{ ok: false, code }` (403 `ax-disabled` /
+`not-allowed`, 400 `invalid-payload` / `unknown-command`, 404 `unknown-node`);
+`/ax/command` rejects an unknown command name with 400; `/ax/elicitation/:id/respond`
+and `/ax/mode/:id/resolve` return 404 for unknown IDs.
+
 ## Diagrams (Excalidraw preset)
 
 ```bash

package/docs/mcp.md

@@ -1,6 +1,6 @@
 # MCP reference
 
-PMX Canvas ships an MCP stdio server with **56 tools** + **12 core resources**,
+PMX Canvas ships an MCP stdio server with **65 tools** + **14 core resources**,
 plus per-skill resources at `canvas://skills/<name>`. The server emits
 `notifications/resources/updated` when canvas state changes — humans pin
 nodes in the browser, agents are notified immediately.
@@ -65,6 +65,15 @@ searchable and readable in pinned/spatial context.
 | `canvas_add_evidence` | Record an `evidence-item` on the timeline (logs/tool-result/screenshot/file/diff/test-output) |
 | `canvas_add_review_annotation` | Add a canvas-bound `review-annotation` (comment/finding) anchored to a node, file, or region |
 | `canvas_report_host_capability` | Report a host/session `host-capability` for diagnostics |
+| `canvas_ax_interaction` | Submit one capability-gated AX interaction envelope (`{ type, sourceNodeId, payload }`) that maps onto an AX operation; the server re-validates and clamps sandboxed surfaces to their own node |
+| `canvas_claim_ax_delivery` | Claim undelivered steering messages for an adapterless consumer (loop-safe — never returns steering the consumer originated) |
+| `canvas_mark_ax_delivery` | Mark a steering message delivered for a consumer |
+| `canvas_request_elicitation` | Request structured human input via a canvas-bound `elicitation` (pending) |
+| `canvas_respond_elicitation` | Respond to / resolve a pending elicitation |
+| `canvas_request_mode` | Request a workflow `mode-request` transition (plan/execute/autonomous) |
+| `canvas_resolve_mode` | Resolve a pending mode request |
+| `canvas_invoke_command` | Invoke a registry command (`pmx.plan`, `pmx.execute`, `pmx.promote-context`, `pmx.summarize`, `pmx.review`); records a `command` agent-event, unknown names rejected |
+| `canvas_set_ax_policy` | Patch the canvas-bound tool/prompt policy (`tools.allowed\|excluded\|approvalRequired`, `prompt.systemAppend\|mode`); patches merge and are normalized |
 | `canvas_pin_nodes` | Pin nodes to include in agent context |
 | `canvas_clear` | Clear all nodes and edges |
 | `canvas_snapshot` | Save current canvas as a named snapshot |
@@ -96,8 +105,10 @@ Individual bundled skills are also readable at `canvas://skills/<name>`.
 | `canvas://pinned-context` | Content of pinned nodes + nearby unpinned neighbors |
 | `canvas://ax` | PMX AX state: focus, work items, approval gates, review annotations |
 | `canvas://ax-context` | Agent-readable pinned and focused AX context, plus timeline summary and host capability |
-| `canvas://ax-work` | Canvas-bound AX work: work items, approval gates, review annotations |
+| `canvas://ax-work` | Canvas-bound AX work: work items, approval gates, review annotations, elicitations, mode requests, and tool/prompt policy |
 | `canvas://ax-timeline` | Bounded AX timeline: recent agent-events, evidence, and steering messages |
+| `canvas://ax-pending-steering` | Undelivered steering an adapterless MCP client can claim, act on, and mark delivered |
+| `canvas://ax-delivery` | Steering delivery state (delivered flag) for diagnostics |
 | `canvas://schema` | Running-server create schemas and json-render catalog metadata |
 | `canvas://layout` | Full canvas state (all nodes, edges, viewport) |
 | `canvas://summary` | Compact overview: counts, pinned titles, viewport |
@@ -106,6 +117,33 @@ Individual bundled skills are also readable at `canvas://skills/<name>`.
 | `canvas://code-graph` | Auto-detected file dependency graph (JS/TS, Python, Go, Rust) |
 | `canvas://skills` | Index of bundled agent skills + per-skill content at `canvas://skills/<name>` |
 
+## Node interactions (capability-gated)
+
+Eligible nodes emit one normalized, validated interaction envelope
+(`{ type, sourceNodeId, payload, sourceSurface }`) via `canvas_ax_interaction`
+(HTTP `POST /api/canvas/ax/interaction`) that maps onto an AX operation — work
+item, evidence, approval, review, focus, steering, event, elicitation, mode, or
+command. The server is the single trust boundary and re-validates every
+interaction against the node's effective capabilities.
+
+- **Capabilities:** each node type has a default capability set (a ceiling). A
+  node may opt in or narrow via `data.axCapabilities` (`{ enabled, allowed }`),
+  clamped to the ceiling — a node can never escalate beyond its type's ceiling.
+  `html` / `html-primitive`, `mcp-app`, and internal `prompt` / `response` are
+  disabled by default.
+- **Scoping:** sandboxed/opaque-origin iframe surfaces (`html-node`, `mcp-app`,
+  `json-render`) are clamped to their own node — caller-supplied `nodeIds` are
+  forced to the source node. Trusted surfaces (`native-node`, `adapter`) may
+  target explicit nodeIds.
+- **Transports:** native node controls call the endpoint directly; sandboxed
+  `html` / `mcp-app` nodes call `window.PMX_AX.emit(type, payload)`; the
+  `json-render` / `graph` viewer forwards a spec action named after an AX type
+  (e.g. `on.press → { action: "ax.work.create", params }`). All postMessage
+  transports are nonce-validated by the parent canvas before submission.
+- **Commands:** `canvas_invoke_command` runs a registry command (`pmx.plan`,
+  `pmx.execute`, `pmx.promote-context`, `pmx.summarize`, `pmx.review`); unknown
+  names are rejected and a successful call records a `command` agent-event.
+
 ## Change notifications
 
 The MCP server emits `notifications/resources/updated` whenever canvas state

package/docs/node-types.md

@@ -138,6 +138,32 @@ canvas_add_json_render_node({
 `outline`. Older saved specs using `label` or status variants such as
 `success`/`warning` are normalized during validation.
 
+Elements may carry an `on` map (`on.press`, `on.change`, …) binding events to
+actions (`{ action, params }`) — built-in actions (`setState`, `pushState`, …) or
+host-provided handlers. PMX wires AX handlers named after interaction types, so a
+spec action named `ax.*` becomes a capability-gated AX interaction:
+
+```ts
+canvas_add_json_render_node({
+  title: 'Approve plan',
+  spec: {
+    root: 'btn',
+    elements: {
+      btn: {
+        type: 'Button',
+        props: { label: 'Track as work', variant: 'primary' },
+        on: { press: { action: 'ax.work.create', params: { title: 'Ship the plan' } } },
+      },
+    },
+  },
+});
+```
+
+The viewer forwards the emit to the parent canvas, which validates it (iframe
+source + per-viewer nonce + node id) and submits it server-side; `json-render` /
+`graph` viewers are sandboxed surfaces, so caller-supplied `nodeIds` are clamped
+to the node's own id. See the [MCP reference](mcp.md#node-interactions-capability-gated).
+
 Use `canvas_describe_schema` / `canvas_validate_spec` to introspect the
 component catalog before building a spec.