pmx-canvas 0.4.8 → 0.5.1

package/dist/types/client/state/session-store.d.ts

@@ -0,0 +1,176 @@
+import type { AxApprovalStatus, AxEventKind, AxWorkItemStatus } from '../../shared/ax-kinds.js';
+export type WorkItemStatus = AxWorkItemStatus;
+export interface WorkItemView {
+    id: string;
+    title: string;
+    status: WorkItemStatus;
+    detail: string | null;
+    nodeIds: string[];
+    updatedAt: string;
+}
+export interface ApprovalGateView {
+    id: string;
+    title: string;
+    detail: string | null;
+    status: AxApprovalStatus;
+    nodeIds: string[];
+    createdAt: string;
+    /** Unattended-approval TTL: when a pending gate auto-holds. */
+    expiresAt: string | null;
+}
+export interface AxEventView {
+    id: string;
+    kind: AxEventKind;
+    summary: string;
+    detail: string | null;
+    createdAt: string;
+    /** Who recorded it — host/source label and per-agent identity. */
+    source?: string | null;
+    agentId?: string | null;
+}
+export interface AxEvidenceView {
+    id: string;
+    title: string;
+    body: string | null;
+    createdAt: string;
+    source?: string | null;
+    agentId?: string | null;
+}
+export interface AxSteeringView {
+    id: string;
+    message: string;
+    createdAt: string;
+    /** Consumer label this steer was addressed to; null/absent = broadcast. */
+    target?: string | null;
+    /** Who sent it — an agent label, or "browser" for the human's composer. */
+    source?: string | null;
+    /** Per-agent identity within the host — preferred over `source` for the row's sender. */
+    agentId?: string | null;
+    /** False until the target (or any consumer, for broadcasts) claims + marks it. */
+    delivered?: boolean;
+}
+/**
+ * Session panel data (rail-chrome-v2 phase 4). Nothing here is a second source
+ * of truth: work items and gates come from the AX surface snapshot the SSE
+ * bridge already refreshes on `ax-state-changed`; the timeline is the bounded
+ * AX timeline read, refreshed on `ax-event-created` while a session is
+ * attached. Gate decisions go through the existing resolve route.
+ */
+export interface ScopeFenceView {
+    nodeIds: string[];
+    padding: number;
+}
+export declare const sessionWorkItems: import("@preact/signals-core").ReadonlySignal<WorkItemView[]>;
+export declare const sessionGates: import("@preact/signals-core").ReadonlySignal<ApprovalGateView[]>;
+export declare const pendingGates: import("@preact/signals-core").ReadonlySignal<ApprovalGateView[]>;
+/** The scope fence the human granted the session (null = unscoped). */
+export declare const scopeFence: import("@preact/signals-core").ReadonlySignal<ScopeFenceView | null>;
+/** Grant or clear the fence: writes outside it are refused server-side; reads stay open. */
+export declare function setScopeFence(nodeIds: string[] | null): Promise<boolean>;
+/** Auto-held gates: the policy said no on the human's behalf; they can be reopened. */
+export declare const heldGates: import("@preact/signals-core").ReadonlySignal<ApprovalGateView[]>;
+export interface AxTimelineView {
+    events: AxEventView[];
+    evidence: AxEvidenceView[];
+    steering: AxSteeringView[];
+}
+export declare const axTimeline: import("@preact/signals-core").Signal<AxTimelineView>;
+export type TimelineEntryKind = AxEventKind | 'evidence' | 'steer' | 'update';
+/** Timeline filter chips: a handful of human categories over the many kinds. */
+export type TimelineFilter = 'all' | 'update' | 'steer' | 'assistant' | 'event' | 'evidence';
+export declare const timelineFilter: import("@preact/signals-core").Signal<TimelineFilter>;
+/** Which chip an entry belongs to: board writes / steering-shaped rows / evidence / the rest. */
+export declare function timelineCategory(kind: TimelineEntryKind): Exclude<TimelineFilter, 'all'>;
+export interface TimelineEntry {
+    id: string;
+    kind: TimelineEntryKind;
+    label: string;
+    body: string;
+    createdAt: string;
+    /** Writer key for the row (agentId, else non-transport source; 'browser' = the human).
+     * With several assistants on one board, a row without this is unanswerable:
+     * "Assistant · 23:11" from WHOM? Null when only a bare transport is known. */
+    who?: string | null;
+    /** Item 10: this agent edit is the top of the shared undo stack — "↩ undo this edit". */
+    undoable?: boolean;
+}
+/** The row's writer key: per-agent identity first, else a non-transport source. */
+export declare function writerKeyFor(agentId?: string | null, source?: string | null): string | null;
+/** The entry Ctrl+Z would undo next, from GET /api/canvas/history. */
+export declare const historyTop: import("@preact/signals-core").Signal<{
+    id: string;
+    actor: "human" | "agent";
+    description: string;
+} | null>;
+/** Agent edits undone from the panel this page-life — rendered "undone · steering sent". */
+export declare const undoneActivityIds: import("@preact/signals-core").Signal<Set<string>>;
+/**
+ * One reverse-chronological feed out of the three timeline tables plus the
+ * agent's board writes (the presence activity feed), so the panel shows what
+ * the agent DID between its tool runs and gates. The newest agent write gets
+ * the undo affordance when it is also the top of the shared undo stack.
+ */
+export declare function mergeTimeline(timeline: AxTimelineView, limit?: number, writes?: Array<{
+    id: string;
+    at: string;
+    op: string;
+    summary: string;
+    sessionId?: string;
+    label?: string;
+}>, top?: {
+    actor: 'human' | 'agent';
+} | null, filter?: TimelineFilter): TimelineEntry[];
+export declare const timelineEntries: import("@preact/signals-core").ReadonlySignal<TimelineEntry[]>;
+export declare function refreshTimeline(): Promise<void>;
+/**
+ * Undo the agent's latest edit through the ONE shared undo stack (the same
+ * POST /api/canvas/undo Ctrl+Z uses), then tell the agent: steering feedback
+ * goes out through the same path a veto takes.
+ */
+export declare function undoAgentEdit(entry: TimelineEntry): Promise<boolean>;
+/** Ctrl+Z / Ctrl+Shift+Z: whichever op is top of the shared stack, agent or human. */
+export declare function undoFromKeyboard(redo?: boolean): Promise<boolean>;
+/**
+ * Resolve a gate through the existing AX path. A rejection also posts steering
+ * feedback so the agent learns WHY its next turn — the same `vetoGhostSteering`
+ * contract ghost vetoes use.
+ */
+export declare function resolveGate(gate: ApprovalGateView, decision: 'approved' | 'rejected'): Promise<boolean>;
+/** Reopen an auto-held gate so it can be answered (fresh TTL). */
+export declare function reopenGate(gate: ApprovalGateView): Promise<boolean>;
+/** Post a steering message the agent reads on its next turn. */
+export declare function sendSteering(message: string, target?: string | null): Promise<boolean>;
+/** Attach a human-started session; the agent's writes are attributed to it. */
+export declare function startSession(): Promise<boolean>;
+/** End the attached session (whoever attached it) — the server answers with a receipt. */
+export declare function endSession(session: {
+    source: string;
+    agentId: string | null;
+}): Promise<boolean>;
+export interface SessionReceipt {
+    label: string;
+    endedAt: string;
+    /** Why it ended — the receipt should answer this, not leave the human asking. */
+    endedBy?: 'human' | 'agent' | 'idle-timeout';
+    /** The session changed nothing on the board (its pre-session snapshot was dropped). */
+    unchanged?: boolean;
+    /** Cancelled (withdrawn items), rejected (human's explicit no on a gate), and
+     * held (TTL expired unanswered) are three different outcomes — never one
+     * "vetoed" pile. */
+    counts: {
+        items: number;
+        done: number;
+        cancelled: number;
+        rejected: number;
+        held: number;
+    };
+    snapshot: {
+        id: string;
+        name: string;
+    } | null;
+}
+/** The last ended session's receipt (design item 2); client-side, cleared on dismiss. */
+export declare const sessionReceipt: import("@preact/signals-core").Signal<SessionReceipt | null>;
+export declare function applySessionReceipt(data: Record<string, unknown>): void;
+export declare function dismissSessionReceipt(): void;
+export declare function resetSessionStore(): void;

package/dist/types/client/types.d.ts

@@ -18,7 +18,6 @@ export interface CanvasNodeState {
     zIndex: number;
     collapsed: boolean;
     pinned: boolean;
-    dockPosition: 'left' | 'right' | null;
     data: Record<string, unknown>;
 }
 export interface CanvasEdge {
@@ -50,6 +49,8 @@ export interface CanvasAnnotation {
     label?: string;
     createdAt: string;
 }
+/** The rail's annotate modes; null = not annotating. */
+export type AnnotationTool = 'pen' | 'eraser' | 'text' | null;
 export type ConnectionStatus = 'connecting' | 'connected' | 'disconnected';
 export declare const TYPE_LABELS: Record<CanvasNodeState['type'], string>;
 /** Node types that support the full-viewport expand/focus overlay. */

package/dist/types/client/utils/platform.d.ts

@@ -1,2 +1,4 @@
 export declare const isMac: boolean;
 export declare const MOD_KEY: string;
+/** Platform-idiomatic modifier chord label: `modChord('K')` → "⌘K" on Mac, "Ctrl+K" elsewhere. */
+export declare function modChord(key: string): string;

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

@@ -0,0 +1,192 @@
+/**
+ * Agent presence registry (rail-chrome-v2 phase 2).
+ *
+ * Lives beside IntentRegistry and follows its discipline: in-memory, TTL-swept,
+ * count-capped, and emitting through an injected workbench emitter so this
+ * module never imports server.ts. One `agent-presence` SSE frame carries the
+ * full snapshot on every change, so a reconnecting client is never stale and
+ * never needs its own expiry ticker.
+ *
+ * Presence is derived, not declared: agent-originated mutations (anything
+ * `executeOperation` runs without the workbench marker) and AX activity
+ * ingests (`tool-start`, `session-start`, …) touch a writer; adapters with
+ * richer hooks may `set` a phase, cursor, or focus explicitly.
+ */
+import { z } from 'zod';
+import { type AgentPhase, type AgentPresence, type AgentPresenceSnapshot, type ContextBudget } from '../shared/agent-presence.js';
+import type { PmxAxActivityKind } from './ax-state.js';
+type PresenceEmitter = (event: string, payload: Record<string, unknown>) => void;
+/** A legal writer label: short, alphanumeric/dash, letter-first (header and env values). */
+export declare const SOURCE_LABEL_RE: RegExp;
+export interface PresenceTouch {
+    source: string;
+    agentId?: string | null;
+    label?: string;
+    phase?: AgentPhase;
+    detail?: string | null;
+    focusNodeId?: string | null;
+    parentAgentId?: string | null;
+    /** Op-derived tooling: overlay the phase without clobbering the explicit one. */
+    derivedTooling?: boolean;
+    cursor?: {
+        x: number;
+        y: number;
+    } | null;
+    attached?: boolean;
+    /** With `attached: false`: who ended it (receipt transparency). Default 'agent'. */
+    endedBy?: 'human' | 'agent';
+    /** The host's real token usage for this agent, if it knows it. */
+    contextUsage?: {
+        used: number;
+        total: number;
+    } | null;
+    /** Count this touch as an agent write. */
+    op?: boolean;
+    /** What the write did, for the activity feed (only meaningful with `op`). */
+    activity?: {
+        op: string;
+        summary: string;
+        nodeId: string | null;
+    };
+}
+/**
+ * One sentence for the activity feed, from the op name plus whatever the
+ * input/result name. Titles are read AFTER the op ran, so creates and updates
+ * resolve; removes describe what is gone by id.
+ */
+export declare function describeWrite(op: string, rawInput: unknown, result: unknown): {
+    summary: string;
+    nodeId: string | null;
+};
+/**
+ * The one validation schema for an explicit presence update. The HTTP/MCP op
+ * spreads these fields into its tool shape so the two cannot drift.
+ *
+ * Identity note: presence is a UX signal, not an authenticated identity — any
+ * local process can assert any `source`/`agentId` (the single-workspace trust
+ * model). It shows the human WHO claims to be working; it grants no write
+ * capability that the caller did not already have.
+ */
+export declare const PRESENCE_SET_SHAPE: {
+    source: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    label: z.ZodOptional<z.ZodString>;
+    phase: z.ZodOptional<z.ZodEnum<{
+        idle: "idle";
+        thinking: "thinking";
+        tooling: "tooling";
+        "waiting-approval": "waiting-approval";
+    }>>;
+    detail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    focusNodeId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    cursor: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>>;
+    attached: z.ZodOptional<z.ZodBoolean>;
+    parentAgentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    endedBy: z.ZodOptional<z.ZodEnum<{
+        agent: "agent";
+        human: "human";
+    }>>;
+    contextUsage: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        used: z.ZodNumber;
+        total: z.ZodNumber;
+    }, z.core.$strip>>>;
+};
+/** Token estimate of the pinned-context payload — the same serialization the MCP resource ships. */
+export declare function estimateContextBudget(): ContextBudget;
+/** Returns the id of the pre-session snapshot the server took, if any. */
+type SessionStartListener = (presence: AgentPresence) => string | null;
+export type SessionEndReason = 'human' | 'agent' | 'idle-timeout';
+type SessionEndListener = (presence: AgentPresence, startSnapshotId: string | null, endedBy: SessionEndReason) => void;
+export declare class AgentPresenceRegistry {
+    private readonly presences;
+    /** Newest first; bounded. Survives a writer fading — the feed is history, the writer list is presence. */
+    private activity;
+    private activitySeq;
+    private emit;
+    /** Single slots (like the emitter): server.ts owns the pre-session snapshot + receipt. */
+    private onSessionStart;
+    private onSessionEnd;
+    private sweepTimer;
+    private emitTimer;
+    /** Inject the workbench SSE emitter (server.ts wires this at module load). */
+    setEmitter(emitter: PresenceEmitter | null): void;
+    /**
+     * Fires when a session attaches (false → true). The listener may snapshot the
+     * board and return the snapshot id; the receipt at session end diffs against it.
+     */
+    setSessionStartListener(listener: SessionStartListener | null): void;
+    /**
+     * Fires once when an ATTACHED session ends — by `session-end`, by an explicit
+     * `attached: false`, or by the idle-TTL sweep — with the presence as it was
+     * and the pre-session snapshot id. Unattached writers fading away never fire it.
+     */
+    setSessionEndListener(listener: SessionEndListener | null): void;
+    /**
+     * Attribute an agent-less write to the one attached session, so the
+     * session's cursor and phase follow its own work no matter which transport
+     * carried it. An agent-started session absorbs transport labels only
+     * (api/mcp/sdk/cli); a human-started one (`browser`, *Start agent session*)
+     * is a placeholder for whichever agent comes next and absorbs any label.
+     * Ambiguous (several sessions) or identified (agentId) writes, and a writer
+     * that is itself attached, keep their own key.
+     */
+    private attributedKey;
+    /**
+     * Fold an unattached writer into a session: its ops and feed entries were
+     * the session's work all along. A human-started session still carrying its
+     * placeholder label takes the writer's name.
+     */
+    private fold;
+    /** Aliased channels: a key that attach-merged into another session (extension + its MCP server). */
+    private aliases;
+    /** Consumer keys that have claimed steering deliveries this server-run → last claim time. */
+    private steeringConsumers;
+    /** A delivery claim proves this consumer polls steering — its presence turns
+     * steerable, and the claim time is the roster's proof-of-polling freshness. */
+    noteSteeringConsumer(consumer: string): void;
+    /** Drop aliases that point at a session that no longer exists. */
+    private dropAliasesTo;
+    /** Touch a writer: upsert, bump lastSeen, apply the patch. Derived `tooling` decays on its own. */
+    touch(input: PresenceTouch, now?: number): AgentPresence;
+    /**
+     * A host reported the agent's real context window without naming the
+     * writer (the legacy `context-usage` workbench event): it belongs to the
+     * single attached session, if there is exactly one. Returns false otherwise.
+     */
+    reportContextUsage(usage: {
+        used: number;
+        total: number;
+    }): boolean;
+    /** Explicit update from an adapter / MCP client (validated). */
+    set(raw: unknown, fallbackSource: string): AgentPresence;
+    /** Map an AX activity ingest onto presence — the feed that already exists. */
+    observeActivity(kind: PmxAxActivityKind, input: {
+        source: string;
+        agentId?: string | null;
+        title: string;
+    }, now?: number): void;
+    /**
+     * Re-emit the snapshot after something the phase is DERIVED from changed
+     * (a gate opened or resolved) without any writer being touched.
+     */
+    refresh(): void;
+    /** Remove a writer (session-end). */
+    detach(sessionId: string): boolean;
+    snapshot(now?: number): AgentPresenceSnapshot;
+    /** Test / shutdown hook. */
+    reset(): void;
+    private publicView;
+    private hasPendingGate;
+    private evictOverflow;
+    private sweep;
+    /** Coalesce bursts (batch churn) into one frame per tick. */
+    private scheduleEmit;
+    private ensureSweeper;
+    private maybeStopSweeper;
+}
+/** Process-wide singleton, shared across HTTP handlers, MCP ops, and the SDK. */
+export declare const agentPresence: AgentPresenceRegistry;
+export {};

package/dist/types/server/ax-gate-ttl.d.ts

@@ -0,0 +1,6 @@
+type GateEmitter = (event: string, payload: Record<string, unknown>) => void;
+/** Hold every pending gate whose TTL has elapsed. Returns the gates it held. */
+export declare function sweepExpiredGates(now?: number): string[];
+export declare function startGateTtlSweeper(emitter: GateEmitter): void;
+export declare function stopGateTtlSweeper(): void;
+export {};

package/dist/types/server/ax-interaction.d.ts

@@ -47,15 +47,15 @@ export declare function normalizeNodeAxCapabilities(value: unknown): Partial<Nod
 export declare function resolveNodeAxCapabilities(node: CanvasNodeState): NodeAxCapabilities;
 declare const InteractionEnvelopeSchema: z.ZodObject<{
     type: z.ZodEnum<{
-        "ax.event.record": "ax.event.record";
-        "ax.steer": "ax.steer";
         "ax.work.create": "ax.work.create";
         "ax.work.update": "ax.work.update";
-        "ax.evidence.add": "ax.evidence.add";
         "ax.approval.request": "ax.approval.request";
         "ax.approval.resolve": "ax.approval.resolve";
-        "ax.review.add": "ax.review.add";
+        "ax.evidence.add": "ax.evidence.add";
+        "ax.event.record": "ax.event.record";
+        "ax.steer": "ax.steer";
         "ax.focus.set": "ax.focus.set";
+        "ax.review.add": "ax.review.add";
         "ax.command.invoke": "ax.command.invoke";
         "ax.elicitation.request": "ax.elicitation.request";
         "ax.mode.request": "ax.mode.request";
@@ -219,11 +219,5 @@ export interface AxFlowMaterializeInput {
         maxRuns?: number;
     };
 }
-/**
- * Validate + execute a node-originated AX interaction. Returns the public result
- * plus the SSE events the caller should emit (accepted/rejected outcome + the
- * underlying AX state event). Never throws on bad input — returns an `ok: false`
- * result with an appropriate HTTP-ish status.
- */
 export declare function applyAxInteraction(manager: AxInteractionManager, rawBody: unknown, source: PmxAxSource): AxInteractionResult;
 export {};

package/dist/types/server/ax-state-manager.d.ts

@@ -96,13 +96,22 @@ export declare class AxStateManager {
         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 gate (typically one the unattended-approval policy
+     * auto-held): back to pending with a fresh TTL, so the human can answer it.
+     */
+    reopenApproval(id: string, options?: {
+        ttlMs?: number;
+        source?: PmxAxSource;
+    }): PmxAxApprovalGate | null;
     getReviewAnnotations(): PmxAxReviewAnnotation[];
     addReviewAnnotation(input: {
         body: string;
@@ -161,6 +170,16 @@ export declare class AxStateManager {
     setPolicy(patch: {
         tools?: Partial<PmxAxPolicy['tools']>;
         prompt?: Partial<PmxAxPolicy['prompt']>;
+        /** Replace semantics: an object sets the fence, `null` clears it, absent leaves it. */
+        scope?: {
+            nodeIds: string[];
+            padding?: number;
+        } | null;
+        /** Per-key merge: an object sets that agent's territory, `null` clears it, absent keys keep theirs. */
+        agentScopes?: Record<string, {
+            nodeIds: string[];
+            padding?: number;
+        } | null>;
     }, _options?: {
         source?: PmxAxSource;
     }): PmxAxPolicy;
@@ -192,7 +211,7 @@ export declare class AxStateManager {
         agentId?: string | null;
         target?: string | null;
     }): PmxAxSteeringMessage;
-    markSteeringDelivered(id: string): boolean;
+    markSteeringDelivered(id: string, consumer?: string | null): boolean;
     /**
      * 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

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

@@ -1,4 +1,5 @@
 import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
+import type { AxApprovalStatus, AxEventKind, AxWorkItemStatus } from '../shared/ax-kinds.js';
 import type { AgentContextNode } from './agent-context.js';
 export type PmxAxSource = 'agent' | 'amp' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';
 export interface PmxAxFocusState {
@@ -7,10 +8,10 @@ export interface PmxAxFocusState {
     updatedAt: string | null;
     source: PmxAxSource | null;
 }
-export type PmxAxEventKind = 'prompt' | 'assistant-message' | 'tool-start' | 'tool-result' | 'failure' | 'approval' | 'steering' | 'command' | 'note';
+export type PmxAxEventKind = AxEventKind;
 export type PmxAxEvidenceKind = 'logs' | 'tool-result' | 'screenshot' | 'file' | 'diff' | 'test-output';
-export type PmxAxWorkItemStatus = 'todo' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
-export type PmxAxApprovalStatus = 'pending' | 'approved' | 'rejected';
+export type PmxAxWorkItemStatus = AxWorkItemStatus;
+export type PmxAxApprovalStatus = AxApprovalStatus;
 export type PmxAxReviewKind = 'comment' | 'finding';
 export type PmxAxReviewSeverity = 'info' | 'warning' | 'error';
 export type PmxAxReviewStatus = 'open' | 'resolved' | 'dismissed';
@@ -34,6 +35,8 @@ export interface PmxAxApprovalGate {
     status: PmxAxApprovalStatus;
     nodeIds: string[];
     createdAt: string;
+    /** When a still-pending gate auto-holds (unattended-approval policy). */
+    expiresAt: string | null;
     resolvedAt: string | null;
     resolution: string | null;
     source: PmxAxSource | null;
@@ -87,6 +90,8 @@ export interface PmxAxSteeringMessage {
     seq: number;
     message: string;
     delivered: boolean;
+    /** Broadcast pickups: which consumers marked this steer (per-consumer delivery). */
+    deliveredTo?: string[];
     createdAt: string;
     source: PmxAxSource | null;
     agentId: string | null;
@@ -154,6 +159,22 @@ export interface PmxAxDeliveryContext {
     omittedPending: number;
     pendingActivity: PendingAxActivityItem[];
 }
+/** Human ink on the board — freehand strokes and text notes, anchored to the nodes they overlap. */
+export interface PmxAxHumanAnnotation {
+    id: string;
+    type: string;
+    /** The human's words, when this is a text note (or a labelled stroke). */
+    text: string | null;
+    /** Nodes whose padded frame the annotation overlaps — what it is "on". */
+    onNodes: Array<{
+        id: string;
+        title: string | null;
+    }>;
+    center: {
+        x: number;
+        y: number;
+    };
+}
 export interface PmxAxContext {
     version: 1;
     generatedAt: string;
@@ -167,6 +188,8 @@ export interface PmxAxContext {
     workItems: PmxAxWorkItem[];
     approvalGates: PmxAxApprovalGate[];
     reviewAnnotations: PmxAxReviewAnnotation[];
+    /** What the human drew/wrote on the board (the annotate tool) — not agent review comments. */
+    humanAnnotations: PmxAxHumanAnnotation[];
     elicitations: PmxAxElicitation[];
     modeRequests: PmxAxModeRequest[];
     policy: PmxAxPolicy;
@@ -194,6 +217,16 @@ export interface PmxAxCommandDescriptor {
 export declare const AX_COMMAND_REGISTRY: Record<string, PmxAxCommandDescriptor>;
 export declare function isAxCommand(name: unknown): name is string;
 export declare function listAxCommands(): PmxAxCommandDescriptor[];
+/**
+ * Scope fence (rail-chrome-v2 design item 4): the region an attached agent
+ * may WRITE to — the fenced node set plus `padding` px around its bounding
+ * box for new nodes. Reads are never fenced. `null` = unscoped.
+ */
+export interface PmxAxScopeFence {
+    nodeIds: string[];
+    padding: number;
+}
+export declare const DEFAULT_SCOPE_FENCE_PADDING = 40;
 export interface PmxAxPolicy {
     tools: {
         allowed: string[];
@@ -204,9 +237,18 @@ export interface PmxAxPolicy {
         systemAppend: string | null;
         mode: string | null;
     };
+    scope: PmxAxScopeFence | null;
+    /**
+     * Per-agent territories (fleet orchestration): writer key (agentId when the
+     * write carries one, else its source label) → fence. Overrides `scope` for
+     * that writer; agents without an entry fall under the global fence.
+     */
+    agentScopes: Record<string, PmxAxScopeFence>;
 }
 export declare function createEmptyAxPolicy(): PmxAxPolicy;
+export declare function normalizeAxScopeFence(input: unknown): PmxAxScopeFence | null;
 export declare function normalizeAxPolicy(input: unknown): PmxAxPolicy;
+export declare function normalizeAxAgentScopes(input: unknown): Record<string, PmxAxScopeFence>;
 export declare function isAxEventKind(value: unknown): value is PmxAxEventKind;
 export declare function isAxEvidenceKind(value: unknown): value is PmxAxEvidenceKind;
 export declare function createEmptyAxFocusState(): PmxAxFocusState;
@@ -269,7 +311,10 @@ export declare function createAxApprovalGate(input: {
     detail?: string | null;
     action?: string | null;
     nodeIds?: string[];
+    ttlMs?: number;
 }, source: PmxAxSource | null, validNodeIds?: Set<string>): PmxAxApprovalGate;
+/** Server default for a gate's TTL: `PMX_CANVAS_GATE_TTL_MS`, else five minutes. */
+export declare function defaultGateTtlMs(): number;
 export declare function createAxReviewAnnotation(input: {
     body: string;
     kind?: PmxAxReviewKind;
@@ -306,6 +351,7 @@ export declare function buildAxContext(input: {
     workItems: PmxAxWorkItem[];
     approvalGates: PmxAxApprovalGate[];
     reviewAnnotations: PmxAxReviewAnnotation[];
+    humanAnnotations: PmxAxHumanAnnotation[];
     elicitations: PmxAxElicitation[];
     modeRequests: PmxAxModeRequest[];
     policy: PmxAxPolicy;

package/dist/types/server/ax-wait.d.ts

@@ -21,3 +21,16 @@ export declare function waitForAxResolution<T extends {
     timeoutMs: number;
     signal?: AbortSignal;
 }): Promise<AxWaitResult<T>>;
+/**
+ * Block until `ready()` turns true after a change on `channel` (default
+ * 'ax-timeline'), or the timeout elapses. The steering long-poll: the gate
+ * waiter above is item/status-shaped; this one waits on a plain condition —
+ * the reactive loop for agent hosts that cannot be woken from outside (their
+ * model only runs while their host gives it a turn, so one call parks here
+ * instead of burning that turn on tight polling).
+ */
+export declare function waitForAxCondition(opts: {
+    ready: () => boolean;
+    timeoutMs: number;
+    channel?: string;
+}): Promise<void>;

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

@@ -47,6 +47,7 @@ export declare function loadSnapshotFromDB(db: Database, idOrName: string): {
     state: PersistedCanvasState;
 } | null;
 export declare function listSnapshotsFromDB(db: Database, options?: CanvasSnapshotListOptions): CanvasSnapshot[];
+export declare function renameSnapshotInDB(db: Database, id: string, name: string): boolean;
 export declare function deleteSnapshotFromDB(db: Database, id: string): boolean;
 export declare function writeBlobToDB(db: Database, sha256: string, jsonValue: string): number;
 export declare function readBlobFromDB(db: Database, sha256: string): string | null;
@@ -57,9 +58,16 @@ export interface AxTimelineQuery {
 export declare function appendAxEventToDB(db: Database, ev: Omit<PmxAxEvent, 'seq'>): PmxAxEvent;
 export declare function appendAxEvidenceToDB(db: Database, ev: Omit<PmxAxEvidence, 'seq'>): PmxAxEvidence;
 export declare function appendAxSteeringToDB(db: Database, s: Omit<PmxAxSteeringMessage, 'seq'>): PmxAxSteeringMessage;
-export declare function markAxSteeringDeliveredInDB(db: Database, id: string): boolean;
+export declare function markAxSteeringDeliveredInDB(db: Database, id: string, consumer?: string | null): boolean;
 export declare function loadAxEventsFromDB(db: Database, q?: AxTimelineQuery): PmxAxEvent[];
 export declare function loadAxEvidenceFromDB(db: Database, q?: AxTimelineQuery): PmxAxEvidence[];
+/**
+ * Broadcasts age out of PENDING (they stay on the timeline): per-consumer
+ * delivery otherwise means every broadcast greets every FUTURE consumer key
+ * forever — a brand-new pump inherited two-day-old "all workers" calls.
+ * Addressed steers never expire here; they wait for their named consumer.
+ */
+export declare const BROADCAST_PENDING_TTL_MS: number;
 export declare function loadAxSteeringFromDB(db: Database, q?: AxTimelineQuery & {
     onlyPending?: boolean;
 }): PmxAxSteeringMessage[];