pmx-canvas 0.4.7 → 0.5.0

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

@@ -196,6 +196,7 @@ export declare function addCanvasEdge(input: {
     style?: CanvasEdge['style'];
     animated?: boolean;
 }): CanvasEdge;
+export declare function updateCanvasEdge(id: string, patch: Partial<Pick<CanvasEdge, 'type' | 'label' | 'style' | 'animated'>>): CanvasEdge;
 export declare function removeCanvasEdge(id: string): {
     removed: boolean;
 };

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

@@ -65,7 +65,6 @@ export interface CanvasNodeState {
     zIndex: number;
     collapsed: boolean;
     pinned: boolean;
-    dockPosition: 'left' | 'right' | null;
     data: Record<string, unknown>;
 }
 export interface ViewportState {
@@ -120,11 +119,10 @@ export interface CanvasNodeUpdate {
         height: number;
     };
     collapsed?: boolean;
-    dockPosition?: 'left' | 'right' | null;
 }
 export type CanvasChangeType = 'pins' | 'nodes' | 'ax' | 'ax-timeline';
 export interface MutationRecordInfo {
-    operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'addWorkItem' | 'updateWorkItem' | 'requestApproval' | 'resolveApproval' | 'addReviewAnnotation' | 'updateReviewAnnotation' | 'requestElicitation' | 'respondElicitation' | 'requestMode' | 'resolveModeRequest' | 'setPolicy' | 'arrange' | 'batch' | 'groupNodes' | 'ungroupNodes' | 'viewport';
+    operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'updateEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'addWorkItem' | 'updateWorkItem' | 'requestApproval' | 'resolveApproval' | 'addReviewAnnotation' | 'updateReviewAnnotation' | 'requestElicitation' | 'respondElicitation' | 'requestMode' | 'resolveModeRequest' | 'setPolicy' | 'arrange' | 'batch' | 'groupNodes' | 'releaseGroupChildren' | 'viewport';
     description: string;
     forward: () => void;
     inverse: () => void;
@@ -202,13 +200,6 @@ declare class CanvasStateManager {
     private emptyPersistedState;
     /** Load canvas state from SQLite. Call once on server startup. */
     loadFromDisk(options?: LoadFromDiskOptions): boolean;
-    /**
-     * Whether this workspace's canvas DB already holds saved state. Used to gate
-     * brand-new-workspace seeding (e.g. the default docked status/context widgets)
-     * so we never add nodes to a canvas that already has content. Reflects the
-     * pre-run persisted flag until the next save.
-     */
-    hasPersistedState(): boolean;
     /** Debounced save — coalesces rapid mutations into a single write. */
     private scheduleSave;
     flushToDisk(): void;
@@ -247,6 +238,7 @@ declare class CanvasStateManager {
         annotations: CanvasAnnotation[];
     } | null;
     /** Delete a snapshot. */
+    renameSnapshot(id: string, name: string): boolean;
     deleteSnapshot(id: string): boolean;
     /** Remove all snapshots from the DB. Used by test teardown. */
     clearAllSnapshots(): void;
@@ -259,6 +251,7 @@ declare class CanvasStateManager {
     getNode(id: string): CanvasNodeState | undefined;
     getNodeForPersistence(id: string): CanvasNodeState | undefined;
     addEdge(edge: CanvasEdge): boolean;
+    updateEdge(id: string, patch: Partial<Pick<CanvasEdge, 'type' | 'label' | 'style' | 'animated'>>): CanvasEdge | null;
     removeEdge(id: string): boolean;
     getEdges(): CanvasEdge[];
     getEdgesForNode(nodeId: string): CanvasEdge[];
@@ -323,13 +316,19 @@ declare class CanvasStateManager {
         detail?: string | null;
         action?: string | null;
         nodeIds?: string[];
+        ttlMs?: number;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxApprovalGate;
-    resolveApproval(id: string, decision: 'approved' | 'rejected', options?: {
+    resolveApproval(id: string, decision: 'approved' | 'rejected' | 'held', options?: {
         resolution?: string;
         source?: PmxAxSource;
     }): PmxAxApprovalGate | null;
+    /** Reopen a resolved (typically auto-held) gate with a fresh TTL. */
+    reopenApproval(id: string, options?: {
+        ttlMs?: number;
+        source?: PmxAxSource;
+    }): PmxAxApprovalGate | null;
     getReviewAnnotations(): PmxAxReviewAnnotation[];
     addReviewAnnotation(input: {
         body: string;
@@ -388,6 +387,10 @@ declare class CanvasStateManager {
     setPolicy(patch: {
         tools?: Partial<PmxAxPolicy['tools']>;
         prompt?: Partial<PmxAxPolicy['prompt']>;
+        scope?: {
+            nodeIds: string[];
+            padding?: number;
+        } | null;
     }, options?: {
         source?: PmxAxSource;
     }): PmxAxPolicy;
@@ -419,7 +422,7 @@ declare class CanvasStateManager {
         agentId?: string | null;
         target?: string | null;
     }): PmxAxSteeringMessage;
-    markSteeringDelivered(id: string): boolean;
+    markSteeringDelivered(id: string, consumer?: string | null): boolean;
     ingestActivity(input: {
         kind: PmxAxActivityKind;
         title: string;
@@ -477,8 +480,19 @@ declare class CanvasStateManager {
     clearContextPins(): void;
     /** Move child nodes into a group. Sets data.parentGroup on children and data.children on the group. */
     groupNodes(groupId: string, childIds: string[], options?: GroupNodesOptions): boolean;
-    /** Remove all children from a group, clearing their parentGroup. */
+    /**
+     * Ungroup = dissolve: the children become independent nodes (members of the
+     * enclosing group when nested) and the frame is removed, in one undo step.
+     * Delegates to `removeNode` so the human's Ungroup and the agent's
+     * `group.remove` are the same operation. False when `groupId` is not a group.
+     */
     ungroupNodes(groupId: string): boolean;
+    /**
+     * Internal membership step: release every child but keep the frame (the
+     * first half of "set this group's children to …"). Not an ungroup — a
+     * human or agent ungroup dissolves the frame (`ungroupNodes`).
+     */
+    releaseGroupChildren(groupId: string): boolean;
     clear(): void;
 }
 export declare const canvasState: CanvasStateManager;

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

@@ -21,12 +21,6 @@ export interface CanvasSizeWarning {
     minWidth: number;
     minHeight: number;
 }
-export interface CanvasHiddenEdgeEndpoint {
-    edgeId: string;
-    nodeId: string;
-    nodeTitle: string | null;
-    dockPosition: 'left' | 'right';
-}
 export interface CanvasValidationResult {
     ok: boolean;
     collisions: CanvasValidationPair[];
@@ -37,13 +31,6 @@ export interface CanvasValidationResult {
         from: string;
         to: string;
     }>;
-    /**
-     * Edges whose endpoint node is DOCKED — it renders in the HUD column, not on
-     * the canvas, so the edge visually terminates in empty space even though both
-     * endpoint IDs resolve (0.4.6 orb feedback #1). Advisory: reported for
-     * diagnosis, but does NOT fail `ok` (see the note at the return site).
-     */
-    hiddenEdgeEndpoints: CanvasHiddenEdgeEndpoint[];
     /** Nodes below their type's readable minimum (advisory — does not fail `ok`). */
     sizeWarnings: CanvasSizeWarning[];
     summary: {
@@ -53,7 +40,6 @@ export interface CanvasValidationResult {
         containments: number;
         containmentViolations: number;
         missingEdgeEndpoints: number;
-        hiddenEdgeEndpoints: number;
         sizeWarnings: number;
     };
 }

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

@@ -60,7 +60,7 @@ export declare function buildContentHeightReporter(frameToken: string): string;
  * of the main SPA bundle). Escaping is mandatory: the source is arbitrary node
  * data and must not be parsed as markup.
  */
-export declare function buildMermaidSurfaceHtml(source: string): string;
+export declare function buildMermaidSurfaceHtml(source: string, inlineEntry?: string | null): string;
 export interface HtmlSurfaceOptions {
     theme: SurfaceTheme;
     /**

package/dist/types/server/human-presence.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { type HumanPresence, type HumanPresenceSnapshot } from '../shared/human-presence.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 declare const HUMAN_PRESENCE_SHAPE: {
+    clientId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>>;
+    grabbingNodeId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** Explicit leave (tab closing): drop the presence now. */
+    left: z.ZodOptional<z.ZodBoolean>;
+};
+type Emitter = (event: string, payload: Record<string, unknown>) => void;
+export declare class HumanPresenceRegistry {
+    private readonly humans;
+    private emit;
+    private sweepTimer;
+    private emitTimer;
+    setEmitter(emitter: Emitter | null): void;
+    set(raw: unknown, now?: number): HumanPresence | null;
+    snapshot(now?: number): HumanPresenceSnapshot;
+    /** Nodes a human is holding right now → that human's name. The edit lock. */
+    lockedNodes(now?: number): Map<string, string>;
+    reset(): void;
+    private publicView;
+    private sweep;
+    private scheduleEmit;
+    private ensureSweeper;
+    private maybeStopSweeper;
+}
+export declare const humanPresence: HumanPresenceRegistry;
+export {};

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

@@ -1,4 +1,5 @@
 import { EventEmitter } from 'node:events';
+import type { AgentPhase, AgentPresence, AgentPresenceSnapshot } from '../shared/agent-presence.js';
 import { canvasState } from './canvas-state.js';
 import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
 import { type AxInteractionInput, type AxInteractionPublicResult } from './ax-interaction.js';
@@ -32,6 +33,7 @@ export declare class PmxCanvas extends EventEmitter {
         port?: number;
     });
     private runIntentCommit;
+    private runIntentCommitInner;
     start(options?: {
         open?: boolean;
         automationWebView?: boolean | CanvasAutomationWebViewOptions;
@@ -134,7 +136,7 @@ export declare class PmxCanvas extends EventEmitter {
         childLayout?: 'grid' | 'column' | 'flow';
         intentId?: string;
     }): boolean;
-    /** 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;
@@ -168,7 +170,7 @@ export declare class PmxCanvas extends EventEmitter {
         agentId?: string | null;
         target?: string | null;
     }): PmxAxSteeringMessage;
-    markSteeringDelivered(id: string): boolean;
+    markSteeringDelivered(id: string, consumer?: string | null): boolean;
     /**
      * Ghost Cursor of Intent — announce a spatial move before making it. The ghost
      * is ephemeral presence (auto-expiring, never snapshotted); the registry emits
@@ -227,6 +229,11 @@ export declare class PmxCanvas extends EventEmitter {
         resolution?: string;
         source?: PmxAxSource;
     }): PmxAxApprovalGate | null;
+    /** Reopen a resolved (typically auto-held) approval gate with a fresh TTL. */
+    reopenApproval(id: string, options?: {
+        ttlMs?: number;
+        source?: PmxAxSource;
+    }): PmxAxApprovalGate | null;
     addEvidence(input: {
         kind: PmxAxEvidenceKind;
         title: string;
@@ -262,6 +269,26 @@ export declare class PmxCanvas extends EventEmitter {
     reportHostCapability(input: unknown, options?: {
         source?: PmxAxSource;
     }): PmxAxHostCapability;
+    /** Who is writing to this board right now, their phase, and the context budget. */
+    getAgentPresence(): AgentPresenceSnapshot;
+    /**
+     * 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;
     listElicitations(): PmxAxElicitation[];
     requestElicitation(input: {
         prompt: string;
@@ -388,7 +415,6 @@ export declare class PmxCanvas extends EventEmitter {
             height: number;
         };
         collapsed?: boolean;
-        dockPosition?: 'left' | 'right' | null;
     }>): {
         applied: number;
         skipped: number;

package/dist/types/server/intent-registry.d.ts

@@ -27,6 +27,13 @@ export declare 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';
     beginCommit(id: string, allowedKinds: readonly PmxAxIntentKind[]): PmxAxIntent;
     completeCommit(id: string, settledNodeId?: string): void;
     abortCommit(id: string): void;

package/dist/types/server/mutation-history.d.ts

@@ -12,12 +12,18 @@
  * - _replaying flag prevents undo/redo from recording new entries
  */
 import type { CanvasNodeState, CanvasEdge } from './canvas-state.js';
-export type MutationOp = 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'arrange' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'addWorkItem' | 'updateWorkItem' | 'requestApproval' | 'resolveApproval' | 'addReviewAnnotation' | 'updateReviewAnnotation' | 'requestElicitation' | 'respondElicitation' | 'requestMode' | 'resolveModeRequest' | 'setPolicy' | 'batch' | 'viewport' | 'groupNodes' | 'ungroupNodes';
+export type MutationOp = 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'updateEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'arrange' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'addWorkItem' | 'updateWorkItem' | 'requestApproval' | 'resolveApproval' | 'addReviewAnnotation' | 'updateReviewAnnotation' | 'requestElicitation' | 'respondElicitation' | 'requestMode' | 'resolveModeRequest' | 'setPolicy' | 'batch' | 'viewport' | 'groupNodes' | '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;
 }
@@ -25,6 +31,8 @@ export interface MutationSummary {
     id: string;
     timestamp: string;
     description: string;
+    actor: MutationActor;
+    writer?: string;
     operationType: MutationOp;
     isCurrent: boolean;
     isUndone: boolean;
@@ -71,7 +79,9 @@ declare 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;
     /** Undo the last applied mutation. Returns the entry that was undone, or null. */
     undo(): MutationEntry | null;
     /** Redo the next undone mutation. Returns the entry that was redone, or null. */
@@ -80,6 +90,8 @@ declare class MutationHistory {
     canRedo(): boolean;
     /** Get all entries with current/undone status for display. */
     getSummaries(): MutationSummary[];
+    /** The entry Ctrl+Z would undo next (top of the shared stack), or null. */
+    top(): MutationSummary | null;
     /** Human-readable timeline for the canvas://history resource. */
     toHumanReadable(): string;
     /** Number of recorded entries. */
@@ -102,4 +114,5 @@ export declare function diffLayouts(snapshotName: string, snapshotLayout: {
  */
 export declare function formatDiff(diff: SnapshotDiffResult): string;
 export declare const mutationHistory: MutationHistory;
+export declare function setMutationActor(actor: MutationActor | null, writer?: string | null): void;
 export {};

package/dist/types/server/operations/invoker.d.ts

@@ -1,13 +1,24 @@
 export interface OperationInvoker {
     invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
 }
+/**
+ * The agent-presence label for a transport: `PMX_CANVAS_AGENT_SOURCE` lets a
+ * host name its agent ('codex', 'claude-code', …) so writes, attach and cursor
+ * all key on one identity; otherwise the transport's own label.
+ */
+export declare function agentSourceLabel(fallback: string): string;
 /** Runs operations in-process against the shared canvasState singleton. */
 export declare class LocalOperationInvoker implements OperationInvoker {
+    private readonly source;
+    /** `source` labels this caller's agent presence ('mcp', 'sdk', …). */
+    constructor(source?: string);
     invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
 }
 /** Builds the HTTP request from the op's route template (`:id` from input, GET flags to query). */
 export declare class HttpOperationInvoker implements OperationInvoker {
     private readonly baseUrl;
-    constructor(baseUrl: string);
-    invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
+    private readonly source;
+    /** `source` labels this caller's agent presence on the server ('cli', 'mcp', …). */
+    constructor(baseUrl: string, source?: string);
+    invoke(name: string, rawInput: Record<string, unknown>): Promise<unknown>;
 }

package/dist/types/server/operations/ops/ax-presence.d.ts

@@ -0,0 +1,2 @@
+import { type Operation } from '../types.js';
+export declare const axPresenceOperations: Operation[];

package/dist/types/server/operations/ops/human-presence.d.ts

@@ -0,0 +1,3 @@
+export declare const humanPresenceSetOperation: import("../types.js").Operation;
+export declare const humanPresenceGetOperation: import("../types.js").Operation;
+export declare const humanPresenceOperations: import("../types.js").Operation[];

package/dist/types/server/operations/registry.d.ts

@@ -18,6 +18,17 @@ export interface ExecuteOperationMeta {
      * its inner dispatches (batch churn is exempt, matching the skill contract).
      */
     suppressAutoGhost?: boolean;
+    /**
+     * Who is calling — the presence writer label ('mcp', 'sdk', 'api', …).
+     * Defaults to 'api'. Workbench calls (suppressAutoGhost) never touch presence.
+     */
+    source?: string;
+    /**
+     * The human's own browser issued this call. Distinct from suppressAutoGhost
+     * (which batch also sets for its inner dispatches): the scope fence applies
+     * to agents only, and batch inner writes are always agent-originated.
+     */
+    fromWorkbench?: boolean;
 }
 export declare function executeOperation(name: string, rawInput: unknown, meta?: ExecuteOperationMeta): Promise<unknown>;
 export {};

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

@@ -11,7 +11,7 @@
  */
 import type { ZodRawShape } from 'zod';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-export type OperationErrorStatus = 400 | 404 | 409;
+export type OperationErrorStatus = 400 | 403 | 404 | 409;
 /** Operation failure that maps to an HTTP status + `{ ok:false, error }` body and MCP `isError`. */
 export declare class OperationError extends Error {
     readonly status: OperationErrorStatus;

package/dist/types/server/scope-fence.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Scope fence enforcement (rail-chrome-v2 phase 4, design item 4).
+ *
+ * When the AX policy carries a scope fence, an attached agent may only WRITE
+ * inside it: existing-node writes must target fenced nodes, new nodes must
+ * land inside the fence's bounding box (fenced nodes + padding), and
+ * board-wide writes (arrange, clear, restore) are refused. Reads are never
+ * fenced, and neither are the human's own workbench writes — the fence is the
+ * human's tool, not a cage for the human.
+ *
+ * One core check (`checkFenceTarget`) serves two describers: the operation
+ * registry (`checkScopeFence`, every HTTP/MCP/CLI write) and the sync SDK,
+ * whose methods bypass the registry and describe their own targets.
+ *
+ * Safe default: a mutating op this module does not know how to scope is
+ * refused while a fence is set, rather than silently allowed. Likewise a
+ * write this module cannot resolve (an edge given by search, a missing id)
+ * is refused — fail closed, never a bypass.
+ *
+ * Trust note: the workbench marker is a self-reported header. Under the
+ * local single-workspace model that is by design (any local process may
+ * write; the safety model is human veto plus this fence), so the fence holds
+ * cooperating agents to the region the human granted — it is not an
+ * authentication boundary.
+ */
+import { type FenceRect } from '../shared/scope-fence.js';
+import type { Operation } from './operations/types.js';
+/** Bounding box of the fenced nodes plus padding; null when none of them exist. */
+export declare function scopeFenceRect(fence: {
+    nodeIds: string[];
+    padding: number;
+}): FenceRect | null;
+/** What a write touches, in fence terms. */
+export interface FenceTarget {
+    /** Existing nodes the write targets — every one must be fenced. */
+    nodeIds?: string[];
+    /** World points a write introduces (a new node, annotation points) — all must be inside the box. */
+    points?: Array<{
+        x: number;
+        y: number;
+    }>;
+    /** A new node with no position: refused (it cannot be placed inside the fence). */
+    unplacedCreate?: boolean;
+    /** Rewrites the whole board — never allowed under a fence. */
+    boardWide?: boolean;
+    /** The op is not fence-aware — refused while a fence is set. */
+    unknown?: string;
+}
+/** Returns a human-readable refusal, or null when the target is inside the fence. */
+export declare function checkFenceTarget(target: FenceTarget, opName: string, writerKey?: string): string | null;
+/** Describe what a registry op would write, in fence terms. */
+export declare function describeOpTarget(op: Operation, rawInput: unknown): FenceTarget;
+/** Registry entry point: refusal text or null. Only call for mutating, agent-originated ops. */
+export declare function checkScopeFence(op: Operation, rawInput: unknown, writerKey?: string): string | null;
+/**
+ * The GLOBAL fence belongs to the human: an agent must not clear, widen, or
+ * replace it through `ax.policy.set`. Per-agent territories (`agentScopes`)
+ * are the orchestration surface — an agent MAY set territories for OTHER
+ * writers (fencing its workers), but never its own: granting yourself a wider
+ * territory (or deleting it) is escalation.
+ */
+export declare function checkScopeOwnership(rawInput: unknown, writerKey?: string): string | null;

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

@@ -93,18 +93,6 @@ export declare function setPrimaryWorkbenchCanvasPromptHandler(handler: PrimaryW
 export declare function isCanvasBundlePath(distPath: string, bundleDir: string): boolean;
 export declare function buildMacBrowserOpenScript(appName: string, url: string): string;
 export declare function openUrlInExternalBrowser(url: string): boolean;
-/**
- * Seed the docked status (left) + context (right) widgets so a freshly opened
- * canvas shows them by default — the same nodes the agent-event path creates on
- * demand (`status-main`, `context-main`), just present from the start.
- *
- * First-run only: we bail if the workspace canvas already has persisted state,
- * so we never add them to a board with content, and — because first-run state is
- * persisted on save — deleting or undocking them later is respected (they are
- * not re-seeded). Create-if-missing keeps it idempotent if the agent path
- * already made one. Returns true if anything was seeded.
- */
-export declare function ensureDefaultDockedNodes(): boolean;
 export declare function emitPrimaryWorkbenchEvent(event: string, payload?: PrimaryWorkbenchEventPayload): void;
 export declare function consumePrimaryWorkbenchIntents(limit?: number): PrimaryWorkbenchIntent[];
 export declare function getPrimaryWorkbenchUrl(workspaceRoot?: string): string | null;

package/dist/types/shared/agent-presence.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Agent presence — the contract behind every agent surface in the rail chrome
+ * (rail-chrome-v2 phase 2). Shared by server and client so the two cannot
+ * drift. See design/rail-chrome-v2/PLAN.md, "Phase 2 contract".
+ *
+ * Presence is DERIVED from feeds that already exist (AX activity ingest,
+ * agent-originated mutations) plus an explicit set for adapters with richer
+ * hooks. Nothing here is a second source of truth for work items, gates, or
+ * steering — those stay in the AX state.
+ */
+export type AgentPhase = 'idle' | 'thinking' | 'tooling' | 'waiting-approval';
+export declare const AGENT_PHASES: readonly AgentPhase[];
+export interface AgentPresence {
+    /** Writer key: `agentId` when the host supplies one, else the source label. */
+    sessionId: string;
+    /** Host label (copilot, codex, mcp, api, cli, …). */
+    source: string;
+    agentId: string | null;
+    /** Display name. */
+    label: string;
+    phase: AgentPhase;
+    /** Tool or operation name while `tooling`. */
+    detail: string | null;
+    focusNodeId: string | null;
+    /** World coordinates. */
+    cursor: {
+        x: number;
+        y: number;
+    } | null;
+    /** A session is attached: `session-start` (or explicit attach) seen and no `session-end`. */
+    attached: boolean;
+    /** Fleet membership: the orchestrating writer's key this worker belongs to (chrome rolls workers up under it). */
+    parentAgentId?: string | null;
+    /** True when steering addressed to this writer can actually reach it: it is
+     * an attached session, or its consumer key has claimed deliveries before. */
+    steerable?: boolean;
+    /** Steers sitting unclaimed in this writer's delivery queue (pump-health:
+     * a growing count means the writer is not polling). Only set for steerable rows. */
+    pendingSteers?: number;
+    /** When this writer's consumer key last claimed its delivery queue — the
+     * proof-of-polling behind `steerable`. Absent for writers that never claimed
+     * (steerable only via an attached adapter loop). */
+    lastClaimAt?: string;
+    /** Agent writes observed for this writer — feeds the external-steering indicator. */
+    opCount: number;
+    /**
+     * The agent's REAL context window, when its host reports it (tokens used /
+     * window size). Null when no adapter reports — the top-bar meter then shows
+     * the pinned-context estimate against the configured budget instead, and
+     * says so.
+     */
+    contextUsage: {
+        used: number;
+        total: number;
+    } | null;
+    lastSeenAt: string;
+}
+export interface ContextBudget {
+    /** Estimated tokens of the pinned-context payload. */
+    used: number;
+    total: number;
+}
+/**
+ * One agent write, as the External Steering activity feed lists it. Derived
+ * from the same presence touch every agent-originated operation already
+ * makes — not a second log.
+ */
+export interface AgentActivityEntry {
+    id: string;
+    at: string;
+    /** Writer key after attribution (the session's when the write was folded into it). */
+    sessionId: string;
+    label: string;
+    /** Registry operation name (node.add, edge.remove, ax.work.create, …). */
+    op: string;
+    /** Human sentence: "Created markdown “Release plan”". */
+    summary: string;
+    nodeId: string | null;
+}
+export interface AgentPresenceSnapshot {
+    presences: AgentPresence[];
+    budget: ContextBudget;
+    /** True when any presence is attached — the master gate for agent chrome. */
+    sessionActive: boolean;
+    /** Most recent agent writes, newest first (bounded by MAX_ACTIVITY_ENTRIES). */
+    activity: AgentActivityEntry[];
+}
+/** Activity entries kept for the feed — oldest fall off. */
+export declare const MAX_ACTIVITY_ENTRIES = 50;
+/** Unattached writers fade this long after their last write. */
+export declare const PRESENCE_ACTIVITY_TTL_MS: number;
+/** Attached sessions expire after this much quiet without a `session-end`. */
+export declare const PRESENCE_ATTACHED_IDLE_TTL_MS: number;
+/** `tooling` decays to `idle` after this much quiet. */
+export declare const PRESENCE_TOOLING_SETTLE_MS = 4000;
+/** Explicit `thinking` without any fresh touch settles to idle — hosts set it
+ * at turn start and often never send the turn-end idle, leaving three
+ * "Thinking" chips on a silent board. */
+export declare const PRESENCE_THINKING_SETTLE_MS: number;
+export declare const MAX_PRESENCES = 16;
+/** Default `budget.total` when `PMX_CANVAS_CONTEXT_BUDGET_TOKENS` is unset. */
+export declare const CONTEXT_BUDGET_DEFAULT_TOKENS = 32000;
+/**
+ * Source labels that name a TRANSPORT, not an agent. A write arriving under
+ * one of these while exactly one session is attached is the attached agent's
+ * own work reaching the board through that transport (Copilot/Codex/Claude
+ * Code all write via MCP or HTTP while their host holds the session).
+ */
+export declare const TRANSPORT_SOURCES: readonly string[];
+/**
+ * The label a human-started session (*Start agent session* in the browser)
+ * carries until an agent writes into it — the session is a placeholder for
+ * whichever agent comes next, so the first identified writer names it.
+ */
+export declare const HUMAN_STARTED_SESSION_LABEL = "Agent session";
+/** The one selector every agent surface reads. */
+export declare function isSessionActive(presences: readonly AgentPresence[]): boolean;
+/** Writers that are live but not attached — the External Steering mode. */
+export declare function externalWriters(presences: readonly AgentPresence[]): AgentPresence[];
+/** Rough token estimate for a JSON payload (chars / 4) — good enough for a meter. */
+export declare function estimateTokens(text: string): number;
+/** Chip label per phase — shared by the top-bar chip and the on-canvas cursor chip. */
+export declare function agentPhaseLabel(presence: Pick<AgentPresence, 'phase' | 'detail'>): string;
+/**
+ * Stable per-agent identity hue (0-359) from the writer key. Phase colors
+ * kept telling the human WHAT an agent is doing while erasing WHO — two
+ * thinking agents rendered identically. Identity rides the glyph/border;
+ * phase stays on dots and labels.
+ */
+export declare function agentIdentityHue(key: string): number;

package/dist/types/shared/approval-gates.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Unattended approval policy (rail-chrome-v2 phase 4, design item 3).
+ *
+ * A pending approval gate carries a TTL. If the human does not answer in time
+ * the gate resolves to `held` — the safe default: the action does NOT proceed,
+ * a `policy` entry lands in the timeline, and the gate can be reopened from the
+ * session panel. Shared so the server's sweeper and the client's countdown read
+ * one clock.
+ */
+export declare const DEFAULT_GATE_TTL_MS: number;
+export declare const MIN_GATE_TTL_MS = 1000;
+export declare const MAX_GATE_TTL_MS: number;
+export declare function clampGateTtlMs(value: unknown, fallback?: number): number;
+/** Milliseconds until a gate auto-holds (0 when expired, null when it has no TTL). */
+export declare function gateRemainingMs(gate: {
+    expiresAt: string | null;
+}, now?: number): number | null;
+/** `M:SS` for the gate countdown ("auto-holds in 4:31"). */
+export declare function formatCountdown(ms: number): string;