pmx-canvas 0.4.4 → 0.4.6

package/src/client/state/intent-store.ts

@@ -23,8 +23,16 @@ export const hoveredIntentId = signal<string | null>(null);
 
 const SETTLE_MS = 480;
 const DISSOLVE_MS = 320;
+/**
+ * Minimum time a ghost stays in its forming state before a settle/dissolve
+ * plays. Fast agents (and every server auto-ghost) signal and settle within
+ * milliseconds — without this floor, correct ghost usage is imperceptible.
+ */
+export const MIN_FORMING_MS = 650;
 
 const exitTimers = new Map<string, ReturnType<typeof setTimeout>>();
+const phaseDelayTimers = new Map<string, ReturnType<typeof setTimeout>>();
+const formedAt = new Map<string, number>();
 let pruneTimer: ReturnType<typeof setInterval> | null = null;
 
 function writeIntents(next: Map<string, ClientIntent>): void {
@@ -40,9 +48,19 @@ function clearExitTimer(id: string): void {
   }
 }
 
+function clearPhaseDelay(id: string): void {
+  const timer = phaseDelayTimers.get(id);
+  if (timer) {
+    clearTimeout(timer);
+    phaseDelayTimers.delete(id);
+  }
+}
+
 /** A live `ax-intent` frame: (re)place the ghost in its forming state. */
 export function upsertIntent(intent: PmxAxIntent): void {
   clearExitTimer(intent.id);
+  clearPhaseDelay(intent.id);
+  if (!intents.value.has(intent.id)) formedAt.set(intent.id, Date.now());
   const next = new Map(intents.value);
   next.set(intent.id, { ...intent, phase: 'forming' });
   writeIntents(next);
@@ -50,6 +68,8 @@ export function upsertIntent(intent: PmxAxIntent): void {
 
 export function removeIntent(id: string): void {
   clearExitTimer(id);
+  clearPhaseDelay(id);
+  formedAt.delete(id);
   if (!intents.value.has(id)) return;
   const next = new Map(intents.value);
   next.delete(id);
@@ -69,19 +89,44 @@ function setPhase(id: string, phase: IntentPhase, ms: number, settledNodeId?: st
   );
 }
 
+/**
+ * Minimum-dwell wrapper: when a settle/dissolve arrives before the ghost has
+ * been visible for MIN_FORMING_MS, hold the forming state until the floor
+ * elapses, then play the exit phase.
+ */
+function setPhaseAfterDwell(id: string, phase: IntentPhase, ms: number, settledNodeId?: string): void {
+  clearPhaseDelay(id);
+  const elapsed = Date.now() - (formedAt.get(id) ?? 0);
+  const delay = Math.max(0, MIN_FORMING_MS - elapsed);
+  if (delay === 0) {
+    setPhase(id, phase, ms, settledNodeId);
+    return;
+  }
+  phaseDelayTimers.set(
+    id,
+    setTimeout(() => {
+      phaseDelayTimers.delete(id);
+      setPhase(id, phase, ms, settledNodeId);
+    }, delay),
+  );
+}
+
 /** Resolve a ghost into a real node — the settle morph, then removal. */
 export function settleIntent(id: string, settledNodeId?: string): void {
-  setPhase(id, 'settling', SETTLE_MS, settledNodeId);
+  setPhaseAfterDwell(id, 'settling', SETTLE_MS, settledNodeId);
 }
 
 /** Dissolve a ghost (expired / vetoed / evicted / abandoned), then remove it. */
 export function dissolveIntent(id: string): void {
-  setPhase(id, 'dissolving', DISSOLVE_MS);
+  setPhaseAfterDwell(id, 'dissolving', DISSOLVE_MS);
 }
 
 export function resetIntents(): void {
   for (const timer of exitTimers.values()) clearTimeout(timer);
   exitTimers.clear();
+  for (const timer of phaseDelayTimers.values()) clearTimeout(timer);
+  phaseDelayTimers.clear();
+  formedAt.clear();
   if (pruneTimer) {
     clearInterval(pruneTimer);
     pruneTimer = null;

package/src/client/state/node-factory.ts

@@ -34,6 +34,8 @@ export const DEFAULT_POSITIONS: Record<CanvasNodeState['type'], { x: number; y:
   ledger: { x: 1130, y: 520, w: 320, h: 280 },
   trace: { x: 40, y: 900, w: 200, h: 56 },
   file: { x: 380, y: 80, w: 720, h: 600 },
+  diff: { x: 380, y: 80, w: 640, h: 420 },
+  mermaid: { x: 380, y: 80, w: 640, h: 460 },
   image: { x: 380, y: 80, w: 720, h: 520 },
   html: { x: 380, y: 80, w: 720, h: 640 },
   group: { x: 220, y: 60, w: 840, h: 560 },

package/src/client/state/sse-bridge.ts

@@ -307,6 +307,8 @@ function isCanvasNodeType(value: unknown): value is CanvasNodeState['type'] {
     value === 'ledger' ||
     value === 'trace' ||
     value === 'file' ||
+    value === 'diff' ||
+    value === 'mermaid' ||
     value === 'image' ||
     value === 'html' ||
     value === 'group'
@@ -402,11 +404,37 @@ function parseCanvasAnnotation(raw: Record<string, unknown>): CanvasAnnotation |
 }
 
 // ── SSE event handlers ───────────────────────────────────────
+
+/**
+ * Stale-SPA guard (0.4.5 report Finding W): a long-lived host panel keeps its
+ * in-memory bundle across a daemon upgrade — SSE reconnects silently and the
+ * old client renders none of the new release's behavior. The boot HTML stamps
+ * the server version at page-serve time; when a `connected` frame reports a
+ * DIFFERENT version, the server was upgraded under this page — reload once to
+ * pick up the new bundle. Guarded per version so a broken stamp can't loop.
+ */
+const VERSION_RELOAD_KEY = 'pmx-canvas-version-reload';
+function reloadIfServerUpgraded(serverVersion: unknown): void {
+  if (typeof serverVersion !== 'string' || !serverVersion || serverVersion === 'unknown') return;
+  if (typeof window === 'undefined') return;
+  const bootVersion = (window as Window & { __PMX_BOOT_SERVER_VERSION?: unknown }).__PMX_BOOT_SERVER_VERSION;
+  if (typeof bootVersion !== 'string' || !bootVersion || bootVersion === 'unknown') return;
+  if (serverVersion === bootVersion) return;
+  try {
+    if (window.sessionStorage.getItem(VERSION_RELOAD_KEY) === serverVersion) return;
+    window.sessionStorage.setItem(VERSION_RELOAD_KEY, serverVersion);
+  } catch {
+    return; // No sessionStorage loop guard available — never risk a reload loop.
+  }
+  window.location.reload();
+}
+
 function handleConnected(data: Record<string, unknown>): void {
   sessionId.value = (data.sessionId as string) || '';
   connectionStatus.value = 'connected';
   // Reconnect marker for holders of server-minted URLs (Finding S).
   workbenchConnectionEpoch.value += 1;
+  reloadIfServerUpgraded(data.version);
   // A ?theme= session override (host-default theming) wins over the
   // server-global theme for THIS client only.
   if (typeof data.theme === 'string' && !themeOverrideActive()) {

package/src/client/theme/global.css

@@ -456,7 +456,7 @@
   --c-text-soft: #CBD3CA;
   --c-muted: #9CA49C;
   --c-dim: #626962;
-  --c-accent: #F34E3F;
+  --c-accent: #DFDFC1;
   --c-ok: #52C880;
   --c-warn: #E4C465;
   --c-warn-alt: #FFB300;
@@ -465,22 +465,22 @@
   --c-thinking: #BC8FB4;
   --c-subagent: #6CA0E0;
   --c-input-bg: #111311;
-  --c-dot-grid: rgba(243, 78, 63, 0.08);
+  --c-dot-grid: rgba(223, 223, 193, 0.08);
   --c-panel-overlay: rgba(11, 13, 11, 0.6);
   --c-panel-glass: rgba(23, 26, 23, 0.92);
   --c-shadow: rgba(0, 0, 0, 0.3);
   --c-shadow-heavy: rgba(0, 0, 0, 0.5);
-  --c-glow-accent: rgba(243, 78, 63, 0.15);
+  --c-glow-accent: rgba(223, 223, 193, 0.15);
   --c-surface-hover: rgba(255, 255, 255, 0.06);
   --c-surface-subtle: rgba(255, 255, 255, 0.03);
   --c-surface-th: rgba(255, 255, 255, 0.04);
-  --c-accent-8: rgba(243, 78, 63, 0.08);
-  --c-accent-10: rgba(243, 78, 63, 0.1);
-  --c-accent-12: rgba(243, 78, 63, 0.12);
-  --c-accent-15: rgba(243, 78, 63, 0.15);
-  --c-accent-25: rgba(243, 78, 63, 0.25);
-  --c-accent-30: rgba(243, 78, 63, 0.3);
-  --c-accent-40: rgba(243, 78, 63, 0.4);
+  --c-accent-8: rgba(223, 223, 193, 0.08);
+  --c-accent-10: rgba(223, 223, 193, 0.1);
+  --c-accent-12: rgba(223, 223, 193, 0.12);
+  --c-accent-15: rgba(223, 223, 193, 0.15);
+  --c-accent-25: rgba(223, 223, 193, 0.25);
+  --c-accent-30: rgba(223, 223, 193, 0.3);
+  --c-accent-40: rgba(223, 223, 193, 0.4);
   --c-ok-10: rgba(82, 200, 128, 0.1);
   --c-ok-12: rgba(82, 200, 128, 0.12);
   --c-ok-20: rgba(82, 200, 128, 0.2);
@@ -495,7 +495,7 @@
   --c-danger-12: rgba(214, 118, 112, 0.12);
   --c-line-30: rgba(39, 42, 39, 0.3);
   --c-contrast-fg: #0B0D0B;
-  --c-accent-hover: #F8695B;
+  --c-accent-hover: #EDEDDB;
   --c-warn-hover: #EBD087;
   --c-canvas-wash: linear-gradient(180deg, rgba(255, 255, 255, 0.02), rgba(0, 0, 0, 0));
   --c-annotation: #F1F7F0;
@@ -669,6 +669,29 @@ body,
   flex-shrink: 0;
 }
 
+.canvas-node .node-ax-status {
+  font-size: calc(9px * var(--node-chrome-scale, 1));
+  padding: calc(1px * var(--node-chrome-scale, 1)) calc(6px * var(--node-chrome-scale, 1));
+  border-radius: calc(4px * var(--node-chrome-scale, 1));
+  background: var(--c-panel-overlay);
+  color: var(--c-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  flex-shrink: 0;
+}
+
+.canvas-node .node-ax-status-in-progress {
+  color: var(--c-accent);
+}
+
+.canvas-node .node-ax-status-done {
+  color: var(--c-ok);
+}
+
+.canvas-node .node-ax-status-blocked {
+  color: var(--c-warn);
+}
+
 .canvas-node .node-controls {
   display: flex;
   align-items: center;
@@ -1872,6 +1895,74 @@ html.is-node-resizing .ext-app-preview-catcher {
   }
 }
 
+/* Diff nodes — unified diff viewer with per-file sections */
+.diff-node {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  height: 100%;
+  overflow: auto;
+  font-family: var(--mono);
+  font-size: 12px;
+  color: var(--c-text);
+}
+
+.diff-node.diff-node-empty {
+  align-items: center;
+  justify-content: center;
+  color: var(--c-muted);
+}
+
+.diff-node .diff-file {
+  border: 1px solid var(--c-line);
+  border-radius: 6px;
+  overflow: hidden;
+  flex-shrink: 0;
+}
+
+.diff-node .diff-file-header {
+  padding: 4px 8px;
+  background: var(--c-panel-overlay);
+  border-bottom: 1px solid var(--c-line);
+  color: var(--c-text-soft);
+  font-weight: 600;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.diff-node .diff-lines {
+  margin: 0;
+  padding: 4px 0;
+  overflow-x: auto;
+  font-family: inherit;
+  font-size: inherit;
+  line-height: 1.5;
+}
+
+.diff-node .diff-lines > div {
+  padding: 0 8px;
+  white-space: pre;
+}
+
+.diff-node .diff-hunk {
+  color: var(--c-muted);
+}
+
+.diff-node .diff-line-add {
+  color: var(--c-ok);
+  background: var(--c-ok-10);
+}
+
+.diff-node .diff-line-remove {
+  color: var(--c-danger);
+  background: var(--c-danger-12);
+}
+
+.diff-node .diff-line-context {
+  color: var(--c-text-soft);
+}
+
 /* Docked node — compact toolbar-flanking panel */
 .docked-node {
   min-width: 200px;
@@ -3955,6 +4046,19 @@ button.welcome-hint:hover {
   display: contents;
 }
 
+/* Auto-ghosts (server-synthesized for unlinked agent mutations) read lighter
+   than a deliberate canvas_intent signal: desaturated, dotted, no veto —
+   the opacity drop lives in ghostOpacity() (inline style). */
+.intent-ghost.is-auto {
+  filter: saturate(0.7);
+  border-style: dotted;
+}
+
+.intent-ghost.is-auto .intent-ghost-titlebar,
+.intent-ghost.is-auto .intent-chip {
+  border-style: dotted;
+}
+
 .intent-ghost {
   position: absolute;
   pointer-events: none;

package/src/client/theme/surface-theme.css

@@ -291,7 +291,7 @@
   --c-text-soft: #CBD3CA;
   --c-muted: #9CA49C;
   --c-dim: #626962;
-  --c-accent: #F34E3F;
+  --c-accent: #DFDFC1;
   --c-ok: #52C880;
   --c-warn: #E4C465;
   --c-warn-alt: #FFB300;
@@ -307,7 +307,7 @@
   --color-text-secondary: #CBD3CA;
   --color-text-muted: #9CA49C;
   --color-text-dim: #626962;
-  --color-accent: #F34E3F;
+  --color-accent: #DFDFC1;
   --color-success: #52C880;
   --color-warning: #E4C465;
   --color-danger: #D67670;

package/src/client/types.ts

@@ -21,6 +21,8 @@ export interface CanvasNodeState {
     | 'ledger'
     | 'trace'
     | 'file'
+    | 'diff'
+    | 'mermaid'
     | 'image'
     | 'html'
     | 'group';
@@ -77,6 +79,8 @@ export const TYPE_LABELS: Record<CanvasNodeState['type'], string> = {
   ledger: 'LOG',
   trace: 'TRACE',
   file: 'FILE',
+  diff: 'DIFF',
+  mermaid: 'MERMAID',
   image: 'IMG',
   html: 'HTML',
   group: 'GROUP',
@@ -92,6 +96,8 @@ export const EXPANDABLE_TYPES = new Set<CanvasNodeState['type']>([
   'context',
   'ledger',
   'file',
+  'diff',
+  'mermaid',
   'image',
   'html',
 ]);

package/src/mcp/server.ts

@@ -26,7 +26,8 @@ import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { canvasState, describeCanvasSchema } from '../server/index.js';
+import { AX_SOURCES } from '../server/operations/ops/ax-shared.js';
+import { canvasState, describeCanvasSchema, stopCanvasServer } from '../server/index.js';
 import { AX_INTERACTION_TYPES } from '../server/ax-interaction.js';
 import { buildPendingAxActivity } from '../server/ax-state.js';
 import { registerOperationTools, registerCompositeTools } from '../server/operations/index.js';
@@ -253,10 +254,7 @@ export async function startMcpServer(): Promise<void> {
         .describe('Type-specific payload, e.g. {"title":"..."} for ax.work.create.'),
       sourceSurface: z.enum(['native-node', 'json-render', 'html-node', 'mcp-app', 'adapter']).optional(),
       correlationId: z.string().optional(),
-      source: z
-        .enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
-        .optional()
-        .describe('Optional host/source label. Defaults to mcp.'),
+      source: z.enum(AX_SOURCES).optional().describe('Optional host/source label. Defaults to mcp.'),
     },
     async ({ type, sourceNodeId, payload, sourceSurface, correlationId, source }) => {
       try {
@@ -345,7 +343,7 @@ export async function startMcpServer(): Promise<void> {
         })
         .optional()
         .describe('Override or suppress the kind-driven default reactions.'),
-      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system']).optional(),
+      source: z.enum(AX_SOURCES).optional(),
     },
     async ({ kind, title, summary, outcome, ref, nodeIds, data, reactions, source }) => {
       try {
@@ -886,6 +884,24 @@ export async function startMcpServer(): Promise<void> {
   // Connect via stdio
   const transport = new StdioServerTransport();
   await server.connect(transport);
+
+  // Exit when the stdio channel closes (0.4.5 report Finding Y): without this,
+  // a client that completes the official close sequence leaves this process
+  // orphaned — the auto-started canvas server and its timers keep the event
+  // loop alive forever. stopCanvasServer() checkpoints the SQLite DB before
+  // exit and is a no-op when this process only attached to a remote daemon.
+  const shutdown = (): void => {
+    try {
+      stopCanvasServer();
+    } catch {
+      // Exit regardless — a failed cleanup must not resurrect the orphan.
+    }
+    process.exit(0);
+  };
+  server.server.onclose = shutdown;
+  process.stdin.on('end', shutdown);
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
 }
 
 // Allow direct execution: bun run src/mcp/server.ts

package/src/server/ax-interaction.ts

@@ -102,6 +102,12 @@ export const DEFAULT_NODE_AX_CAPABILITIES: Record<CanvasNodeType, NodeAxCapabili
     'notify-agent',
   ),
   file: caps(true, ['ax.evidence.add', 'ax.review.add', 'ax.focus.set', 'ax.event.record']),
+  diff: caps(true, ['ax.evidence.add', 'ax.review.add', 'ax.focus.set', 'ax.event.record']),
+  mermaid: caps(
+    true,
+    ['ax.steer', 'ax.work.create', 'ax.evidence.add', 'ax.command.invoke', 'ax.event.record'],
+    'notify-agent',
+  ),
   'json-render': caps(true, [
     'ax.work.create',
     'ax.work.update',

package/src/server/ax-state-manager.ts

@@ -239,7 +239,13 @@ export class AxStateManager {
   }
 
   addWorkItem(
-    input: { title: string; status?: PmxAxWorkItemStatus; detail?: string | null; nodeIds?: string[] },
+    input: {
+      title: string;
+      status?: PmxAxWorkItemStatus;
+      detail?: string | null;
+      nodeIds?: string[];
+      agentId?: string | null;
+    },
     options: { source?: PmxAxSource } = {},
   ): PmxAxWorkItem {
     const oldAxState = this.getAxState();
@@ -267,7 +273,13 @@ export class AxStateManager {
 
   updateWorkItem(
     id: string,
-    patch: { title?: string; status?: PmxAxWorkItemStatus; detail?: string | null; nodeIds?: string[] },
+    patch: {
+      title?: string;
+      status?: PmxAxWorkItemStatus;
+      detail?: string | null;
+      nodeIds?: string[];
+      agentId?: string | null;
+    },
     options: { source?: PmxAxSource } = {},
   ): PmxAxWorkItem | null {
     const oldAxState = this.getAxState();
@@ -280,6 +292,7 @@ export class AxStateManager {
       ...(patch.status !== undefined ? { status: patch.status } : {}),
       ...(patch.detail !== undefined ? { detail: patch.detail } : {}),
       ...(patch.nodeIds !== undefined ? { nodeIds: patch.nodeIds.filter((n) => validNodeIds.has(n)) } : {}),
+      ...(patch.agentId !== undefined ? { agentId: patch.agentId } : {}),
       updatedAt: new Date().toISOString(),
       source: options.source ?? existing.source,
     };
@@ -703,9 +716,9 @@ export class AxStateManager {
       nodeIds?: string[];
       data?: Record<string, unknown> | null;
     },
-    options: { source?: PmxAxSource } = {},
+    options: { source?: PmxAxSource; agentId?: string | null } = {},
   ): PmxAxEvent {
-    const draft = createAxEvent(input, options.source ?? 'api');
+    const draft = createAxEvent(input, options.source ?? 'api', options.agentId ?? null);
     const db = this.deps.getDb();
     if (db) {
       try {
@@ -746,8 +759,16 @@ export class AxStateManager {
     return { ...draft, seq: 0 };
   }
 
-  recordSteeringMessage(message: string, options: { source?: PmxAxSource } = {}): PmxAxSteeringMessage {
-    const draft = createAxSteeringMessage(message, options.source ?? 'api');
+  recordSteeringMessage(
+    message: string,
+    options: { source?: PmxAxSource; agentId?: string | null; target?: string | null } = {},
+  ): PmxAxSteeringMessage {
+    const draft = createAxSteeringMessage(
+      message,
+      options.source ?? 'api',
+      options.agentId ?? null,
+      options.target ?? null,
+    );
     const db = this.deps.getDb();
     if (db) {
       try {

package/src/server/ax-state.ts

@@ -1,7 +1,7 @@
 import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
 import type { AgentContextNode } from './agent-context.js';
 
-export type PmxAxSource = 'agent' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';
+export type PmxAxSource = 'agent' | 'amp' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';
 
 export interface PmxAxFocusState {
   nodeIds: string[];
@@ -39,6 +39,7 @@ export interface PmxAxWorkItem {
   createdAt: string;
   updatedAt: string;
   source: PmxAxSource | null;
+  agentId: string | null;
 }
 
 export interface PmxAxApprovalGate {
@@ -87,6 +88,7 @@ export interface PmxAxEvent {
   data: Record<string, unknown> | null;
   createdAt: string;
   source: PmxAxSource | null;
+  agentId: string | null;
 }
 
 export interface PmxAxEvidence {
@@ -109,6 +111,9 @@ export interface PmxAxSteeringMessage {
   delivered: boolean;
   createdAt: string;
   source: PmxAxSource | null;
+  agentId: string | null;
+  /** The agentId/consumer this steer is addressed to; null = broadcast to all consumers. */
+  target: string | null;
 }
 
 // ── Host/session capability (own table; reported by adapters) ──────
@@ -269,7 +274,18 @@ export function buildPendingAxActivity(state: PmxAxState, consumer?: string): Pe
   return out;
 }
 
-const AX_SOURCES = new Set<PmxAxSource>(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system']);
+const AX_SOURCES = new Set<PmxAxSource>([
+  'agent',
+  'amp',
+  'api',
+  'browser',
+  'cli',
+  'codex',
+  'copilot',
+  'mcp',
+  'sdk',
+  'system',
+]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -622,6 +638,7 @@ export function normalizeAxWorkItem(input: unknown, validNodeIds?: Set<string>):
     createdAt,
     updatedAt: normalizeTimestamp(input.updatedAt) ?? createdAt,
     source: normalizeSource(input.source),
+    agentId: optionalString(input.agentId),
   };
 }
 
@@ -715,6 +732,7 @@ export function normalizeAxEvent(input: unknown): PmxAxEvent | null {
     data: boundedRecord(input.data),
     createdAt: normalizeTimestamp(input.createdAt) ?? nowIso(),
     source: normalizeSource(input.source),
+    agentId: optionalString(input.agentId),
   };
 }
 
@@ -745,12 +763,20 @@ export function normalizeAxSteeringMessage(input: unknown): PmxAxSteeringMessage
     delivered: input.delivered === true,
     createdAt: normalizeTimestamp(input.createdAt) ?? nowIso(),
     source: normalizeSource(input.source),
+    agentId: optionalString(input.agentId),
+    target: optionalString(input.target),
   };
 }
 
 // ── Factories ──────────────────────────────────────────────────────
 export function createAxWorkItem(
-  input: { title: string; status?: PmxAxWorkItemStatus; detail?: string | null; nodeIds?: string[] },
+  input: {
+    title: string;
+    status?: PmxAxWorkItemStatus;
+    detail?: string | null;
+    nodeIds?: string[];
+    agentId?: string | null;
+  },
   source: PmxAxSource | null,
   validNodeIds?: Set<string>,
 ): PmxAxWorkItem {
@@ -764,6 +790,7 @@ export function createAxWorkItem(
     createdAt: now,
     updatedAt: now,
     source,
+    agentId: input.agentId ?? null,
   };
 }
 
@@ -829,6 +856,7 @@ export function createAxEvent(
     data?: Record<string, unknown> | null;
   },
   source: PmxAxSource | null,
+  agentId: string | null = null,
 ): Omit<PmxAxEvent, 'seq'> {
   return {
     id: axId('evt'),
@@ -839,6 +867,7 @@ export function createAxEvent(
     data: input.data ?? null,
     createdAt: nowIso(),
     source,
+    agentId,
   };
 }
 
@@ -869,6 +898,8 @@ export function createAxEvidence(
 export function createAxSteeringMessage(
   message: string,
   source: PmxAxSource | null,
+  agentId: string | null = null,
+  target: string | null = null,
 ): Omit<PmxAxSteeringMessage, 'seq'> {
   return {
     id: axId('steer'),
@@ -876,6 +907,8 @@ export function createAxSteeringMessage(
     delivered: false,
     createdAt: nowIso(),
     source,
+    agentId,
+    target,
   };
 }