pmx-canvas 0.4.8 → 0.5.0

package/src/server/html-surface.ts

@@ -218,8 +218,17 @@ function escapeSurfaceHtml(value: string): string {
  * of the main SPA bundle). Escaping is mandatory: the source is arbitrary node
  * data and must not be parsed as markup.
  */
-export function buildMermaidSurfaceHtml(source: string): string {
-  return `<pre class="mermaid-source" style="display:none">${escapeSurfaceHtml(source)}</pre><script src="/canvas/mermaid-entry.js"></script>`;
+export function buildMermaidSurfaceHtml(source: string, inlineEntry?: string | null): string {
+  // srcdoc-rendered surfaces in hosts that block sub-frame subresources (the
+  // Claude Code desktop browser blocks the script request too, not just the
+  // frame document) get the renderer embedded as a data: URL — no network
+  // request for the host to block, and base64 has no `<` for the HTML script
+  // parser to trip on (a 3.5MB bundle inlined as literal script text hits the
+  // `<!--` script-data-escaped states and renders as page text).
+  const entry = inlineEntry
+    ? `<script src="data:text/javascript;charset=utf-8;base64,${Buffer.from(inlineEntry, 'utf-8').toString('base64')}"></script>`
+    : '<script src="/canvas/mermaid-entry.js"></script>';
+  return `<pre class="mermaid-source" style="display:none">${escapeSurfaceHtml(source)}</pre>${entry}`;
 }
 
 export interface HtmlSurfaceOptions {

package/src/server/human-presence.ts

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+import {
+  HUMAN_GRAB_TTL_MS,
+  HUMAN_PRESENCE_TTL_MS,
+  type HumanPresence,
+  type HumanPresenceSnapshot,
+  MAX_HUMANS,
+} from '../shared/human-presence.js';
+import { OperationError } from './operations/types.js';
+
+/**
+ * Registry of open workbench tabs (rail-chrome-v2 phase 8). Fed by the
+ * browser's own `human.presence.set` heartbeats; broadcast as one coalesced
+ * `human-presence` SSE frame on every change including expiry, so clients
+ * never run their own expiry timers. `lockedNodes()` is the edit lock the
+ * operation registry consults for agent writes (user wins).
+ */
+export const HUMAN_PRESENCE_SHAPE = {
+  clientId: z.string().min(1).max(64),
+  name: z.string().min(1).max(40).optional(),
+  cursor: z.object({ x: z.number().finite(), y: z.number().finite() }).nullable().optional(),
+  grabbingNodeId: z.string().max(200).nullable().optional(),
+  /** Explicit leave (tab closing): drop the presence now. */
+  left: z.boolean().optional(),
+};
+const presenceSchema = z.object(HUMAN_PRESENCE_SHAPE);
+
+interface Stored extends HumanPresence {
+  lastSeenMs: number;
+  grabSinceMs: number | null;
+}
+
+type Emitter = (event: string, payload: Record<string, unknown>) => void;
+
+export class HumanPresenceRegistry {
+  private readonly humans = new Map<string, Stored>();
+  private emit: Emitter = () => {};
+  private sweepTimer: ReturnType<typeof setInterval> | null = null;
+  private emitTimer: ReturnType<typeof setTimeout> | null = null;
+
+  setEmitter(emitter: Emitter | null): void {
+    this.emit = emitter ?? (() => {});
+  }
+
+  set(raw: unknown, now = Date.now()): HumanPresence | null {
+    const parsed = presenceSchema.safeParse(raw);
+    if (!parsed.success) {
+      throw new OperationError(
+        `Invalid human presence: ${parsed.error.issues.map((issue) => issue.message).join('; ')}`,
+      );
+    }
+    const input = parsed.data;
+    if (input.left) {
+      if (this.humans.delete(input.clientId)) this.scheduleEmit();
+      this.maybeStopSweeper();
+      return null;
+    }
+    const existing = this.humans.get(input.clientId);
+    const stored: Stored = existing ?? {
+      clientId: input.clientId,
+      name: input.name ?? 'Human',
+      cursor: null,
+      grabbingNodeId: null,
+      lastSeenAt: new Date(now).toISOString(),
+      lastSeenMs: now,
+      grabSinceMs: null,
+    };
+    stored.lastSeenMs = now;
+    stored.lastSeenAt = new Date(now).toISOString();
+    if (input.name) stored.name = input.name;
+    if (input.cursor !== undefined) stored.cursor = input.cursor;
+    if (input.grabbingNodeId !== undefined) {
+      if (input.grabbingNodeId !== stored.grabbingNodeId) stored.grabSinceMs = input.grabbingNodeId ? now : null;
+      else if (input.grabbingNodeId) stored.grabSinceMs = now; // renewed
+      stored.grabbingNodeId = input.grabbingNodeId;
+    }
+    this.humans.set(input.clientId, stored);
+    while (this.humans.size > MAX_HUMANS) {
+      const oldest = [...this.humans.values()].sort((a, b) => a.lastSeenMs - b.lastSeenMs)[0];
+      if (!oldest) break;
+      this.humans.delete(oldest.clientId);
+    }
+    this.ensureSweeper();
+    this.scheduleEmit();
+    return this.publicView(stored);
+  }
+
+  snapshot(now = Date.now()): HumanPresenceSnapshot {
+    this.sweep(now, { emit: false });
+    return { humans: [...this.humans.values()].map((stored) => this.publicView(stored)) };
+  }
+
+  /** Nodes a human is holding right now → that human's name. The edit lock. */
+  lockedNodes(now = Date.now()): Map<string, string> {
+    const locked = new Map<string, string>();
+    for (const human of this.humans.values()) {
+      if (human.grabbingNodeId && human.grabSinceMs !== null && now - human.grabSinceMs <= HUMAN_GRAB_TTL_MS) {
+        locked.set(human.grabbingNodeId, human.name);
+      }
+    }
+    return locked;
+  }
+
+  reset(): void {
+    this.humans.clear();
+    if (this.emitTimer) {
+      clearTimeout(this.emitTimer);
+      this.emitTimer = null;
+    }
+    this.maybeStopSweeper();
+  }
+
+  private publicView(stored: Stored): HumanPresence {
+    const { lastSeenMs: _lastSeenMs, grabSinceMs, ...human } = stored;
+    // An expired grab reads as released even before the sweep drops it.
+    const grabbing =
+      human.grabbingNodeId && grabSinceMs !== null && Date.now() - grabSinceMs <= HUMAN_GRAB_TTL_MS
+        ? human.grabbingNodeId
+        : null;
+    return { ...human, grabbingNodeId: grabbing };
+  }
+
+  private sweep(now = Date.now(), options: { emit?: boolean } = {}): void {
+    let changed = false;
+    for (const [key, human] of this.humans) {
+      if (human.lastSeenMs + HUMAN_PRESENCE_TTL_MS <= now) {
+        this.humans.delete(key);
+        changed = true;
+      } else if (human.grabbingNodeId && human.grabSinceMs !== null && now - human.grabSinceMs > HUMAN_GRAB_TTL_MS) {
+        human.grabbingNodeId = null;
+        human.grabSinceMs = null;
+        changed = true;
+      }
+    }
+    if (changed && options.emit !== false) this.scheduleEmit();
+    this.maybeStopSweeper();
+  }
+
+  private scheduleEmit(): void {
+    if (this.emitTimer) return;
+    this.emitTimer = setTimeout(() => {
+      this.emitTimer = null;
+      this.emit('human-presence', this.snapshot() as unknown as Record<string, unknown>);
+    }, 16);
+  }
+
+  private ensureSweeper(): void {
+    if (this.sweepTimer) return;
+    this.sweepTimer = setInterval(() => this.sweep(), 1000);
+  }
+
+  private maybeStopSweeper(): void {
+    if (this.humans.size === 0 && this.sweepTimer) {
+      clearInterval(this.sweepTimer);
+      this.sweepTimer = null;
+    }
+  }
+}
+
+export const humanPresence = new HumanPresenceRegistry();

package/src/server/index.ts

@@ -1,4 +1,7 @@
 import { EventEmitter } from 'node:events';
+import { agentPresence } from './agent-presence.js';
+import { checkFenceTarget, type FenceTarget } from './scope-fence.js';
+import type { AgentPhase, AgentPresence, AgentPresenceSnapshot } from '../shared/agent-presence.js';
 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';
@@ -132,6 +135,31 @@ function toSdkNode(node: CanvasNodeState): SdkCanvasNode {
   return { ...serializeCanvasNode(node), nodeId: node.id };
 }
 
+/**
+ * The SDK bypasses the operation registry, so each mutation describes what it
+ * writes to the same fence core the registry uses (scope-fence.ts). Reads and
+ * presence/AX calls are never fenced.
+ */
+function assertInsideFence(opName: string, target: FenceTarget): void {
+  const refusal = checkFenceTarget(target, opName);
+  if (refusal) throw new Error(`Outside the agent scope: ${refusal}`);
+}
+
+function createTarget(input: { x?: number; y?: number }, nodeIds: string[] = []): FenceTarget {
+  return typeof input.x === 'number' && typeof input.y === 'number'
+    ? { points: [{ x: input.x, y: input.y }], nodeIds }
+    : { unplacedCreate: true, nodeIds };
+}
+
+/** Presence `detail` for SDK writes, by the intent kind the wrapper commits. */
+const SDK_PRESENCE_DETAIL: Record<PmxAxIntentKind, string> = {
+  create: 'node.add',
+  move: 'node.move',
+  edit: 'node.update',
+  remove: 'node.remove',
+  connect: 'edge.add',
+};
+
 export class PmxCanvas extends EventEmitter {
   private _port: number;
   private _server: string | null = null;
@@ -146,6 +174,27 @@ export class PmxCanvas extends EventEmitter {
     allowedKinds: readonly PmxAxIntentKind[],
     mutate: () => T,
     settledNodeId: (result: T) => string | undefined,
+  ): T {
+    const result = this.runIntentCommitInner(intentId, allowedKinds, mutate, settledNodeId);
+    // SDK writes bypass executeOperation, so they register agent presence
+    // here — the same derived `tooling` + focus-node touch the HTTP/MCP
+    // transports get, attributed to the attached session by the registry.
+    const focusNodeId = settledNodeId(result);
+    agentPresence.touch({
+      source: 'sdk',
+      phase: 'tooling',
+      detail: SDK_PRESENCE_DETAIL[allowedKinds[0] ?? 'edit'],
+      ...(focusNodeId ? { focusNodeId } : {}),
+      op: true,
+    });
+    return result;
+  }
+
+  private runIntentCommitInner<T>(
+    intentId: string | undefined,
+    allowedKinds: readonly PmxAxIntentKind[],
+    mutate: () => T,
+    settledNodeId: (result: T) => string | undefined,
   ): T {
     if (intentId === undefined) return mutate();
     intentRegistry.beginCommit(intentId, allowedKinds);
@@ -246,6 +295,10 @@ export class PmxCanvas extends EventEmitter {
     height?: number;
     strictSize?: boolean;
   }): SdkCanvasNode {
+    assertInsideFence(
+      'node.add',
+      createTarget(input, input.type === 'group' ? (input.childIds ?? input.children ?? []) : []),
+    );
     return this.runIntentCommit(
       input.intentId,
       ['create'],
@@ -296,6 +349,7 @@ export class PmxCanvas extends EventEmitter {
     height?: number;
     strictSize?: boolean;
   }): Promise<{ ok: boolean; id: string; error?: string; fetch: { ok: boolean; error?: string } }> {
+    assertInsideFence('node.add', createTarget(input));
     const mutate = async () => {
       const { id } = addCanvasNode({
         type: 'webpage',
@@ -330,6 +384,7 @@ export class PmxCanvas extends EventEmitter {
   }
 
   updateNode(id: string, patch: Partial<CanvasNodeState> & Record<string, unknown>): void {
+    assertInsideFence('node.update', { nodeIds: [id] });
     const intentId = typeof patch.intentId === 'string' ? patch.intentId : undefined;
     this.runIntentCommit(
       intentId,
@@ -354,6 +409,7 @@ export class PmxCanvas extends EventEmitter {
 
   /** Remove a node. Missing id throws (plan-005 unifies this across surfaces). */
   removeNode(id: string, options?: { intentId?: string }): void {
+    assertInsideFence('node.remove', { nodeIds: [id] });
     this.runIntentCommit(
       options?.intentId,
       ['remove'],
@@ -382,6 +438,7 @@ export class PmxCanvas extends EventEmitter {
     style?: CanvasEdge['style'];
     animated?: boolean;
   }): string {
+    assertInsideFence('edge.add', { nodeIds: [input.from ?? '', input.to ?? ''] });
     return this.runIntentCommit(
       input.intentId,
       ['connect'],
@@ -412,6 +469,8 @@ export class PmxCanvas extends EventEmitter {
   }
 
   removeEdge(id: string): void {
+    const edge = canvasState.getEdges().find((entry) => entry.id === id);
+    if (edge) assertInsideFence('edge.remove', { nodeIds: [edge.from, edge.to] });
     removeCanvasEdge(id);
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   }
@@ -431,6 +490,7 @@ export class PmxCanvas extends EventEmitter {
     color?: string;
     childLayout?: 'grid' | 'column' | 'flow';
   }): string {
+    assertInsideFence('group.create', { nodeIds: input.childIds ?? [] });
     return this.runIntentCommit(
       input.intentId,
       ['create'],
@@ -449,6 +509,7 @@ export class PmxCanvas extends EventEmitter {
     childIds: string[],
     options?: { childLayout?: 'grid' | 'column' | 'flow'; intentId?: string },
   ): boolean {
+    assertInsideFence('group.add', { nodeIds: [groupId, ...childIds] });
     return this.runIntentCommit(
       options?.intentId,
       ['edit'],
@@ -466,8 +527,9 @@ export class PmxCanvas extends EventEmitter {
     );
   }
 
-  /** Remove all children from a group (the group node remains). */
+  /** Dissolve a group: children released (into the enclosing group when nested), frame removed — one undo step. */
   ungroupNodes(groupId: string, options?: { intentId?: string }): boolean {
+    assertInsideFence('group.remove', { nodeIds: [groupId] });
     return this.runIntentCommit(
       options?.intentId,
       ['edit'],
@@ -486,6 +548,7 @@ export class PmxCanvas extends EventEmitter {
   }
 
   clear(): void {
+    assertInsideFence('canvas.clear', { boardWide: true });
     for (const node of canvasState.getLayout().nodes) {
       if (node.type !== 'mcp-app') continue;
       const sessionId = typeof node.data.appSessionId === 'string' ? node.data.appSessionId : '';
@@ -496,6 +559,7 @@ export class PmxCanvas extends EventEmitter {
   }
 
   arrange(layout?: 'grid' | 'column' | 'flow'): void {
+    assertInsideFence('arrange', { boardWide: true });
     arrangeCanvasNodes(layout ?? 'grid');
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
   }
@@ -562,8 +626,8 @@ export class PmxCanvas extends EventEmitter {
     return steering;
   }
 
-  markSteeringDelivered(id: string): boolean {
-    const ok = canvasState.markSteeringDelivered(id);
+  markSteeringDelivered(id: string, consumer?: string | null): boolean {
+    const ok = canvasState.markSteeringDelivered(id, consumer);
     if (ok) emitPrimaryWorkbenchEvent('ax-event-created', { steeringDelivered: id });
     return ok;
   }
@@ -667,6 +731,16 @@ export class PmxCanvas extends EventEmitter {
     return approvalGate;
   }
 
+  /** Reopen a resolved (typically auto-held) approval gate with a fresh TTL. */
+  reopenApproval(id: string, options?: { ttlMs?: number; source?: PmxAxSource }): PmxAxApprovalGate | null {
+    const approvalGate = canvasState.reopenApproval(id, {
+      ...(options?.ttlMs !== undefined ? { ttlMs: options.ttlMs } : {}),
+      source: options?.source ?? 'sdk',
+    });
+    if (approvalGate) emitPrimaryWorkbenchEvent('ax-state-changed', { approvalGate });
+    return approvalGate;
+  }
+
   addEvidence(
     input: {
       kind: PmxAxEvidenceKind;
@@ -726,6 +800,30 @@ export class PmxCanvas extends EventEmitter {
     return host;
   }
 
+  /** Who is writing to this board right now, their phase, and the context budget. */
+  getAgentPresence(): AgentPresenceSnapshot {
+    return agentPresence.snapshot();
+  }
+
+  /**
+   * Update this SDK caller's presence (rail-chrome-v2 phase 2): phase, detail,
+   * focus node, cursor, and `attached` (true starts a session, false ends it).
+   */
+  setAgentPresence(
+    input: {
+      agentId?: string | null;
+      label?: string;
+      phase?: AgentPhase;
+      detail?: string | null;
+      focusNodeId?: string | null;
+      cursor?: { x: number; y: number } | null;
+      attached?: boolean;
+    },
+    options?: { source?: PmxAxSource },
+  ): AgentPresence {
+    return agentPresence.set(input, options?.source ?? 'sdk');
+  }
+
   listElicitations(): PmxAxElicitation[] {
     return canvasState.getElicitations();
   }
@@ -957,9 +1055,9 @@ export class PmxCanvas extends EventEmitter {
       position?: { x: number; y: number };
       size?: { width: number; height: number };
       collapsed?: boolean;
-      dockPosition?: 'left' | 'right' | null;
     }>,
   ): { applied: number; skipped: number } {
+    assertInsideFence('node.update', { nodeIds: updates.map((update) => update.id) });
     return applyCanvasNodeUpdates(updates);
   }
 
@@ -978,6 +1076,7 @@ export class PmxCanvas extends EventEmitter {
   }
 
   async restoreSnapshot(id: string): Promise<{ ok: boolean }> {
+    assertInsideFence('snapshot.restore', { boardWide: true });
     const result = await restoreCanvasSnapshot(id);
     if (result.ok) {
       emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
@@ -1076,6 +1175,7 @@ export class PmxCanvas extends EventEmitter {
     url: string;
     spec: JsonRenderSpec;
   } {
+    assertInsideFence('jsonrender.add', createTarget(input));
     return this.runIntentCommit(
       input.intentId,
       ['create'],
@@ -1160,6 +1260,7 @@ export class PmxCanvas extends EventEmitter {
      *  the html capability ceiling server-side; cannot escalate. */
     axCapabilities?: { enabled?: boolean; allowed?: string[] };
   }): SdkCanvasNode {
+    assertInsideFence('node.add', createTarget(input));
     return this.runIntentCommit(
       input.intentId,
       ['create'],
@@ -1206,6 +1307,7 @@ export class PmxCanvas extends EventEmitter {
     height?: number;
     strictSize?: boolean;
   }): { id: string; kind: HtmlPrimitiveKind; title: string; htmlBytes: number } {
+    assertInsideFence('node.add', createTarget(input));
     return this.runIntentCommit(
       input.intentId,
       ['create'],
@@ -1243,6 +1345,7 @@ export class PmxCanvas extends EventEmitter {
   }
 
   addGraphNode(input: GraphNodeInput & { intentId?: string }): { id: string; url: string; spec: JsonRenderSpec } {
+    assertInsideFence('graph.add', createTarget(input));
     return this.runIntentCommit(
       input.intentId,
       ['create'],

package/src/server/intent-registry.ts

@@ -223,6 +223,19 @@ export class IntentRegistry {
    * synchronous: once this method has accepted the intent, a later veto cannot
    * race in between the check and the mutation.
    */
+  /**
+   * How a linked commit would fare right now. 'absent' = the ghost expired
+   * quietly (TTL sweep) with no veto — the mutation should proceed UNLINKED
+   * instead of failing: a slow spawn is not a human "no", and inside a batch
+   * the 409 poisoned every sibling op (orchestration review #5).
+   */
+  commitDisposition(id: string): 'live' | 'vetoed' | 'committing' | 'absent' {
+    this.pruneVetoTombstones();
+    if (this.committingIntentIds.has(id)) return 'committing';
+    if (this.vetoedIntentIds.has(id)) return 'vetoed';
+    return this.intents.has(id) ? 'live' : 'absent';
+  }
+
   beginCommit(id: string, allowedKinds: readonly PmxAxIntentKind[]): PmxAxIntent {
     this.pruneVetoTombstones();
     if (this.committingIntentIds.has(id)) {

package/src/server/mutation-history.ts

@@ -21,6 +21,7 @@ export type MutationOp =
   | 'updateNode'
   | 'removeNode'
   | 'addEdge'
+  | 'updateEdge'
   | 'removeEdge'
   | 'addAnnotation'
   | 'removeAnnotation'
@@ -43,13 +44,20 @@ export type MutationOp =
   | 'batch'
   | 'viewport'
   | 'groupNodes'
-  | 'ungroupNodes';
+  | 'releaseGroupChildren';
+
+/** Who made a mutation: the human in the workbench, or an agent through any transport. */
+export type MutationActor = 'human' | 'agent';
 
 export interface MutationEntry {
   id: string;
   timestamp: string;
   description: string;
   operationType: MutationOp;
+  actor: MutationActor;
+  /** Writer key (agentId, else transport source) for agent entries — lets a
+   * client prove "the top edit is MINE" before undoing on a multi-agent board. */
+  writer?: string;
   forward: () => void;
   inverse: () => void;
 }
@@ -58,6 +66,8 @@ export interface MutationSummary {
   id: string;
   timestamp: string;
   description: string;
+  actor: MutationActor;
+  writer?: string;
   operationType: MutationOp;
   isCurrent: boolean;
   isUndone: boolean;
@@ -103,11 +113,13 @@ class MutationHistory {
    * Record a new mutation. Truncates any redo-able future, then appends.
    * If called while replaying (undo/redo), the call is silently ignored.
    */
-  record(entry: Omit<MutationEntry, 'id' | 'timestamp'>): void {
+  record(entry: Omit<MutationEntry, 'id' | 'timestamp' | 'actor'> & { actor?: MutationActor }): void {
     if (this._replaying) return;
 
     const full: MutationEntry = {
       ...entry,
+      actor: entry.actor ?? currentActor ?? 'agent',
+      ...((entry.writer ?? currentWriter) ? { writer: entry.writer ?? currentWriter ?? undefined } : {}),
       id: `mut-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
       timestamp: new Date().toISOString(),
     };
@@ -169,12 +181,31 @@ class MutationHistory {
       id: e.id,
       timestamp: e.timestamp,
       description: e.description,
+      actor: e.actor,
+      ...(e.writer ? { writer: e.writer } : {}),
       operationType: e.operationType,
       isCurrent: i === this.cursor,
       isUndone: i > this.cursor,
     }));
   }
 
+  /** The entry Ctrl+Z would undo next (top of the shared stack), or null. */
+  top(): MutationSummary | null {
+    const entry = this.entries[this.cursor];
+    return entry
+      ? {
+          id: entry.id,
+          timestamp: entry.timestamp,
+          description: entry.description,
+          actor: entry.actor,
+          ...(entry.writer ? { writer: entry.writer } : {}),
+          operationType: entry.operationType,
+          isCurrent: true,
+          isUndone: false,
+        }
+      : null;
+  }
+
   /** Human-readable timeline for the canvas://history resource. */
   toHumanReadable(): string {
     if (this.entries.length === 0) {
@@ -383,3 +414,17 @@ export function formatDiff(diff: SnapshotDiffResult): string {
 // ── Singleton ────────────────────────────────────────────────────────
 
 export const mutationHistory = new MutationHistory();
+
+/**
+ * Actor context for entries recorded while an operation runs. executeOperation
+ * sets it from the workbench marker around each op; writes outside the
+ * registry (the sync SDK) default to `agent`. Only the undo affordance reads
+ * it, so an async op interleaving with another request costs at most a
+ * mislabelled row — never a wrong undo.
+ */
+let currentActor: MutationActor | null = null;
+let currentWriter: string | null = null;
+export function setMutationActor(actor: MutationActor | null, writer: string | null = null): void {
+  currentActor = actor;
+  currentWriter = actor === 'agent' ? writer : null;
+}

package/src/server/operations/composites.ts

@@ -170,10 +170,11 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_edge',
     description:
-      'Add or remove an edge (connection) between two nodes. Action "add" connects two nodes (type: flow=sequential, depends-on=dependency, relation=general, references=cross-reference; from/to take node ids, or fromSearch/toSearch resolve by title/content); "remove" deletes an edge by id.',
+      'Add, update, or remove an edge (connection) between two nodes. Action "add" connects two nodes (type: flow=sequential, depends-on=dependency, relation=general, references=cross-reference; from/to take node ids, or fromSearch/toSearch resolve by title/content); "update" patches an existing edge in place (label, type, style, animated); "remove" deletes an edge by id.',
     actionSummary: 'add | remove',
     actions: {
       add: 'edge.add',
+      update: 'edge.update',
       remove: 'edge.remove',
     },
   },
@@ -250,13 +251,15 @@ export const compositeToolDefinitions: CompositeToolDefinition[] = [
   {
     toolName: 'canvas_ax_state',
     description:
-      'Read or set host-agnostic PMX AX state. Action "get" reads the AX state + agent-ready context (pinned/focused context, focus field); "set-focus" places node IDs in the AX focus field (nodeIds); "set-policy" patches the tool/prompt policy (tools.allowed|excluded|approvalRequired, prompt.systemAppend|mode — merges with existing); "report-capability" records a host/session capability for diagnostics. Adapters may pass a source label (e.g. codex).',
-    actionSummary: 'get | set-focus | set-policy | report-capability',
+      'Read or set host-agnostic PMX AX state. Action "get" reads the AX state + agent-ready context (pinned/focused context, focus field); "set-focus" places node IDs in the AX focus field (nodeIds); "set-policy" patches the tool/prompt policy (tools.allowed|excluded|approvalRequired, prompt.systemAppend|mode — merges with existing); "report-capability" records a host/session capability for diagnostics; "presence" reads agent presence (who is writing, phase, attached session, context budget); "set-presence" updates this caller\'s presence (phase idle|thinking|tooling|waiting-approval, detail, focusNodeId, cursor, attached — attached:true starts a session, false ends it; contextUsage {used,total} reports the agent\'s real token window so the board\'s meter shows it instead of the pinned-context estimate). Adapters may pass a source label (e.g. codex).',
+    actionSummary: 'get | set-focus | set-policy | report-capability | presence | set-presence',
     actions: {
       get: 'ax.get',
       'set-focus': 'ax.focus.set',
       'set-policy': 'ax.policy.set',
       'report-capability': 'ax.host-capability.report',
+      presence: 'ax.presence.get',
+      'set-presence': 'ax.presence.set',
     },
   },
   {

package/src/server/operations/http.ts

@@ -7,6 +7,7 @@
  * the remaining legacy routes.
  */
 import { executeOperation, listOperations } from './registry.js';
+import { SOURCE_LABEL_RE } from '../agent-presence.js';
 import { OperationError } from './types.js';
 
 function responseJson(data: unknown, status = 200): Response {
@@ -88,7 +89,15 @@ export async function dispatchOperationRoute(req: Request, url: URL): Promise<Re
       // the browser is not agent activity, so it never synthesizes an
       // auto-ghost. Everything else (CLI, scripts, adapters) counts as agent.
       const fromWorkbench = req.headers.get('x-pmx-workbench') === '1';
-      const result = await executeOperation(op.name, input, { suppressAutoGhost: fromWorkbench });
+      // Presence writer label: adapters/CLI may identify themselves; plain
+      // HTTP callers read as 'api'.
+      const sourceHeader = req.headers.get('x-pmx-source');
+      const source = sourceHeader && SOURCE_LABEL_RE.test(sourceHeader) ? sourceHeader : 'api';
+      const result = await executeOperation(op.name, input, {
+        suppressAutoGhost: fromWorkbench,
+        fromWorkbench,
+        source,
+      });
       return responseJson(result, route.status ? route.status(result) : 200);
     } catch (error) {
       if (error instanceof OperationError) {

package/src/server/operations/index.ts

@@ -22,6 +22,8 @@ import { appOperations } from './ops/app.js';
 import { intentOperations } from './ops/intent.js';
 import { extAppOperations } from './ops/ext-app.js';
 import { axReadOperations } from './ops/ax-read.js';
+import { axPresenceOperations } from './ops/ax-presence.js';
+import { humanPresenceOperations } from './ops/human-presence.js';
 import { canvasWireOperations } from './ops/canvas-wire.js';
 
 for (const op of [
@@ -44,6 +46,8 @@ for (const op of [
   ...intentOperations,
   ...extAppOperations,
   ...axReadOperations,
+  ...axPresenceOperations,
+  ...humanPresenceOperations,
   ...canvasWireOperations,
 ]) {
   registerOperation(op);