pmx-canvas 0.1.34 → 0.1.36

package/src/server/ax-state.ts

@@ -157,6 +157,22 @@ export interface PmxAxFocusContext extends PmxAxFocusState {
   nodes: AgentContextNode[];
 }
 
+// ── Pending agent-actionable digest (open canvas-bound items) ──────
+export interface PendingAxActivityItem {
+  kind: 'work-item' | 'approval-gate' | 'elicitation' | 'mode-request';
+  id: string;
+  title: string;
+  status: string;
+  nodeIds: string[];
+  source: PmxAxSource | null;
+}
+
+// ── Delivery lead block (compact, un-truncated; for per-turn injection) ──
+export interface PmxAxDeliveryContext {
+  pendingSteering: PmxAxSteeringMessage[];
+  pendingActivity: PendingAxActivityItem[];
+}
+
 export interface PmxAxContext {
   version: 1;
   generatedAt: string;
@@ -164,6 +180,10 @@ export interface PmxAxContext {
     nodeCount: number;
     edgeCount: number;
   };
+  // Compact, loop-safe lead block of what's awaiting the agent right now
+  // (undelivered steering + open work/approvals/elicitations/mode requests).
+  // Sits ABOVE the full dump so a host adapter can inject it un-truncated.
+  delivery: PmxAxDeliveryContext;
   pinned: PmxAxPinnedContext;
   focus: PmxAxFocusContext;
   workItems: PmxAxWorkItem[];
@@ -176,6 +196,44 @@ export interface PmxAxContext {
   host: PmxAxHostCapability | null;
 }
 
+const OPEN_AX_WORK_STATUSES = new Set<PmxAxWorkItemStatus>(['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.
+ * 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 function buildPendingAxActivity(state: PmxAxState, consumer?: string): PendingAxActivityItem[] {
+  const notMine = (source: PmxAxSource | 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;
+}
+
 const AX_SOURCES = new Set<PmxAxSource>(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system']);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -207,6 +265,33 @@ function normalizeNodeIds(value: unknown, validNodeIds?: Set<string>): string[]
 
 const AX_EVENT_KINDS = new Set<PmxAxEventKind>(['prompt', 'assistant-message', 'tool-start', 'tool-result', 'failure', 'approval', 'steering', 'command']);
 
+// ── Activity ingestion (harness-forwarded tool/session events) ─────
+// A normalized activity the agent's harness forwards; the board auto-reacts.
+// The precise activity kind is preserved on the recorded event's `data.activityKind`;
+// only the (coarser) timeline event kind is constrained to PmxAxEventKind.
+export type PmxAxActivityKind =
+  | 'tool-start' | 'tool-result' | 'failure' | 'error'
+  | 'session-start' | 'session-end' | 'command' | 'note';
+const AX_ACTIVITY_KINDS = new Set<PmxAxActivityKind>([
+  'tool-start', 'tool-result', 'failure', 'error', 'session-start', 'session-end', 'command', 'note',
+]);
+const ACTIVITY_TO_EVENT_KIND: Record<PmxAxActivityKind, PmxAxEventKind> = {
+  'tool-start': 'tool-start',
+  'tool-result': 'tool-result',
+  'failure': 'failure',
+  'error': 'failure',
+  'session-start': 'assistant-message',
+  'session-end': 'assistant-message',
+  'command': 'command',
+  'note': 'assistant-message',
+};
+export function isAxActivityKind(value: unknown): value is PmxAxActivityKind {
+  return typeof value === 'string' && AX_ACTIVITY_KINDS.has(value as PmxAxActivityKind);
+}
+export function mapAxActivityKindToEventKind(kind: PmxAxActivityKind): PmxAxEventKind {
+  return ACTIVITY_TO_EVENT_KIND[kind];
+}
+
 // ── 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
@@ -725,6 +810,7 @@ export function normalizeAxState(input: unknown, validNodeIds?: Set<string>): Pm
 
 export function buildAxContext(input: {
   layout: CanvasLayout;
+  delivery: PmxAxDeliveryContext;
   pinned: PmxAxPinnedContext;
   focus: PmxAxFocusState;
   focusNodes: AgentContextNode[];
@@ -744,6 +830,7 @@ export function buildAxContext(input: {
       nodeCount: input.layout.nodes.length,
       edgeCount: input.layout.edges.length,
     },
+    delivery: input.delivery,
     pinned: input.pinned,
     focus: {
       ...input.focus,

package/src/server/ax-wait.ts

@@ -0,0 +1,56 @@
+import { canvasState } from './canvas-state.js';
+
+/** Hard ceiling on a single blocking wait, regardless of the requested timeout. */
+export 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 async function waitForAxResolution<T extends { status: string }>(opts: {
+  read: () => T | null;
+  isResolved: (value: T) => boolean;
+  timeoutMs: number;
+  signal?: AbortSignal;
+}): Promise<AxWaitResult<T>> {
+  const { read, isResolved } = opts;
+  const timeoutMs = Math.max(0, Math.min(opts.timeoutMs, AX_WAIT_MAX_MS));
+  const pendingOf = (v: T | null): boolean => (v ? !isResolved(v) : false);
+
+  const current = read();
+  if (!current || isResolved(current) || timeoutMs === 0 || opts.signal?.aborted) {
+    return { value: current, pending: pendingOf(current) };
+  }
+
+  return new Promise<AxWaitResult<T>>((resolve) => {
+    let done = false;
+    const finish = (): void => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      dispose();
+      opts.signal?.removeEventListener('abort', onSettle);
+      const v = read();
+      resolve({ value: v, pending: pendingOf(v) });
+    };
+    const onSettle = finish;
+    const check = (type: string): void => {
+      if (type !== 'ax') return;
+      const v = read();
+      if (!v || isResolved(v)) finish();
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    const dispose = canvasState.onChange(check);
+    opts.signal?.addEventListener('abort', onSettle, { once: true });
+  });
+}

package/src/server/canvas-state.ts

@@ -70,6 +70,8 @@ import {
   listAxCommands,
   AX_COMMAND_REGISTRY,
   normalizeAxPolicy,
+  mapAxActivityKindToEventKind,
+  type PmxAxActivityKind,
   type PmxAxElicitation,
   type PmxAxModeRequest,
   type PmxAxMode,
@@ -334,13 +336,25 @@ class CanvasStateManager {
   // ── Change listeners (for MCP resource notifications) ──────
   private _changeListeners: ((type: CanvasChangeType) => void)[] = [];
 
-  /** 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 {
     this._changeListeners.push(cb);
+    return () => {
+      const i = this._changeListeners.indexOf(cb);
+      if (i >= 0) this._changeListeners.splice(i, 1);
+    };
   }
 
   private notifyChange(type: CanvasChangeType): void {
-    for (const cb of this._changeListeners) {
+    // Iterate a snapshot: a listener (e.g. a blocking-wait via onChange) may dispose
+    // itself synchronously here, and splicing the live array mid-iteration would skip
+    // the next listener for this notification.
+    for (const cb of [...this._changeListeners]) {
       try {
         cb(type);
       } catch (error) {
@@ -2049,6 +2063,19 @@ class CanvasStateManager {
     return applied.modeRequests.find((m) => m.id === id) ?? null;
   }
 
+  // ── Single-item AX readers (canvas-bound; for the blocking-wait endpoints) ──
+  getApproval(id: string): PmxAxApprovalGate | null {
+    return this.getAxState().approvalGates.find((g) => g.id === id) ?? null;
+  }
+
+  getElicitation(id: string): PmxAxElicitation | null {
+    return this.getAxState().elicitations.find((e) => e.id === id) ?? null;
+  }
+
+  getModeRequest(id: string): PmxAxModeRequest | null {
+    return this.getAxState().modeRequests.find((m) => m.id === id) ?? null;
+  }
+
   getCommandRegistry(): PmxAxCommandDescriptor[] {
     return listAxCommands();
   }
@@ -2171,6 +2198,107 @@ class CanvasStateManager {
     }
   }
 
+  /**
+   * 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 } {
+    const source = options.source ?? 'api';
+    const summary = input.summary ?? input.title;
+    const isFailure = input.kind === 'failure' || input.kind === 'error' || input.outcome === 'failure';
+    const isToolSuccess = input.kind === 'tool-result' && input.outcome === 'success';
+    const nodeIds = input.nodeIds ?? [];
+    const anchorNodeId = nodeIds.find((n) => this.nodes.has(n)) ?? null;
+
+    // (1) Always record the activity on the timeline (precise kind on data.activityKind).
+    const event = this.recordAxEvent(
+      {
+        kind: mapAxActivityKindToEventKind(input.kind),
+        summary: input.title,
+        detail: input.summary ?? null,
+        nodeIds,
+        // Caller data first so the canonical fields always win — a malformed/hostile
+        // payload can't overwrite activityKind/outcome/ref (which the docstring +
+        // reaction logic treat as authoritative).
+        data: {
+          ...(input.data ?? {}),
+          activityKind: input.kind,
+          ...(input.outcome ? { outcome: input.outcome } : {}),
+          ...(input.ref ? { ref: input.ref } : {}),
+        },
+      },
+      { source },
+    );
+
+    // (2) Resolve reactions: kind-driven defaults, overridable per call.
+    const r = input.reactions ?? {};
+    const wantWorkItem = r.workItem === false ? null : (r.workItem ?? (isFailure ? {} : null));
+    const wantEvidence = r.evidence === false
+      ? null
+      : (r.evidence ?? (isFailure ? { kind: 'logs' as PmxAxEvidenceKind } : isToolSuccess ? { kind: 'tool-result' as PmxAxEvidenceKind } : null));
+    const wantReview = r.review === false ? null : (r.review ?? (isFailure ? {} : null));
+
+    let workItem: PmxAxWorkItem | null = null;
+    if (wantWorkItem) {
+      workItem = this.addWorkItem(
+        { title: input.title, status: wantWorkItem.status ?? 'blocked', detail: wantWorkItem.detail ?? summary, nodeIds },
+        { source },
+      );
+    }
+
+    let evidence: PmxAxEvidence | null = null;
+    if (wantEvidence) {
+      evidence = this.addEvidence(
+        { kind: wantEvidence.kind ?? 'logs', title: input.title, body: wantEvidence.body ?? input.summary ?? null, ref: input.ref ?? null, nodeIds },
+        { source },
+      );
+    }
+
+    let review: PmxAxReviewAnnotation | null = null;
+    if (wantReview) {
+      const reviewNodeId = wantReview.nodeId ?? anchorNodeId;
+      // addReviewAnnotation returns null on a bad node anchor — that just skips the
+      // review; it never fails the whole ingest (the event + other reactions stand).
+      review = this.addReviewAnnotation(
+        {
+          body: summary,
+          kind: wantReview.kind ?? 'finding',
+          severity: wantReview.severity ?? 'error',
+          ...(wantReview.anchorType ? { anchorType: wantReview.anchorType } : {}),
+          ...(reviewNodeId ? { nodeId: reviewNodeId } : {}),
+          ...(input.ref ? { file: input.ref } : {}),
+        },
+        { source },
+      );
+    }
+
+    return { event, workItem, evidence, review };
+  }
+
   getAxEvents(q: AxTimelineQuery = {}): PmxAxEvent[] {
     return this._db ? loadAxEventsFromDB(this._db, q) : [];
   }

package/src/server/html-surface.ts

@@ -108,22 +108,60 @@ function injectIntoHead(html: string, content: string): string {
  * 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 function buildAxBridge(axToken: string, nodeId: string): string {
   const token = JSON.stringify(axToken);
   const node = JSON.stringify(nodeId);
   return `<script data-pmx-canvas-ax-bridge>
-const PMX_AX_TOKEN = ${token};
-const PMX_AX_NODE_ID = ${node};
-window.PMX_AX = window.PMX_AX || {};
-window.PMX_AX.emit = function (type, payload) {
-  window.parent.postMessage({
-    source: 'pmx-canvas-ax',
-    token: PMX_AX_TOKEN,
-    nodeId: PMX_AX_NODE_ID,
-    interaction: { type: String(type), payload: payload && typeof payload === 'object' ? payload : {} },
-  }, '*');
-};
+(function () {
+  const PMX_AX_TOKEN = ${token};
+  const PMX_AX_NODE_ID = ${node};
+  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);
+    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 : {} },
+    }, '*');
+    return new Promise(function (resolve) {
+      const timer = setTimeout(function () {
+        pending.delete(correlationId);
+        // Match the real reject shape ({ ok:false, status, code:string, error }) so a
+        // surface inspecting r.code/r.status sees a consistent type on timeout vs reject.
+        resolve({ ok: false, status: 504, code: 'ax-ack-timeout', error: 'ax-ack-timeout' });
+      }, 10000);
+      pending.set(correlationId, function (result) { clearTimeout(timer); resolve(result); });
+    });
+  };
+  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>`;
 }
 

package/src/server/index.ts

@@ -3,7 +3,9 @@ import { canvasState, IMAGE_MIME_MAP } from './canvas-state.js';
 import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout, ViewportState } from './canvas-state.js';
 import { buildCanvasAxContext } from './ax-context.js';
 import { applyAxInteraction, type AxInteractionInput, type AxInteractionPublicResult } from './ax-interaction.js';
+import { waitForAxResolution } from './ax-wait.js';
 import type {
+  PmxAxActivityKind,
   PmxAxApprovalGate,
   PmxAxCommandDescriptor,
   PmxAxContext,
@@ -512,8 +514,8 @@ export class PmxCanvas extends EventEmitter {
     return canvasState.getAxState();
   }
 
-  getAxContext(): PmxAxContext {
-    return buildCanvasAxContext();
+  getAxContext(options?: { consumer?: string }): PmxAxContext {
+    return buildCanvasAxContext(options?.consumer);
   }
 
   setAxFocus(nodeIds: string[], options?: { source?: PmxAxSource }): PmxAxFocusState {
@@ -710,6 +712,84 @@ export class PmxCanvas extends EventEmitter {
     return modeRequest;
   }
 
+  // ── Activity ingestion (primitive A — bidirectional board) ────────
+  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 } {
+    const result = canvasState.ingestActivity(input, { source: options?.source ?? 'sdk' });
+    emitPrimaryWorkbenchEvent('ax-event-created', { event: result.event });
+    if (result.workItem) emitPrimaryWorkbenchEvent('ax-state-changed', { workItem: result.workItem });
+    if (result.evidence) emitPrimaryWorkbenchEvent('ax-event-created', { evidence: result.evidence });
+    if (result.review) emitPrimaryWorkbenchEvent('ax-state-changed', { reviewAnnotation: result.review });
+    return result;
+  }
+
+  // ── Single-item readers + blocking waits (primitive D — gates that gate) ──
+  getApproval(id: string): PmxAxApprovalGate | null {
+    return canvasState.getApproval(id);
+  }
+
+  getElicitation(id: string): PmxAxElicitation | null {
+    return canvasState.getElicitation(id);
+  }
+
+  getModeRequest(id: string): PmxAxModeRequest | null {
+    return canvasState.getModeRequest(id);
+  }
+
+  async awaitApproval(
+    id: string,
+    options?: { timeoutMs?: number; signal?: AbortSignal },
+  ): Promise<{ approvalGate: PmxAxApprovalGate | null; pending: boolean }> {
+    const { value, pending } = await waitForAxResolution<PmxAxApprovalGate>({
+      read: () => canvasState.getApproval(id),
+      isResolved: (g) => g.status !== 'pending',
+      timeoutMs: options?.timeoutMs ?? 30000,
+      ...(options?.signal ? { signal: options.signal } : {}),
+    });
+    return { approvalGate: value, pending };
+  }
+
+  async awaitElicitation(
+    id: string,
+    options?: { timeoutMs?: number; signal?: AbortSignal },
+  ): Promise<{ elicitation: PmxAxElicitation | null; pending: boolean }> {
+    const { value, pending } = await waitForAxResolution<PmxAxElicitation>({
+      read: () => canvasState.getElicitation(id),
+      isResolved: (e) => e.status !== 'pending',
+      timeoutMs: options?.timeoutMs ?? 30000,
+      ...(options?.signal ? { signal: options.signal } : {}),
+    });
+    return { elicitation: value, pending };
+  }
+
+  async awaitMode(
+    id: string,
+    options?: { timeoutMs?: number; signal?: AbortSignal },
+  ): Promise<{ modeRequest: PmxAxModeRequest | null; pending: boolean }> {
+    const { value, pending } = await waitForAxResolution<PmxAxModeRequest>({
+      read: () => canvasState.getModeRequest(id),
+      isResolved: (m) => m.status !== 'pending',
+      timeoutMs: options?.timeoutMs ?? 30000,
+      ...(options?.signal ? { signal: options.signal } : {}),
+    });
+    return { modeRequest: value, pending };
+  }
+
   getCommandRegistry(): PmxAxCommandDescriptor[] {
     return canvasState.getCommandRegistry();
   }