pmx-canvas 0.1.35 → 0.1.36

package/dist/types/client/nodes/ExtAppFrame.d.ts

@@ -16,6 +16,8 @@ export declare function resolveExtAppDisplayModeRequest(requestedMode: DisplayMo
 };
 export declare function sendExtAppBootstrapState(bridge: ExtAppBridgeNotifications, toolInput: Record<string, unknown>, toolResult: CallToolResult | undefined): Promise<void>;
 export declare function resolveExtAppSandbox(value: unknown): string;
+export declare function buildExtAppAxBridgeScript(axToken: string, nodeId: string): string;
+export declare function injectExtAppAxBridgeScript(html: string, axBridgeScript: string): string;
 export declare function resolveExtAppContainerDimensions(target: ExtAppHostDimensionsTarget | null | undefined, fallback: {
     width: number;
     height: number;

package/dist/types/mcp/canvas-access.d.ts

@@ -40,6 +40,11 @@ type ListModeRequestsResult = ReturnType<PmxCanvas['listModeRequests']>;
 type RequestModeInput = Parameters<PmxCanvas['requestMode']>[0];
 type RequestModeResult = ReturnType<PmxCanvas['requestMode']>;
 type ResolveModeRequestResult = ReturnType<PmxCanvas['resolveModeRequest']>;
+type IngestActivityInput = Parameters<PmxCanvas['ingestActivity']>[0];
+type IngestActivityResult = ReturnType<PmxCanvas['ingestActivity']>;
+type AwaitApprovalResult = Awaited<ReturnType<PmxCanvas['awaitApproval']>>;
+type AwaitElicitationResult = Awaited<ReturnType<PmxCanvas['awaitElicitation']>>;
+type AwaitModeResult = Awaited<ReturnType<PmxCanvas['awaitMode']>>;
 type GetCommandRegistryResult = ReturnType<PmxCanvas['getCommandRegistry']>;
 type InvokeCommandResult = ReturnType<PmxCanvas['invokeCommand']>;
 type GetPolicyResult = ReturnType<PmxCanvas['getPolicy']>;
@@ -115,7 +120,9 @@ export interface CanvasAccess {
     }): Promise<FocusNodeResult>;
     fitView(options?: FitViewOptions): Promise<FitViewResult>;
     getAxState(): Promise<AxStateResult>;
-    getAxContext(): Promise<AxContextResult>;
+    getAxContext(options?: {
+        consumer?: string;
+    }): Promise<AxContextResult>;
     setAxFocus(nodeIds: string[], options?: {
         source?: PmxAxSource;
     }): Promise<SetAxFocusResult>;
@@ -178,6 +185,18 @@ export interface CanvasAccess {
         resolution?: string;
         source?: PmxAxSource;
     }): Promise<ResolveModeRequestResult>;
+    ingestActivity(input: IngestActivityInput, options?: {
+        source?: PmxAxSource;
+    }): Promise<IngestActivityResult>;
+    awaitApproval(id: string, options?: {
+        timeoutMs?: number;
+    }): Promise<AwaitApprovalResult>;
+    awaitElicitation(id: string, options?: {
+        timeoutMs?: number;
+    }): Promise<AwaitElicitationResult>;
+    awaitMode(id: string, options?: {
+        timeoutMs?: number;
+    }): Promise<AwaitModeResult>;
     getCommandRegistry(): Promise<GetCommandRegistryResult>;
     invokeCommand(name: string, args?: Record<string, unknown> | null, options?: {
         source?: PmxAxSource;

package/dist/types/server/ax-context.d.ts

@@ -23,4 +23,4 @@ export interface PmxAxSurfaceSnapshot {
  */
 export declare function buildCanvasAxSurfaceSnapshot(): PmxAxSurfaceSnapshot;
 export declare function buildCanvasAxPinnedContext(): PmxAxPinnedContext;
-export declare function buildCanvasAxContext(): PmxAxContext;
+export declare function buildCanvasAxContext(consumer?: string): PmxAxContext;

package/dist/types/server/ax-state.d.ts

@@ -135,6 +135,18 @@ export interface PmxAxPinnedContext {
 export interface PmxAxFocusContext extends PmxAxFocusState {
     nodes: AgentContextNode[];
 }
+export interface PendingAxActivityItem {
+    kind: 'work-item' | 'approval-gate' | 'elicitation' | 'mode-request';
+    id: string;
+    title: string;
+    status: string;
+    nodeIds: string[];
+    source: PmxAxSource | null;
+}
+export interface PmxAxDeliveryContext {
+    pendingSteering: PmxAxSteeringMessage[];
+    pendingActivity: PendingAxActivityItem[];
+}
 export interface PmxAxContext {
     version: 1;
     generatedAt: string;
@@ -142,6 +154,7 @@ export interface PmxAxContext {
         nodeCount: number;
         edgeCount: number;
     };
+    delivery: PmxAxDeliveryContext;
     pinned: PmxAxPinnedContext;
     focus: PmxAxFocusContext;
     workItems: PmxAxWorkItem[];
@@ -153,6 +166,20 @@ export interface PmxAxContext {
     timeline: PmxAxTimelineSummary;
     host: PmxAxHostCapability | null;
 }
+/**
+ * Open, agent-actionable canvas-bound AX items (open work items + pending approval
+ * gates / elicitations / mode requests). Unlike steering (a directive routed through
+ * the claim/ack delivery queue), these are STATE the human curates in the browser —
+ * they fire `ax-state-changed` (so resource-subscribers are pushed canvas://ax-work),
+ * but an adapterless client that only POLLS the delivery surface never saw them.
+ * Optionally excludes items the consumer itself originated (loop prevention),
+ * mirroring getPendingSteering. Shared by the MCP delivery surface and the HTTP
+ * context lead block so the digest never drifts between the two.
+ */
+export declare function buildPendingAxActivity(state: PmxAxState, consumer?: string): PendingAxActivityItem[];
+export type PmxAxActivityKind = 'tool-start' | 'tool-result' | 'failure' | 'error' | 'session-start' | 'session-end' | 'command' | 'note';
+export declare function isAxActivityKind(value: unknown): value is PmxAxActivityKind;
+export declare function mapAxActivityKindToEventKind(kind: PmxAxActivityKind): PmxAxEventKind;
 export interface PmxAxCommandDescriptor {
     name: string;
     description: string;
@@ -264,6 +291,7 @@ export declare function createAxSteeringMessage(message: string, source: PmxAxSo
 export declare function normalizeAxState(input: unknown, validNodeIds?: Set<string>): PmxAxState;
 export declare function buildAxContext(input: {
     layout: CanvasLayout;
+    delivery: PmxAxDeliveryContext;
     pinned: PmxAxPinnedContext;
     focus: PmxAxFocusState;
     focusNodes: AgentContextNode[];

package/dist/types/server/ax-wait.d.ts

@@ -0,0 +1,23 @@
+/** Hard ceiling on a single blocking wait, regardless of the requested timeout. */
+export declare const AX_WAIT_MAX_MS = 120000;
+export interface AxWaitResult<T> {
+    /** Latest value, or null if the item does not exist / vanished mid-wait. */
+    value: T | null;
+    /** True only when the item still exists and is still pending after the wait. */
+    pending: boolean;
+}
+/**
+ * Block until a canvas-bound AX item resolves (its status leaves `pending`), the
+ * timeout elapses, or the request aborts — the server side of report primitive D
+ * ("gates that actually gate"). Resolves immediately when the item is already
+ * resolved, missing, or `timeoutMs <= 0` (a plain single read). Subscribes to the
+ * `ax` change channel and always disposes the listener + timer.
+ */
+export declare function waitForAxResolution<T extends {
+    status: string;
+}>(opts: {
+    read: () => T | null;
+    isResolved: (value: T) => boolean;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<AxWaitResult<T>>;

package/dist/types/server/canvas-state.d.ts

@@ -10,7 +10,7 @@
  * Legacy `.pmx-canvas/state.json` is auto-migrated on first boot.
  */
 import { type PersistedCanvasState, type CanvasTheme, type AxTimelineQuery } from './canvas-db.js';
-import { type PmxAxElicitation, type PmxAxModeRequest, type PmxAxMode, type PmxAxCommandDescriptor, type PmxAxPolicy, type PmxAxFocusState, type PmxAxSource, type PmxAxState, type PmxAxWorkItem, type PmxAxWorkItemStatus, type PmxAxApprovalGate, type PmxAxReviewAnnotation, type PmxAxReviewKind, type PmxAxReviewSeverity, type PmxAxReviewStatus, type PmxAxReviewAnchorType, type PmxAxReviewRegion, type PmxAxEvent, type PmxAxEventKind, type PmxAxEvidence, type PmxAxEvidenceKind, type PmxAxSteeringMessage, type PmxAxHostCapability, type PmxAxTimelineSummary } from './ax-state.js';
+import { type PmxAxActivityKind, type PmxAxElicitation, type PmxAxModeRequest, type PmxAxMode, type PmxAxCommandDescriptor, type PmxAxPolicy, type PmxAxFocusState, type PmxAxSource, type PmxAxState, type PmxAxWorkItem, type PmxAxWorkItemStatus, type PmxAxApprovalGate, type PmxAxReviewAnnotation, type PmxAxReviewKind, type PmxAxReviewSeverity, type PmxAxReviewStatus, type PmxAxReviewAnchorType, type PmxAxReviewRegion, type PmxAxEvent, type PmxAxEventKind, type PmxAxEvidence, type PmxAxEvidenceKind, type PmxAxSteeringMessage, type PmxAxHostCapability, type PmxAxTimelineSummary } from './ax-state.js';
 export declare const PMX_CANVAS_DIR = ".pmx-canvas";
 export interface PersistedBlobRef {
     __pmxCanvasBlob: 'v1';
@@ -146,8 +146,13 @@ declare class CanvasStateManager {
     private _axHostCapability;
     private _workspaceRoot;
     private _changeListeners;
-    /** Register a listener for state changes. Used by MCP server to emit resource notifications. */
-    onChange(cb: (type: CanvasChangeType) => void): void;
+    /**
+     * Register a listener for state changes. Used by MCP server to emit resource
+     * notifications and by the blocking-wait endpoints to await an AX transition.
+     * Returns a disposer that unregisters the listener (callers that don't need it
+     * — e.g. the long-lived MCP subscription — may ignore the return value).
+     */
+    onChange(cb: (type: CanvasChangeType) => void): () => void;
     private notifyChange;
     private _mutationRecorder;
     private _suppressRecordingDepth;
@@ -346,6 +351,9 @@ declare class CanvasStateManager {
         resolution?: string;
         source?: PmxAxSource;
     }): PmxAxModeRequest | null;
+    getApproval(id: string): PmxAxApprovalGate | null;
+    getElicitation(id: string): PmxAxElicitation | null;
+    getModeRequest(id: string): PmxAxModeRequest | null;
     getCommandRegistry(): PmxAxCommandDescriptor[];
     /** Invoke a registry-gated PMX command intent — records a timeline event (no execution). */
     invokeCommand(name: string, args?: Record<string, unknown> | null, options?: {
@@ -385,6 +393,50 @@ declare class CanvasStateManager {
         source?: PmxAxSource;
     }): PmxAxSteeringMessage;
     markSteeringDelivered(id: string): boolean;
+    /**
+     * Ingest a normalized agent activity (a tool/session event a harness forwards)
+     * and apply kind-driven board reactions, so the agent's real work flows back into
+     * the board without it remembering to push each item (report primitive A — makes
+     * AX bidirectional). Always records a timeline event; then, unless the caller
+     * overrides/suppresses via `reactions`, applies defaults by kind/outcome:
+     *   • failure | error | outcome==='failure' → work item (blocked) + review
+     *     (finding/error, anchored to a valid nodeId else the `ref` file) + evidence (logs)
+     *   • tool-result + outcome==='success'      → evidence (tool-result)
+     *   • everything else (tool-start, session-*, command, note) → event only
+     * A reaction value of `false` suppresses it; an object overrides its fields/forces it on.
+     */
+    ingestActivity(input: {
+        kind: PmxAxActivityKind;
+        title: string;
+        summary?: string | null;
+        outcome?: 'success' | 'failure';
+        ref?: string | null;
+        nodeIds?: string[];
+        data?: Record<string, unknown> | null;
+        reactions?: {
+            workItem?: false | {
+                status?: PmxAxWorkItemStatus;
+                detail?: string | null;
+            };
+            evidence?: false | {
+                kind?: PmxAxEvidenceKind;
+                body?: string | null;
+            };
+            review?: false | {
+                severity?: PmxAxReviewSeverity;
+                kind?: PmxAxReviewKind;
+                anchorType?: PmxAxReviewAnchorType;
+                nodeId?: string | null;
+            };
+        };
+    }, options?: {
+        source?: PmxAxSource;
+    }): {
+        event: PmxAxEvent;
+        workItem: PmxAxWorkItem | null;
+        evidence: PmxAxEvidence | null;
+        review: PmxAxReviewAnnotation | null;
+    };
     getAxEvents(q?: AxTimelineQuery): PmxAxEvent[];
     getAxEvidence(q?: AxTimelineQuery): PmxAxEvidence[];
     getAxSteering(q?: AxTimelineQuery & {

package/dist/types/server/html-surface.d.ts

@@ -27,6 +27,13 @@ export declare function normalizeSurfaceTheme(value: string | null | undefined):
  * injected when the node's AX capabilities are enabled (opt-in for `html`), and
  * the server re-validates every interaction — so this is a convenience surface,
  * not a trust boundary.
+ *
+ * `emit` returns a Promise that resolves with the interaction result once the
+ * parent acks it (report #55 — built-in confirmation so a click no longer looks
+ * like "nothing happened"). Authors can also `window.PMX_AX.on('ack', cb)` or
+ * listen for the `pmx-ax-ack` CustomEvent. Resolves with an `ax-ack-timeout`
+ * result after 10s if no ack arrives (e.g. an older parent), so `await emit()`
+ * never hangs.
  */
 export declare function buildAxBridge(axToken: string, nodeId: string): string;
 /**

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

@@ -2,7 +2,7 @@ import { EventEmitter } from 'node:events';
 import { canvasState } from './canvas-state.js';
 import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-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 { PmxAxActivityKind, 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';
@@ -134,7 +134,9 @@ export declare class PmxCanvas extends EventEmitter {
         panned: boolean;
     } | null;
     getAxState(): PmxAxState;
-    getAxContext(): PmxAxContext;
+    getAxContext(options?: {
+        consumer?: string;
+    }): PmxAxContext;
     setAxFocus(nodeIds: string[], options?: {
         source?: PmxAxSource;
     }): PmxAxFocusState;
@@ -253,6 +255,62 @@ export declare class PmxCanvas extends EventEmitter {
         resolution?: string;
         source?: PmxAxSource;
     }): PmxAxModeRequest | null;
+    ingestActivity(input: {
+        kind: PmxAxActivityKind;
+        title: string;
+        summary?: string | null;
+        outcome?: 'success' | 'failure';
+        ref?: string | null;
+        nodeIds?: string[];
+        data?: Record<string, unknown> | null;
+        reactions?: {
+            workItem?: false | {
+                status?: PmxAxWorkItemStatus;
+                detail?: string | null;
+            };
+            evidence?: false | {
+                kind?: PmxAxEvidenceKind;
+                body?: string | null;
+            };
+            review?: false | {
+                severity?: PmxAxReviewSeverity;
+                kind?: PmxAxReviewKind;
+                anchorType?: PmxAxReviewAnchorType;
+                nodeId?: string | null;
+            };
+        };
+    }, options?: {
+        source?: PmxAxSource;
+    }): {
+        event: PmxAxEvent;
+        workItem: PmxAxWorkItem | null;
+        evidence: PmxAxEvidence | null;
+        review: PmxAxReviewAnnotation | null;
+    };
+    getApproval(id: string): PmxAxApprovalGate | null;
+    getElicitation(id: string): PmxAxElicitation | null;
+    getModeRequest(id: string): PmxAxModeRequest | null;
+    awaitApproval(id: string, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        approvalGate: PmxAxApprovalGate | null;
+        pending: boolean;
+    }>;
+    awaitElicitation(id: string, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        elicitation: PmxAxElicitation | null;
+        pending: boolean;
+    }>;
+    awaitMode(id: string, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        modeRequest: PmxAxModeRequest | null;
+        pending: boolean;
+    }>;
     getCommandRegistry(): PmxAxCommandDescriptor[];
     invokeCommand(name: string, args?: Record<string, unknown> | null, options?: {
         source?: PmxAxSource;

package/docs/ax-host-adapter-contract.md

@@ -0,0 +1,65 @@
+# AX host-adapter contract
+
+PMX Canvas owns the **AX data layer** — work items, approval gates, steering,
+evidence, review annotations, elicitations, mode requests, the timeline, host
+capabilities, and the tool/prompt policy — over HTTP and MCP. What makes AX
+*interactive* on a given coding harness (GitHub Copilot, Codex, Claude Code, …) is
+a thin **adapter** that wires PMX's neutral surfaces to that harness's lifecycle.
+
+"Agnostic" means a documented interface plus PMX-side behavior plus one small
+reference adapter per harness — not zero-adapter magic. The genuinely harness-owned
+acts (waking a turn, per-turn context injection, forwarding native tool hooks,
+native modals) still need a per-harness adapter; PMX owns everything on its side of
+the line (queues, endpoints, schemas, the canvas-surface fallback).
+
+## The interface
+
+Every adapter implements as much of this as its host allows; PMX provides the
+surface each one binds to.
+
+| Adapter method | PMX surface (owned) | Harness-owned part |
+| --- | --- | --- |
+| `pullContext()` | `GET /api/canvas/ax/context?consumer=<id>` · `canvas://ax-context` — full board **plus** a compact `delivery` lead block | When/where to inject it into the model's turn |
+| `deliverSteer()` | `GET /api/canvas/ax/delivery/pending?consumer=<id>` · `canvas_claim_ax_delivery` → act → `POST …/delivery/<id>/mark` · `canvas_mark_ax_delivery` | Calling the host's native send/wake |
+| `ingestActivity(event)` | `POST /api/canvas/ax/activity` · `canvas_ingest_activity` — board auto-reacts | Forwarding the host's tool/session hooks |
+| `awaitGate(id)` | `GET /api/canvas/ax/{approval\|elicitation\|mode}/<id>?waitMs=` · `canvas_await_*` | Optionally surfacing a native modal; the agent must await PMX |
+| `mirrorLog(event)` *(optional)* | `GET /api/canvas/ax/timeline` · `canvas://ax-timeline` | Writing AX events into the host's own chat/session log |
+
+## Steering is gated, not pushed (#54)
+
+A board action (e.g. an `ax.steer` emit from a surface button) enqueues a steering
+message; it does **not** wake the agent. It reaches the next turn only when:
+
+1. **The pin/focus gate is open.** A typical adapter injects `/api/canvas/ax/context`
+   only when something is pinned or focused (`pinned.count > 0 || focus.nodeIds.length > 0`).
+   A steering board must therefore stay pinned, or its button should also emit
+   `ax.focus.set` on the board node, to hold the gate open.
+2. **A human message fires the turn.** A sandbox button click cannot itself create a
+   new agent turn (an app-platform constraint). Any human prompt triggers the injection.
+3. **The agent acts, then acks.** Injected `pendingSteering` / `pendingActivity` is
+   *to-do*, not narration: act on it, then `canvas_mark_ax_delivery` the steering
+   (or resolve the work item / gate). Until acked, steering re-injects every gated turn.
+
+The `delivery` lead block (`GET /api/canvas/ax/context?consumer=<id>`) is the
+robustness hedge: it's compact and sits above the full dump, so an adapter can inject
+it un-truncated even on a busy board where the full context is clipped.
+
+## The two primitives that close the loop
+
+- **Activity ingestion (bidirectional board).** Before, AX was one-directional
+  (agent → board). With `ingestActivity`, the agent's *real work* flows back: a failed
+  tool becomes a blocked work item + a review finding + evidence without the agent
+  remembering to push it. Reactions are kind-driven and overridable per call.
+- **Blocking gates (gates that actually gate).** Before, an approval gate was inert
+  data the agent had to poll. With `canvas_await_approval` (and the `?waitMs` HTTP
+  long-poll), the agent requests a gate then *blocks* until the human resolves it in
+  the browser — real human-in-the-loop control on any harness.
+
+## What stays harness-owned
+
+Waking a turn, the exact per-turn injection timing, forwarding native tool hooks, and
+native blocking modals are the host's job — PMX defines the neutral interface and owns
+its side. Model/abort control (`setModel`, `abort`) is intentionally out of scope.
+
+See [`docs/http-api.md`](http-api.md) and [`docs/mcp.md`](mcp.md) for the full surface,
+and the per-harness notes under `skills/pmx-canvas/references/`.

package/docs/http-api.md

@@ -46,8 +46,18 @@ curl -X POST http://localhost:4313/api/canvas/node \
 curl -X POST http://localhost:4313/api/canvas/node \
   -H "Content-Type: application/json" \
   -d '{"type":"html-primitive","kind":"choice-grid","title":"Options","data":{"items":[{"title":"Small patch","summary":"Least disruption."}]}}'
+
+# Opt an html node into AX. Top-level `html` AND `axCapabilities` are accepted on
+# POST add and PATCH update (and may also be nested under `data`).
+curl -X POST http://localhost:4313/api/canvas/node \
+  -H "Content-Type: application/json" \
+  -d '{"type":"html","title":"AX board","html":"<p>steering board</p>","axCapabilities":{"enabled":true,"allowed":["ax.steer"]}}'
 ```
 
+A node creation request must resolve a `type` — pass it in the body (`{ "type":
+... }`) or as a `?type=` query param. An empty / type-less body returns `400`
+rather than silently creating a markdown node.
+
 ## Edges
 
 ```bash
@@ -177,7 +187,9 @@ curl http://localhost:4313/api/canvas/ax/host-capability
 
 Validation: `/ax/event` requires a valid `kind` + `summary` (400 otherwise);
 `/ax/evidence` requires `kind` + `title`; `/ax/steer`, `/ax/work`,
-`/ax/approval`, `/ax/review` require their primary field; `PATCH /ax/work/:id`
+`/ax/approval`, `/ax/review` require their primary field; `POST`/`PATCH /ax/work`
+reject an unknown `status` with 400 (the tokens are `todo`, `in-progress`,
+`blocked`, `done`, `cancelled` — hyphens, not underscores); `PATCH /ax/work/:id`
 and `PATCH /ax/review/:id` return 404 for unknown IDs; approval resolve returns
 404 if the gate is missing or already resolved.
 
@@ -218,6 +230,24 @@ curl -X POST http://localhost:4313/api/canvas/ax/mode/<id>/resolve \
   -d '{"decision":"approved"}'
 curl http://localhost:4313/api/canvas/ax/mode
 
+# Activity ingestion — forward an agent tool/session event; the board auto-reacts
+# (kind-driven, overridable: failure → work item + review + evidence; tool-result
+# + outcome:"success" → evidence). Set a reaction to false to suppress it.
+curl -X POST http://localhost:4313/api/canvas/ax/activity \
+  -H "Content-Type: application/json" \
+  -d '{"kind":"failure","title":"tsc failed","summary":"type error in x.ts","nodeIds":["node-1"],"source":"api"}'
+
+# Blocking gate read — read one gate, or long-poll with ?waitMs until the human
+# resolves it in the browser (gates that actually gate). Returns { <primitive>, pending }.
+curl "http://localhost:4313/api/canvas/ax/approval/<id>"                 # immediate read
+curl "http://localhost:4313/api/canvas/ax/approval/<id>?waitMs=30000"    # blocks ≤30s / until resolved
+curl "http://localhost:4313/api/canvas/ax/elicitation/<id>?waitMs=30000"
+curl "http://localhost:4313/api/canvas/ax/mode/<id>?waitMs=30000"
+
+# Context — optional ?consumer= filters the compact, loop-safe `delivery` lead block
+# (undelivered steering + open work/approvals it can act on) for per-turn injection.
+curl "http://localhost:4313/api/canvas/ax/context?consumer=copilot"
+
 # 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 \
@@ -234,7 +264,9 @@ curl -X POST http://localhost:4313/api/canvas/ax/policy \
 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.
+and `/ax/mode/:id/resolve` return 404 for unknown IDs; `/ax/activity` requires a
+valid `kind` + `title` (400 otherwise); the single-item gate GETs return 404 for
+unknown IDs and clamp `?waitMs` to ≤120000.
 
 ## Diagrams (Excalidraw preset)
 

package/docs/mcp.md

@@ -1,6 +1,6 @@
 # MCP reference
 
-PMX Canvas ships an MCP stdio server with **65 tools** + **14 core resources**,
+PMX Canvas ships an MCP stdio server with **69 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.
@@ -72,6 +72,10 @@ searchable and readable in pinned/spatial context.
 | `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_ingest_activity` | Ingest a harness-forwarded agent activity (tool/session event); the board auto-reacts with kind-driven, overridable defaults (failure → work item + review + evidence; `tool-result`+success → evidence). Makes AX bidirectional |
+| `canvas_await_approval` | Block until an approval gate resolves (human approves/rejects in the browser) or the timeout elapses (`timeoutMs` 0 = immediate read). Gates that actually gate |
+| `canvas_await_elicitation` | Block until an elicitation is answered or the timeout elapses |
+| `canvas_await_mode` | Block until a mode request resolves or the timeout elapses |
 | `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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/skills/pmx-canvas/SKILL.md

@@ -843,6 +843,12 @@ Eligible nodes can emit one normalized, validated AX interaction that maps onto
 AX operation — work item, evidence, approval, review, focus, steering, event,
 elicitation, or mode request. One envelope, many transports:
 
+This is the **agent-native nodes** model: existing canvas node types become
+interactive agent controls when their AX capabilities allow it. Do not describe
+this as a separate node type; it is a capability layer on top of markdown,
+status, HTML, json-render, graph, web-artifact, MCP app, and other supported
+nodes.
+
 - **Endpoint:** `POST /api/canvas/ax/interaction` with
   `{ type, sourceNodeId, payload }` (MCP: `canvas_ax_interaction`; CLI:
   `pmx-canvas ax interaction`). Returns `{ ok, primitive }` or
@@ -857,10 +863,12 @@ elicitation, or mode request. One envelope, many transports:
   before submitting: `html` / `html-primitive` nodes (when opted in) call
   `window.PMX_AX.emit(type, payload)`; **json-render / graph** viewers forward a
   spec action named after an AX type (e.g. `on.press → { action:
-  "ax.work.create", params }`, `sourceSurface: 'json-render'`); opted-in ext-app
-  **`mcp-app`** nodes get the same `window.PMX_AX.emit` injected
-  (`sourceSurface: 'mcp-app'`). The server re-validates capabilities regardless
-  of transport — bridges are convenience, not a trust boundary.
+  "ax.work.create", params }`, `sourceSurface: 'json-render'`); web-artifact
+  **`mcp-app`** nodes use the same parent bridge; external MCP app frames
+  (`mode: "ext-app"`) can emit through an injected `window.PMX_AX.emit` with
+  Promise acknowledgements, but do not get the read-state bridge. The server
+  re-validates capabilities regardless of transport — bridges are convenience,
+  not a trust boundary.
 - **Delivery (adapterless):** `canvas://ax-pending-steering` /
   `canvas_claim_ax_delivery` return two things, both loop-safe (a consumer never
   receives items it originated):
@@ -877,6 +885,26 @@ elicitation, or mode request. One envelope, many transports:
     live. Clients that **poll** instead should poll `canvas_claim_ax_delivery` —
     `pendingActivity` is how non-steering browser changes reach them. Only steering
     flows through the claim/ack queue.
+  - **Steering is gated, not pushed.** A surface button that emits `ax.steer`
+    enqueues a steer — it does NOT wake the agent. With a prompt-injecting host
+    adapter (e.g. Copilot), it reaches the next turn only when (1) the **pin/focus
+    gate is open** (something pinned or focused — so keep a steering board pinned, or
+    have its button also emit `ax.focus.set` on itself), (2) a **human message** fires
+    the turn, and (3) the agent **acts then acks** (`canvas_mark_ax_delivery`), or the
+    steer re-injects every gated turn. `GET /api/canvas/ax/context?consumer=<id>` adds
+    a compact, loop-safe `delivery: { pendingSteering, pendingActivity }` lead block an
+    adapter can inject un-truncated, so steering survives the full-context char clip.
+- **Activity ingestion (bidirectional board):** a host adapter forwards the agent's
+  tool/session events with `canvas_ingest_activity` (HTTP `POST /api/canvas/ax/activity`)
+  and the board auto-reacts — `failure`/`error` (or `outcome:"failure"`) → a blocked
+  work item + a review finding + `logs` evidence; `tool-result` + `outcome:"success"` →
+  `tool-result` evidence; everything else records a timeline event only. Override or
+  suppress per call via `reactions` (`{ workItem: false }`, `{ review: { severity } }`, …).
+- **Blocking gates (gates that actually gate):** after requesting an approval /
+  elicitation / mode, `canvas_await_approval` / `canvas_await_elicitation` /
+  `canvas_await_mode` (HTTP `GET /api/canvas/ax/<kind>/<id>?waitMs=`) BLOCK until the
+  human resolves it in the browser or the timeout elapses (`timeoutMs` 0 = immediate
+  read; ≤120000). Use this to pause real work on a human decision instead of polling.
 - **Elicitation / mode:** request structured human input
   (`canvas_request_elicitation` → `canvas_respond_elicitation`) or a workflow
   mode transition (`canvas_request_mode` → `canvas_resolve_mode`); both are
@@ -916,8 +944,10 @@ AX interactions are gated per node type. The lists below are each type's **ceili
 | `webpage` | `ax.evidence.add`, `ax.review.add`, `ax.focus.set`, `ax.event.record` |
 | `group` | `ax.focus.set`, `ax.work.create`, `ax.command.invoke`, `ax.event.record` |
 
-**Opt-in** — set `data.axCapabilities.enabled = true` (MCP: pass `axCapabilities` to
-`canvas_add_html_node` or `canvas_update_node`; HTTP: nest under `data`):
+**Opt-in** — set `axCapabilities.enabled = true` (MCP: pass `axCapabilities` to
+`canvas_add_html_node` / `canvas_update_node`. HTTP: `axCapabilities` **and** the
+`html` body are accepted **top-level on both `POST /api/canvas/node` and
+`PATCH /api/canvas/node/<id>`**, or nested under `data` — both work, top-level wins):
 
 | Node type | Allowed AX interaction types |
 |-----------|------------------------------|
@@ -928,7 +958,9 @@ AX interactions are gated per node type. The lists below are each type's **ceili
 only, no human-facing emit.
 
 The 11 interaction types and what they create: `ax.work.create` / `ax.work.update`
-(work-queue items, status todo→in-progress→blocked→done→cancelled), `ax.evidence.add`
+(work-queue items; status is exactly one of `todo`, `in-progress`, `blocked`, `done`,
+`cancelled` — **hyphens, not underscores**; `POST`/`PATCH /api/canvas/ax/work` reject an
+unknown token like `in_progress` with `400`), `ax.evidence.add`
 (timeline evidence), `ax.review.add` (review annotation), `ax.focus.set` (agent focus
 pointer), `ax.steer` (a steering message delivered to the agent), `ax.approval.request`
 (approval gate), `ax.elicitation.request` (structured human input), `ax.mode.request`
@@ -949,6 +981,12 @@ state. The read side mirrors the write side:
 - **Emit (write):** in `html`, call `window.PMX_AX.emit("ax.work.create", { title })`;
   in `json-render`, bind a control action named after the AX type
   (`on: { press: { action: "ax.work.create", params: { title } } }`).
+- **Confirm (#55):** for `html` / `html-primitive` and PMX_AX-enabled `mcp-app`
+  surfaces, `emit` returns a Promise that resolves with the result once the
+  canvas acks it, so a button can self-confirm: `const r = await
+  window.PMX_AX.emit(...); if (r.ok) showQueued();`. You can also
+  `window.PMX_AX.on('ack', cb)` or listen for the `pmx-ax-ack` event. (Falls back
+  to an `ax-ack-timeout` result after 10s, so `await` never hangs.)
 - **Reflect (read):** the canvas seeds the surface with a compact AX snapshot at
   load (the same shape as `GET /api/canvas/ax/surface-snapshot`) and live-updates it
   as AX state changes. Works on all three authored surface types:
@@ -966,11 +1004,15 @@ state. The read side mirrors the write side:
 Minimal html work board (drop-in via `canvas_add_html_node`, `axCapabilities.enabled: true`):
 
 ```html
-<button onclick="window.PMX_AX.emit('ax.work.create',{title:'New task'})">+ Task</button>
+<button id="add">+ Task</button> <span id="ok"></span>
 <ul id="q"></ul>
 <script>
   function render(s){ document.getElementById('q').innerHTML =
     ((s&&s.workItems)||[]).map(w => '<li>['+w.status+'] '+w.title+'</li>').join(''); }
+  document.getElementById('add').onclick = async () => {
+    const r = await window.PMX_AX.emit('ax.work.create',{title:'New task'});
+    document.getElementById('ok').textContent = r && r.ok ? 'queued ✓' : 'failed';   // #55 self-confirm
+  };
   render(window.PMX_AX && window.PMX_AX.state);
   window.addEventListener('pmx-ax-update', e => render(e.detail));
 </script>

package/skills/pmx-canvas/references/codex-app-adapter.md

@@ -86,10 +86,24 @@ against `canvas_set_ax_focus`.
 Codex agents should treat PMX AX context as host-native working context:
 
 - `canvas://pinned-context` is the explicit human-curated node set.
-- `canvas://ax-context` combines pins, focus, and surface metadata.
+- `canvas://ax-context` combines pins, focus, and surface metadata, plus a compact
+  loop-safe `delivery: { pendingSteering, pendingActivity }` lead block
+  (`GET /api/canvas/ax/context?consumer=codex` filters out Codex-originated items).
 - `canvas_get_ax` returns both persisted AX state and agent-ready context.
 - Focus is a current attention target, not a command to ignore the rest of the repository.
 
+The adapterless MCP+Browser path is poll-based: there is no automatic prompt injection,
+so a board click does not wake the current turn. Codex agents poll
+`canvas_claim_ax_delivery` (steering + `pendingActivity`) and act/ack explicitly. The
+loop-closing surfaces work over MCP today even without a dedicated extension:
+
+- **Self-report work** with `canvas_ingest_activity` (the board auto-reacts: a failed
+  tool → a blocked work item + review + evidence). Automatic forwarding of Codex's own
+  tool hooks would need a Codex adapter; manual ingestion works now.
+- **Block on a decision** with `canvas_await_approval` / `canvas_await_elicitation` /
+  `canvas_await_mode` (they long-poll PMX until the human resolves the gate in the
+  Browser or the timeout elapses) instead of looping on `canvas_get_ax`.
+
 ## Live-Test Checklist
 
 1. Open `http://127.0.0.1:4313/workbench` in the Codex in-app Browser first so the user can see