pmx-canvas 0.1.34 → 0.1.36

package/skills/pmx-canvas/references/github-copilot-app-adapter.md

@@ -48,6 +48,37 @@ panel.
 - Reads `/api/canvas/ax/context` and injects pinned/focused context from
   `onUserPromptSubmitted`.
 - Exposes adapter actions for status, AX context refresh, AX focus, and explicit session steering.
+
+### Agent behavior — steering is gated, not pushed
+
+`onUserPromptSubmitted` injects the whole `/api/canvas/ax/context` (pins, focus, work
+items, approval gates, and `timeline.pendingSteering`) as hidden context — but only
+when the **pin/focus gate is open** (`pinned.count > 0 || focus.nodeIds.length > 0`),
+and it is clipped to a char budget. Three consequences the adapter/agent must honor:
+
+1. A steering board must **stay pinned** (or its button must also emit `ax.focus.set`
+   on the board node) to hold the gate open.
+2. A sandbox button click does **not** wake a turn — a human message does. The click
+   only enqueues the steer.
+3. The agent must **act on injected `pendingSteering` / `pendingActivity` and then ack**
+   (`canvas_mark_ax_delivery`), or it re-injects every gated turn.
+
+To be robust to the char clip, prefer injecting the compact loop-safe lead block from
+`GET /api/canvas/ax/context?consumer=copilot` (`delivery.pendingSteering` +
+`delivery.pendingActivity`) **above** the full dump.
+
+### Closing the loop (optional, recommended)
+
+- **Forward tool/session hooks** (`onPreToolUse` / `onPostToolUse` /
+  `onPostToolUseFailure` / `onSessionStart` / `onSessionEnd` / `onErrorOccurred`) to
+  `POST /api/canvas/ax/activity` (`canvas_ingest_activity`) so the board reflects the
+  agent's real work automatically (a failed tool → a blocked work item + review +
+  evidence).
+- **Await gates** with `canvas_await_approval` / `canvas_await_elicitation` /
+  `canvas_await_mode` (or surface a native modal and await the PMX result) so an
+  approval gate actually blocks the agent until the human resolves it.
+
+See [`docs/ax-host-adapter-contract.md`](../../../docs/ax-host-adapter-contract.md).
 - Keeps all persistent PMX state in `.pmx-canvas/canvas.db`; the extension does not own canvas
   state.
 

package/src/client/nodes/ExtAppFrame.tsx

@@ -97,6 +97,66 @@ export function resolveExtAppSandbox(value: unknown): string {
     : DEFAULT_EXT_APP_SANDBOX;
 }
 
+export function buildExtAppAxBridgeScript(axToken: string, nodeId: string): string {
+  return `<script data-pmx-canvas-ax-bridge>
+(function () {
+  const PMX_AX_TOKEN = ${JSON.stringify(axToken)};
+  const PMX_AX_NODE_ID = ${JSON.stringify(nodeId)};
+  window.PMX_AX = window.PMX_AX || {};
+  const pending = new Map();
+  const ackListeners = [];
+  let seq = 0;
+  window.PMX_AX.emit = function (type, payload) {
+    seq += 1;
+    const correlationId = PMX_AX_NODE_ID + '-' + seq + '-' + (Date.now ? Date.now() : 0);
+    return new Promise(function (resolve) {
+      const timer = setTimeout(function () {
+        pending.delete(correlationId);
+        resolve({ ok: false, status: 504, code: 'ax-ack-timeout', error: 'ax-ack-timeout' });
+      }, 10000);
+      pending.set(correlationId, function (result) { clearTimeout(timer); resolve(result); });
+      window.parent.postMessage({
+        source: 'pmx-canvas-ax',
+        token: PMX_AX_TOKEN,
+        nodeId: PMX_AX_NODE_ID,
+        correlationId: correlationId,
+        interaction: { type: String(type), payload: payload && typeof payload === 'object' ? payload : {} },
+      }, '*');
+    });
+  };
+  window.PMX_AX.on = function (eventType, cb) {
+    if (eventType === 'ack' && typeof cb === 'function') ackListeners.push(cb);
+  };
+  window.addEventListener('message', function (event) {
+    const m = event.data;
+    if (!m || m.source !== 'pmx-canvas-ax-ack' || m.token !== PMX_AX_TOKEN) return;
+    const result = m.result || { ok: false };
+    const resolver = m.correlationId ? pending.get(m.correlationId) : undefined;
+    if (resolver) { pending.delete(m.correlationId); resolver(result); }
+    for (let i = 0; i < ackListeners.length; i += 1) {
+      try { ackListeners[i](result, m.interaction || null); } catch (e) {}
+    }
+    try { window.dispatchEvent(new CustomEvent('pmx-ax-ack', { detail: { result: result, interaction: m.interaction || null } })); } catch (e) {}
+  });
+})();
+</script>`;
+}
+
+export function injectExtAppAxBridgeScript(html: string, axBridgeScript: string): string {
+  if (!axBridgeScript) return html;
+  const headMatch = /<head\b[^>]*>/i.exec(html);
+  if (headMatch?.index !== undefined) {
+    const insertAt = headMatch.index + headMatch[0].length;
+    return `${html.slice(0, insertAt)}${axBridgeScript}${html.slice(insertAt)}`;
+  }
+  const bodyMatch = /<body\b[^>]*>/i.exec(html);
+  if (bodyMatch?.index !== undefined) {
+    const insertAt = bodyMatch.index + bodyMatch[0].length;
+    return `${html.slice(0, insertAt)}${axBridgeScript}${html.slice(insertAt)}`;
+  }
+  return `${axBridgeScript}${html}`;
+}
+
 function positiveDimension(value: number, fallback: number): number {
   if (Number.isFinite(value) && value > 0) return Math.round(value);
   if (Number.isFinite(fallback) && fallback > 0) return Math.round(fallback);
@@ -164,31 +224,39 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const axEnabled = axCaps?.enabled === true && typeof html === 'string' && html.length > 0;
   const axToken = useMemo(() => `ax-${crypto.randomUUID()}`, []);
   const axBridgeScript = axEnabled
-    ? `<script data-pmx-canvas-ax-bridge>window.PMX_AX={emit:function(t,p){window.parent.postMessage({source:'pmx-canvas-ax',token:${JSON.stringify(axToken)},nodeId:${JSON.stringify(nodeId)},interaction:{type:String(t),payload:p&&typeof p==='object'?p:{}}},'*');}};</script>`
+    ? buildExtAppAxBridgeScript(axToken, nodeId)
     : '';
-  const iframeDocument = useIframeDocument((html ?? '') + axBridgeScript, iframeSandbox);
+  const iframeDocument = useIframeDocument(injectExtAppAxBridgeScript(html ?? '', axBridgeScript), iframeSandbox);
 
   useEffect(() => {
     if (!axEnabled) return;
     function onAxMessage(event: MessageEvent) {
       if (event.source !== iframeRef.current?.contentWindow) return;
       const data = event.data as {
-        source?: string; token?: string; nodeId?: string;
+        source?: string; token?: string; nodeId?: string; correlationId?: string;
         interaction?: { type?: unknown; payload?: unknown };
       } | null;
       if (!data || data.source !== 'pmx-canvas-ax' || data.token !== axToken || data.nodeId !== nodeId) return;
       const interaction = data.interaction;
       if (!interaction || typeof interaction.type !== 'string') return;
+      const interactionType = interaction.type;
       void submitAxInteractionFromClient({
-        type: interaction.type,
+        type: interactionType,
         sourceNodeId: nodeId,
         sourceSurface: 'mcp-app',
         ...(interaction.payload && typeof interaction.payload === 'object'
           ? { payload: interaction.payload as Record<string, unknown> }
           : {}),
       }).then((res) => {
-        if (res.ok) showToast('context', 'AX interaction', interaction.type as string, [nodeId]);
+        if (res.ok) showToast('context', 'AX interaction', interactionType, [nodeId]);
         else showToast('remove', 'AX interaction rejected', res.error ?? res.code ?? '', [nodeId]);
+        iframeRef.current?.contentWindow?.postMessage({
+          source: 'pmx-canvas-ax-ack',
+          token: axToken,
+          ...(data.correlationId ? { correlationId: data.correlationId } : {}),
+          interaction: { type: interactionType },
+          result: res,
+        }, '*');
       });
     }
     window.addEventListener('message', onAxMessage);

package/src/client/nodes/HtmlNode.tsx

@@ -57,22 +57,31 @@ export function HtmlNode({
       // nodeId are a second gate, not the only one.
       if (event.source !== iframeRef.current?.contentWindow) return;
       const data = event.data as {
-        source?: string; token?: string; nodeId?: string;
+        source?: string; token?: string; nodeId?: string; correlationId?: string;
         interaction?: { type?: unknown; payload?: unknown };
       } | null;
       if (!data || data.source !== 'pmx-canvas-ax' || data.token !== axToken || data.nodeId !== node.id) return;
       const interaction = data.interaction;
       if (!interaction || typeof interaction.type !== 'string') return;
+      const interactionType = interaction.type;
       void submitAxInteractionFromClient({
-        type: interaction.type,
+        type: interactionType,
         sourceNodeId: node.id,
         sourceSurface: 'html-node',
         ...(interaction.payload && typeof interaction.payload === 'object'
           ? { payload: interaction.payload as Record<string, unknown> }
           : {}),
       }).then((res) => {
-        if (res.ok) showToast('context', 'AX interaction', interaction.type as string, [node.id]);
+        if (res.ok) showToast('context', 'AX interaction', interactionType, [node.id]);
         else showToast('remove', 'AX interaction rejected', res.error ?? res.code ?? '', [node.id]);
+        // Report #55: ack back to the surface so it can self-confirm (e.g. "queued ✓").
+        iframeRef.current?.contentWindow?.postMessage({
+          source: 'pmx-canvas-ax-ack',
+          token: axToken,
+          ...(data.correlationId ? { correlationId: data.correlationId } : {}),
+          interaction: { type: interactionType },
+          result: res,
+        }, '*');
       });
     }
     window.addEventListener('message', onAxMessage);

package/src/client/nodes/McpAppNode.tsx

@@ -89,22 +89,31 @@ function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boo
     function onAxMessage(event: MessageEvent) {
       if (event.source !== iframeRef.current?.contentWindow) return;
       const data = event.data as {
-        source?: string; token?: string; nodeId?: string;
+        source?: string; token?: string; nodeId?: string; correlationId?: string;
         interaction?: { type?: unknown; payload?: unknown };
       } | null;
       if (!data || data.source !== 'pmx-canvas-ax' || data.token !== axToken || data.nodeId !== node.id) return;
       const interaction = data.interaction;
       if (!interaction || typeof interaction.type !== 'string') return;
+      const interactionType = interaction.type;
       void submitAxInteractionFromClient({
-        type: interaction.type,
+        type: interactionType,
         sourceNodeId: node.id,
         sourceSurface: axSurface,
         ...(interaction.payload && typeof interaction.payload === 'object'
           ? { payload: interaction.payload as Record<string, unknown> }
           : {}),
       }).then((res) => {
-        if (res.ok) showToast('context', 'AX interaction', interaction.type as string, [node.id]);
+        if (res.ok) showToast('context', 'AX interaction', interactionType, [node.id]);
         else showToast('remove', 'AX interaction rejected', res.error ?? res.code ?? '', [node.id]);
+        // Report #55: ack back to the viewer so the surface can self-confirm.
+        iframeRef.current?.contentWindow?.postMessage({
+          source: 'pmx-canvas-ax-ack',
+          token: axToken,
+          ...(data.correlationId ? { correlationId: data.correlationId } : {}),
+          interaction: { type: interactionType },
+          result: res,
+        }, '*');
       });
     }
     window.addEventListener('message', onAxMessage);

package/src/json-render/renderer/index.tsx

@@ -121,6 +121,9 @@ function buildAxHandlers(): Record<string, (params: Record<string, unknown>) =>
   const token = window.__PMX_CANVAS_AX_TOKEN__;
   const handlers: Record<string, (params: Record<string, unknown>) => void> = {};
   if (!nodeId || !token) return handlers;
+  // Declarative json-render boards are reflect-only: a spec action is fire-and-forget
+  // and confirmation arrives as a live `pmx-ax-update` (the work item appears). There
+  // is no JS surface for a Promise-style ack here, so we don't stamp a correlationId.
   for (const type of AX_INTERACTION_HANDLER_NAMES) {
     handlers[type] = (params: Record<string, unknown>) => {
       window.parent.postMessage({

package/src/mcp/canvas-access.ts

@@ -51,6 +51,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']>;
@@ -165,7 +170,7 @@ export interface CanvasAccess {
   focusNode(id: string, options?: { noPan?: boolean }): 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>;
   recordAxEvent(input: RecordAxEventInput, options?: { source?: PmxAxSource }): Promise<RecordAxEventResult>;
   sendSteering(message: string, options?: { source?: PmxAxSource }): Promise<SendSteeringResult>;
@@ -191,6 +196,10 @@ export interface CanvasAccess {
   listModeRequests(): Promise<ListModeRequestsResult>;
   requestMode(input: RequestModeInput, options?: { source?: PmxAxSource }): Promise<RequestModeResult>;
   resolveModeRequest(id: string, decision: 'approved' | 'rejected', options?: { 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 }): Promise<InvokeCommandResult>;
   getPolicy(): Promise<GetPolicyResult>;
@@ -336,8 +345,8 @@ class LocalCanvasAccess implements CanvasAccess {
     return this.canvas.getAxState();
   }
 
-  async getAxContext(): Promise<AxContextResult> {
-    return this.canvas.getAxContext();
+  async getAxContext(options?: { consumer?: string }): Promise<AxContextResult> {
+    return this.canvas.getAxContext(options);
   }
 
   async setAxFocus(nodeIds: string[], options?: { source?: PmxAxSource }): Promise<SetAxFocusResult> {
@@ -396,6 +405,22 @@ class LocalCanvasAccess implements CanvasAccess {
     return this.canvas.resolveModeRequest(id, decision, { ...(options ?? {}), source: options?.source ?? 'mcp' });
   }
 
+  async ingestActivity(input: IngestActivityInput, options?: { source?: PmxAxSource }): Promise<IngestActivityResult> {
+    return this.canvas.ingestActivity(input, { source: options?.source ?? 'mcp' });
+  }
+
+  async awaitApproval(id: string, options?: { timeoutMs?: number }): Promise<AwaitApprovalResult> {
+    return this.canvas.awaitApproval(id, options);
+  }
+
+  async awaitElicitation(id: string, options?: { timeoutMs?: number }): Promise<AwaitElicitationResult> {
+    return this.canvas.awaitElicitation(id, options);
+  }
+
+  async awaitMode(id: string, options?: { timeoutMs?: number }): Promise<AwaitModeResult> {
+    return this.canvas.awaitMode(id, options);
+  }
+
   async getCommandRegistry(): Promise<GetCommandRegistryResult> {
     return this.canvas.getCommandRegistry();
   }
@@ -831,8 +856,9 @@ class RemoteCanvasAccess implements CanvasAccess {
     return response.state;
   }
 
-  async getAxContext(): Promise<AxContextResult> {
-    return await this.requestJson<AxContextResult>('GET', '/api/canvas/ax/context');
+  async getAxContext(options?: { consumer?: string }): Promise<AxContextResult> {
+    const qs = options?.consumer ? `?consumer=${encodeURIComponent(options.consumer)}` : '';
+    return await this.requestJson<AxContextResult>('GET', `/api/canvas/ax/context${qs}`);
   }
 
   async setAxFocus(nodeIds: string[], options?: { source?: PmxAxSource }): Promise<SetAxFocusResult> {
@@ -961,6 +987,49 @@ class RemoteCanvasAccess implements CanvasAccess {
     return (await res.json() as { modeRequest?: ResolveModeRequestResult }).modeRequest ?? null;
   }
 
+  async ingestActivity(input: IngestActivityInput, options?: { source?: PmxAxSource }): Promise<IngestActivityResult> {
+    return await this.requestJson<IngestActivityResult>('POST', '/api/canvas/ax/activity', {
+      ...input,
+      source: options?.source ?? 'mcp',
+    });
+  }
+
+  async awaitApproval(id: string, options?: { timeoutMs?: number }): Promise<AwaitApprovalResult> {
+    // Mirror PmxCanvas's `?? 30000` default so the remote transport blocks like the
+    // local one (an omitted timeout must still long-poll). Explicit 0 = immediate read.
+    const ms = options?.timeoutMs ?? 30000;
+    const qs = ms > 0 ? `?waitMs=${ms}` : '';
+    const res = await fetch(`${this.remoteBaseUrl}/api/canvas/ax/approval/${encodeURIComponent(id)}${qs}`);
+    if (res.status === 404) return { approvalGate: null, pending: false };
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const body = await res.json() as { approvalGate?: AwaitApprovalResult['approvalGate']; pending?: boolean };
+    return { approvalGate: body.approvalGate ?? null, pending: body.pending ?? false };
+  }
+
+  async awaitElicitation(id: string, options?: { timeoutMs?: number }): Promise<AwaitElicitationResult> {
+    // Mirror PmxCanvas's `?? 30000` default so the remote transport blocks like the
+    // local one (an omitted timeout must still long-poll). Explicit 0 = immediate read.
+    const ms = options?.timeoutMs ?? 30000;
+    const qs = ms > 0 ? `?waitMs=${ms}` : '';
+    const res = await fetch(`${this.remoteBaseUrl}/api/canvas/ax/elicitation/${encodeURIComponent(id)}${qs}`);
+    if (res.status === 404) return { elicitation: null, pending: false };
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const body = await res.json() as { elicitation?: AwaitElicitationResult['elicitation']; pending?: boolean };
+    return { elicitation: body.elicitation ?? null, pending: body.pending ?? false };
+  }
+
+  async awaitMode(id: string, options?: { timeoutMs?: number }): Promise<AwaitModeResult> {
+    // Mirror PmxCanvas's `?? 30000` default so the remote transport blocks like the
+    // local one (an omitted timeout must still long-poll). Explicit 0 = immediate read.
+    const ms = options?.timeoutMs ?? 30000;
+    const qs = ms > 0 ? `?waitMs=${ms}` : '';
+    const res = await fetch(`${this.remoteBaseUrl}/api/canvas/ax/mode/${encodeURIComponent(id)}${qs}`);
+    if (res.status === 404) return { modeRequest: null, pending: false };
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const body = await res.json() as { modeRequest?: AwaitModeResult['modeRequest']; pending?: boolean };
+    return { modeRequest: body.modeRequest ?? null, pending: body.pending ?? false };
+  }
+
   async getCommandRegistry(): Promise<GetCommandRegistryResult> {
     const r = await this.requestJson<{ commands?: GetCommandRegistryResult }>('GET', '/api/canvas/ax/command');
     return r.commands ?? [];

package/src/mcp/server.ts

@@ -26,6 +26,7 @@ import { isAbsolute, relative, resolve } from 'node:path';
 import { z } from 'zod';
 import { canvasState, describeCanvasSchema, validateStructuredCanvasPayload } from '../server/index.js';
 import { AX_INTERACTION_TYPES } from '../server/ax-interaction.js';
+import { buildPendingAxActivity } from '../server/ax-state.js';
 import { isHtmlPrimitiveKind } from '../server/html-primitives.js';
 import type { HtmlPrimitiveKind } from '../server/html-primitives.js';
 import { createCanvasAccess, refreshCanvasAccess, type CanvasAccess } from './canvas-access.js';
@@ -200,56 +201,6 @@ function wantsFullPayload(input: { full?: boolean; verbose?: boolean; includeDat
   return input.full === true || input.verbose === true || input.includeData === true;
 }
 
-interface PendingAxActivityItem {
-  kind: 'work-item' | 'approval-gate' | 'elicitation' | 'mode-request';
-  id: string;
-  title: string;
-  status: string;
-  nodeIds: string[];
-  source: string | null;
-}
-
-const OPEN_AX_WORK_STATUSES = new Set(['todo', 'in-progress', 'blocked']);
-
-/**
- * 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.
- * Surfacing this digest there closes report #43 without conflating state with steering.
- * Optionally excludes items the consumer itself originated (loop prevention), mirroring
- * getPendingSteering.
- */
-function buildPendingAxActivity(
-  state: Awaited<ReturnType<CanvasAccess['getAxState']>>,
-  consumer?: string,
-): PendingAxActivityItem[] {
-  const notMine = (source: string | null) => !consumer || source !== consumer;
-  const out: PendingAxActivityItem[] = [];
-  for (const w of state.workItems ?? []) {
-    if (OPEN_AX_WORK_STATUSES.has(w.status) && notMine(w.source)) {
-      out.push({ kind: 'work-item', id: w.id, title: w.title, status: w.status, nodeIds: w.nodeIds ?? [], source: w.source });
-    }
-  }
-  for (const g of state.approvalGates ?? []) {
-    if (g.status === 'pending' && notMine(g.source)) {
-      out.push({ kind: 'approval-gate', id: g.id, title: g.title, status: g.status, nodeIds: g.nodeIds ?? [], source: g.source });
-    }
-  }
-  for (const e of state.elicitations ?? []) {
-    if (e.status === 'pending' && notMine(e.source)) {
-      out.push({ kind: 'elicitation', id: e.id, title: e.prompt, status: e.status, nodeIds: e.nodeIds ?? [], source: e.source });
-    }
-  }
-  for (const m of state.modeRequests ?? []) {
-    if (m.status === 'pending' && notMine(m.source)) {
-      out.push({ kind: 'mode-request', id: m.id, title: m.reason ? `${m.mode}: ${m.reason}` : `mode: ${m.mode}`, status: m.status, nodeIds: m.nodeIds ?? [], source: m.source });
-    }
-  }
-  return out;
-}
-
 function compactNodePayload(node: Awaited<ReturnType<CanvasAccess['getNode']>>): Record<string, unknown> | null {
   if (!node) return null;
   const serialized = serializeCanvasNode(node);
@@ -1361,7 +1312,7 @@ export async function startMcpServer(): Promise<void> {
       const c = await ensureCanvas();
       const state = await c.getAxState();
       const host = await c.getHostCapability();
-      const context = includeContext === false ? undefined : await c.getAxContext();
+      const context = includeContext === false ? undefined : await c.getAxContext({ consumer: 'mcp' });
       return {
         content: [
           {
@@ -1839,6 +1790,96 @@ export async function startMcpServer(): Promise<void> {
     },
   );
 
+  server.tool(
+    'canvas_ingest_activity',
+    'Ingest a normalized agent activity (a tool/session event your harness forwards) so the board reacts automatically — primitive A, makes AX bidirectional. Always records a timeline event; kind-driven default reactions (overridable per call via `reactions`): failure/error → work item (blocked) + review finding + evidence (logs); tool-result + outcome:"success" → evidence (tool-result); everything else (tool-start, session-*, command, note) → event only. Set any reaction to false to suppress it, or to an object to override its fields. Returns { event, workItem, evidence, review }.',
+    {
+      kind: z.enum(['tool-start', 'tool-result', 'failure', 'error', 'session-start', 'session-end', 'command', 'note']),
+      title: z.string(),
+      summary: z.string().optional(),
+      outcome: z.enum(['success', 'failure']).optional(),
+      ref: z.string().optional().describe('A file path, URL, or commit the activity refers to (used as the review file anchor for failures).'),
+      nodeIds: z.array(z.string()).optional(),
+      data: z.record(z.string(), z.unknown()).optional(),
+      reactions: z.object({
+        workItem: z.union([z.literal(false), z.object({
+          status: z.enum(['todo', 'in-progress', 'blocked', 'done', 'cancelled']).optional(),
+          detail: z.string().nullable().optional(),
+        })]).optional(),
+        evidence: z.union([z.literal(false), z.object({
+          kind: z.enum(['logs', 'tool-result', 'screenshot', 'file', 'diff', 'test-output']).optional(),
+          body: z.string().nullable().optional(),
+        })]).optional(),
+        review: z.union([z.literal(false), z.object({
+          severity: z.enum(['info', 'warning', 'error']).optional(),
+          kind: z.enum(['comment', 'finding']).optional(),
+          anchorType: z.enum(['node', 'file', 'region']).optional(),
+          nodeId: z.string().nullable().optional(),
+        })]).optional(),
+      }).optional().describe('Override or suppress the kind-driven default reactions.'),
+      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system']).optional(),
+    },
+    async ({ kind, title, summary, outcome, ref, nodeIds, data, reactions, source }) => {
+      const c = await ensureCanvas();
+      const result = await c.ingestActivity(
+        {
+          kind,
+          title,
+          ...(summary !== undefined ? { summary } : {}),
+          ...(outcome !== undefined ? { outcome } : {}),
+          ...(ref !== undefined ? { ref } : {}),
+          ...(nodeIds !== undefined ? { nodeIds } : {}),
+          ...(data !== undefined ? { data } : {}),
+          ...(reactions !== undefined ? { reactions } : {}),
+        },
+        { source: source ?? 'mcp' },
+      );
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: true, ...result }) }] };
+    },
+  );
+
+  server.tool(
+    'canvas_await_approval',
+    'Block until an approval gate resolves (the human approves/rejects it in the browser) or the timeout elapses — primitive D, gates that actually gate. timeoutMs 0 = read immediately without waiting. Returns { approvalGate, pending } (pending=true → still unresolved after the wait).',
+    {
+      id: z.string(),
+      timeoutMs: z.number().int().min(0).max(120000).optional().describe('Max ms to block (default 30000; 0 = immediate read; capped at 120000).'),
+    },
+    async ({ id, timeoutMs }) => {
+      const c = await ensureCanvas();
+      const result = await c.awaitApproval(id, timeoutMs !== undefined ? { timeoutMs } : {});
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: result.approvalGate !== null, ...result }) }] };
+    },
+  );
+
+  server.tool(
+    'canvas_await_elicitation',
+    'Block until an elicitation is answered (the human responds in the browser) or the timeout elapses — primitive D. timeoutMs 0 = read immediately. Returns { elicitation, pending }.',
+    {
+      id: z.string(),
+      timeoutMs: z.number().int().min(0).max(120000).optional().describe('Max ms to block (default 30000; 0 = immediate read; capped at 120000).'),
+    },
+    async ({ id, timeoutMs }) => {
+      const c = await ensureCanvas();
+      const result = await c.awaitElicitation(id, timeoutMs !== undefined ? { timeoutMs } : {});
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: result.elicitation !== null, ...result }) }] };
+    },
+  );
+
+  server.tool(
+    'canvas_await_mode',
+    'Block until a mode request resolves (approved/rejected in the browser) or the timeout elapses — primitive D. timeoutMs 0 = read immediately. Returns { modeRequest, pending }.',
+    {
+      id: z.string(),
+      timeoutMs: z.number().int().min(0).max(120000).optional().describe('Max ms to block (default 30000; 0 = immediate read; capped at 120000).'),
+    },
+    async ({ id, timeoutMs }) => {
+      const c = await ensureCanvas();
+      const result = await c.awaitMode(id, timeoutMs !== undefined ? { timeoutMs } : {});
+      return { content: [{ type: 'text', text: JSON.stringify({ ok: result.modeRequest !== null, ...result }) }] };
+    },
+  );
+
   server.tool(
     'canvas_invoke_command',
     'Invoke a registry-gated PMX command intent (pmx.plan | pmx.execute | pmx.promote-context | pmx.summarize | pmx.review). Records a timeline event a host/agent can observe — NOT arbitrary execution; unknown names are rejected.',
@@ -2283,7 +2324,7 @@ export async function startMcpServer(): Promise<void> {
     },
     async () => {
       const c = await ensureCanvas();
-      const context = await c.getAxContext();
+      const context = await c.getAxContext({ consumer: 'mcp' });
       return {
         contents: [
           {
@@ -2394,7 +2435,7 @@ export async function startMcpServer(): Promise<void> {
     'Inject the current PMX Canvas AX context (pins, focus, work items, approvals, review, timeline) so an MCP-aware client can ground its next action without a host-native adapter.',
     async () => {
       const c = await ensureCanvas();
-      const context = await c.getAxContext();
+      const context = await c.getAxContext({ consumer: 'mcp' });
       return {
         messages: [
           {

package/src/server/ax-context.ts

@@ -1,6 +1,8 @@
 import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
 import {
   buildAxContext,
+  buildPendingAxActivity,
+  AX_CONTEXT_STEERING_LIMIT,
   type PmxAxContext,
   type PmxAxPinnedContext,
   type PmxAxWorkItem,
@@ -71,7 +73,7 @@ export function buildCanvasAxPinnedContext(): PmxAxPinnedContext {
   };
 }
 
-export function buildCanvasAxContext(): PmxAxContext {
+export function buildCanvasAxContext(consumer?: string): PmxAxContext {
   const layout = canvasState.getLayout();
   const ax = canvasState.getAxState();
   const focusNodes = ax.focus.nodeIds
@@ -79,6 +81,10 @@ export function buildCanvasAxContext(): PmxAxContext {
     .filter((node): node is CanvasNodeState => node !== undefined);
   return buildAxContext({
     layout,
+    delivery: {
+      pendingSteering: canvasState.getPendingSteering({ consumer, limit: AX_CONTEXT_STEERING_LIMIT }),
+      pendingActivity: buildPendingAxActivity(ax, consumer),
+    },
     pinned: buildCanvasAxPinnedContext(),
     focus: ax.focus,
     focusNodes: serializeNodes(focusNodes),