@sanctuary-framework/mcp-server 1.2.10 → 1.2.11

package/dist/index.d.cts

@@ -7525,26 +7525,143 @@ declare class SentinelDispatcher {
 }
 
 /**
- * Sanctuary MCP Server — Principal Dashboard
+ * Sanctuary v1.3 WP-V1.3-3 Omega-1 Coordination Handoff Log.
+ *
+ * OPENS WP-V1.3-3 Coordination Handoff Visualization. Read-only
+ * server-side data API: queries the existing audit log for the
+ * handoff-shape event classes, normalizes them into a uniform
+ * HandoffEntry, and exposes query + per-entry detail.
+ *
+ * Why this matters: operators running multiple wrapped agents need
+ * to SEE what their agents are doing together. Handoffs between
+ * agents are the most important state transitions: who passed work
+ * to whom, what got transferred, what got withheld. Without
+ * visibility, operators can't audit the multi-agent workflow OR
+ * diagnose where work stalled.
+ *
+ * Audit event sources unioned by this module:
+ *  - `v1.1_local_handoff` (Tau-3 in-process coordination): canonical
+ *    explicit-pair signal. Details carry sender_agent_id +
+ *    recipient_agent_id.
+ *  - `cross_harness_approval_aggregated` (Upsilon-1 cross-harness
+ *    aggregator): wrapped-agent -> operator handoff. Details carry
+ *    source_harness; recipient is the synthetic `operator` node.
+ *
+ * NOT included at v1.3 Omega-1 (deviation, documented in PR body):
+ *  - `composition_completed` events do not exist as audit-log
+ *    operations in current source; composition events are mesh-only
+ *    signed envelopes (`composition_receipt_*` / `composition_*` are
+ *    in COMPOSITION_EVENT_TYPES but never flow through
+ *    auditLog.append). When composition wires audit emissions, the
+ *    union extends here. Same posture as Phi-3 cross-agent-chatter
+ *    watcher.
  *
- * HTTP-based approval channel that serves a real-time web dashboard
- * for human principals to approve/deny agent operations.
+ * Castle-walking discipline:
+ *  - No outbound surface. Reads server-local audit log only.
+ *  - No LLM call (purely operator-eyes view; no inference).
+ *  - No new operator attack surface (read-only against existing audit
+ *    log; new audit events are operator-action observability only).
  *
- * Architecture:
- * - Node.js built-in `http`/`https` modules (no Express or external deps)
- * - SSE (Server-Sent Events) for real-time push to browser
- * - Pending approval requests block the MCP tool call via Promise
- * - Human clicks approve/deny in browser → POST /api/approve/:id → Promise resolves
- * - Timeout fallback: auto-deny (or auto-approve) if no response
+ * Multi-fortress isolation: HandoffLog is scoped to ONE AuditLog
+ * instance per fortress; the audit log itself enforces fortress
+ * boundary at the encryption layer.
+ */
+
+/** Operator-facing per-handoff record. */
+interface HandoffEntry {
+    /** Stable per-fortress entry id (32 hex chars; SHA-256 of audit_event_id). */
+    entry_id: string;
+    /** Pointer back to the source audit-event. */
+    audit_event_id: string;
+    source_agent_id: string;
+    /** `operator` for cross-harness flows; `unknown` when the entry shape lacks a recipient. */
+    target_agent_id: string;
+    /** ISO 8601 timestamp from the underlying audit entry. */
+    observed_at: string;
+    /** The original audit operation (`v1.1_local_handoff`, `cross_harness_approval_aggregated`). */
+    event_class: string;
+    /** Operator-friendly one-liner. */
+    context_transfer_summary: string;
+    /** Multi-step workflow grouping key (Omega-3); v1.3 Omega-1 returns null. */
+    workflow_link: string | null;
+}
+interface HandoffEntryDetail {
+    entry: HandoffEntry;
+    /** Source audit entry, decrypted under operator auth. */
+    source_audit_entry: AuditEntry;
+}
+interface HandoffLogQueryOptions {
+    /** Filter to entries with observed_at >= ISO 8601. */
+    since?: string;
+    /** Filter to entries with observed_at <= ISO 8601. */
+    until?: string;
+    /** Filter to entries where the agent participates as sender or recipient. */
+    agent_id?: string;
+    /** Result cap. Default 50; max 500. */
+    limit?: number;
+}
+interface HandoffLogOptions {
+    auditLog: AuditLog;
+    fortressId: string;
+}
+declare class HandoffLog {
+    private readonly auditLog;
+    private readonly fortressId;
+    constructor(opts: HandoffLogOptions);
+    /** Stable fortress id this HandoffLog reads. */
+    getFortressId(): string;
+    /**
+     * Query handoffs in chronological-newest-first order. Filters
+     * applied after normalization so the per-event-class shape
+     * differences (sender field name, recipient inference) are handled
+     * once.
+     */
+    query(opts: HandoffLogQueryOptions): Promise<HandoffEntry[]>;
+    /**
+     * Look up a single entry by id. Returns the normalized entry +
+     * the source audit payload for operator-facing detail rendering.
+     * Returns null when no audit entry maps to the given id.
+     */
+    getEntry(entryId: string): Promise<HandoffEntryDetail | null>;
+    private normalize;
+}
+
+/**
+ * Sanctuary v1.3 WP-V1.3-3 Omega-1 Coordination handoff HTTP routes.
  *
- * Security invariants:
- * - Binds to 127.0.0.1 by default (localhost only)
- * - Optional bearer token authentication for non-localhost deployments
- * - Optional TLS (HTTPS) via cert/key paths
- * - All decisions are audit-logged
- * - Agent cannot access the dashboard (it runs outside MCP stdin/stdout)
+ * Mounted under `/api/coordination/*`. Mirrors the Phi-1 sentinel
+ * route module shape (Standing CTO call: follow Phi-1 sibling-view
+ * pattern; spawn-prompt's `dashboard-handoff-view.ts` filename did
+ * not exist on main, so the routes live under the
+ * `coordination/` subsystem with the rest of the handoff machinery).
+ *
+ * Routes:
+ *   GET    /api/coordination/handoffs              (chronological list, filtered)
+ *   GET    /api/coordination/handoffs/stream       (SSE stream of new entries)
+ *   GET    /api/coordination/handoffs/:entry_id    (full detail incl. source audit entry)
+ *
+ * Auth-gated via existing operator middleware. Multi-fortress
+ * isolation enforced at the audit-log encryption boundary the
+ * underlying HandoffLog reads through.
+ *
+ * Two new operator-action audit events fire on these routes:
+ *  - `operator_coordination_view_opened` on the list route.
+ *  - `operator_handoff_entry_drilled` on the detail route.
  */
 
+/**
+ * In-process bridge that lets the dispatcher (or any other in-process
+ * source) push handoff events to live SSE subscribers without
+ * coupling the HandoffLog to a transport. The list route reads
+ * historical state via HandoffLog.query(); the stream route subscribes
+ * here for new entries.
+ */
+declare class HandoffEventBridge {
+    private readonly listeners;
+    subscribe(listener: (entry: HandoffEntry) => void): () => void;
+    emit(entry: HandoffEntry): void;
+}
+
 interface DashboardConfig {
     port: number;
     host: string;
@@ -7628,6 +7745,17 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * dispatcher's audited paths.
      */
     private sentinelDispatcher;
+    /**
+     * v1.3 WP-V1.3-3 Omega-1 Coordination Handoff Visualization.
+     * Mounted additively at `/api/coordination/*` when set. Read-only
+     * against the audit log; the only writes are operator-action audit
+     * events (operator_coordination_view_opened,
+     * operator_handoff_entry_drilled).
+     */
+    private handoffLog;
+    private handoffEventBridge;
+    private handoffAuditLog;
+    private handoffOperatorId;
     constructor(config: DashboardConfig);
     /**
      * Inject dependencies after construction.
@@ -7671,6 +7799,18 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * Pass `null` to detach (used by tests + during shutdown).
      */
     setSentinelDispatcher(dispatcher: SentinelDispatcher | null): void;
+    /**
+     * v1.3 WP-V1.3-3 Omega-1: bind the Coordination handoff log +
+     * event bridge + audit log + operator id. Once set, requests to
+     * `/api/coordination/*` route through `handleCoordinationRoute`.
+     * Pass `null` for any field to detach.
+     */
+    setHandoffLog(opts: {
+        handoffLog: HandoffLog | null;
+        eventBridge?: HandoffEventBridge | null;
+        auditLog?: AuditLog | null;
+        operatorId?: string | null;
+    }): void;
     /**
      * v1.3 WP-V1.3-10 dispatch entry point. Called from `handleRequest`
      * before the legacy approval route table. Returns true when served.
@@ -7682,6 +7822,12 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * bound. Returns true when served.
      */
     private dispatchSentinel;
+    /**
+     * v1.3 WP-V1.3-3 Omega-1 dispatch entry point. Routes
+     * `/api/coordination/*` requests through the coordination router
+     * when a HandoffLog has been bound. Returns true when served.
+     */
+    private dispatchCoordination;
     /**
      * v1.1 dispatch entry point. Called from `handleRequest` before the
      * legacy route table. Returns true when the request was served by v1.1

package/dist/index.d.ts

@@ -7525,26 +7525,143 @@ declare class SentinelDispatcher {
 }
 
 /**
- * Sanctuary MCP Server — Principal Dashboard
+ * Sanctuary v1.3 WP-V1.3-3 Omega-1 Coordination Handoff Log.
+ *
+ * OPENS WP-V1.3-3 Coordination Handoff Visualization. Read-only
+ * server-side data API: queries the existing audit log for the
+ * handoff-shape event classes, normalizes them into a uniform
+ * HandoffEntry, and exposes query + per-entry detail.
+ *
+ * Why this matters: operators running multiple wrapped agents need
+ * to SEE what their agents are doing together. Handoffs between
+ * agents are the most important state transitions: who passed work
+ * to whom, what got transferred, what got withheld. Without
+ * visibility, operators can't audit the multi-agent workflow OR
+ * diagnose where work stalled.
+ *
+ * Audit event sources unioned by this module:
+ *  - `v1.1_local_handoff` (Tau-3 in-process coordination): canonical
+ *    explicit-pair signal. Details carry sender_agent_id +
+ *    recipient_agent_id.
+ *  - `cross_harness_approval_aggregated` (Upsilon-1 cross-harness
+ *    aggregator): wrapped-agent -> operator handoff. Details carry
+ *    source_harness; recipient is the synthetic `operator` node.
+ *
+ * NOT included at v1.3 Omega-1 (deviation, documented in PR body):
+ *  - `composition_completed` events do not exist as audit-log
+ *    operations in current source; composition events are mesh-only
+ *    signed envelopes (`composition_receipt_*` / `composition_*` are
+ *    in COMPOSITION_EVENT_TYPES but never flow through
+ *    auditLog.append). When composition wires audit emissions, the
+ *    union extends here. Same posture as Phi-3 cross-agent-chatter
+ *    watcher.
  *
- * HTTP-based approval channel that serves a real-time web dashboard
- * for human principals to approve/deny agent operations.
+ * Castle-walking discipline:
+ *  - No outbound surface. Reads server-local audit log only.
+ *  - No LLM call (purely operator-eyes view; no inference).
+ *  - No new operator attack surface (read-only against existing audit
+ *    log; new audit events are operator-action observability only).
  *
- * Architecture:
- * - Node.js built-in `http`/`https` modules (no Express or external deps)
- * - SSE (Server-Sent Events) for real-time push to browser
- * - Pending approval requests block the MCP tool call via Promise
- * - Human clicks approve/deny in browser → POST /api/approve/:id → Promise resolves
- * - Timeout fallback: auto-deny (or auto-approve) if no response
+ * Multi-fortress isolation: HandoffLog is scoped to ONE AuditLog
+ * instance per fortress; the audit log itself enforces fortress
+ * boundary at the encryption layer.
+ */
+
+/** Operator-facing per-handoff record. */
+interface HandoffEntry {
+    /** Stable per-fortress entry id (32 hex chars; SHA-256 of audit_event_id). */
+    entry_id: string;
+    /** Pointer back to the source audit-event. */
+    audit_event_id: string;
+    source_agent_id: string;
+    /** `operator` for cross-harness flows; `unknown` when the entry shape lacks a recipient. */
+    target_agent_id: string;
+    /** ISO 8601 timestamp from the underlying audit entry. */
+    observed_at: string;
+    /** The original audit operation (`v1.1_local_handoff`, `cross_harness_approval_aggregated`). */
+    event_class: string;
+    /** Operator-friendly one-liner. */
+    context_transfer_summary: string;
+    /** Multi-step workflow grouping key (Omega-3); v1.3 Omega-1 returns null. */
+    workflow_link: string | null;
+}
+interface HandoffEntryDetail {
+    entry: HandoffEntry;
+    /** Source audit entry, decrypted under operator auth. */
+    source_audit_entry: AuditEntry;
+}
+interface HandoffLogQueryOptions {
+    /** Filter to entries with observed_at >= ISO 8601. */
+    since?: string;
+    /** Filter to entries with observed_at <= ISO 8601. */
+    until?: string;
+    /** Filter to entries where the agent participates as sender or recipient. */
+    agent_id?: string;
+    /** Result cap. Default 50; max 500. */
+    limit?: number;
+}
+interface HandoffLogOptions {
+    auditLog: AuditLog;
+    fortressId: string;
+}
+declare class HandoffLog {
+    private readonly auditLog;
+    private readonly fortressId;
+    constructor(opts: HandoffLogOptions);
+    /** Stable fortress id this HandoffLog reads. */
+    getFortressId(): string;
+    /**
+     * Query handoffs in chronological-newest-first order. Filters
+     * applied after normalization so the per-event-class shape
+     * differences (sender field name, recipient inference) are handled
+     * once.
+     */
+    query(opts: HandoffLogQueryOptions): Promise<HandoffEntry[]>;
+    /**
+     * Look up a single entry by id. Returns the normalized entry +
+     * the source audit payload for operator-facing detail rendering.
+     * Returns null when no audit entry maps to the given id.
+     */
+    getEntry(entryId: string): Promise<HandoffEntryDetail | null>;
+    private normalize;
+}
+
+/**
+ * Sanctuary v1.3 WP-V1.3-3 Omega-1 Coordination handoff HTTP routes.
  *
- * Security invariants:
- * - Binds to 127.0.0.1 by default (localhost only)
- * - Optional bearer token authentication for non-localhost deployments
- * - Optional TLS (HTTPS) via cert/key paths
- * - All decisions are audit-logged
- * - Agent cannot access the dashboard (it runs outside MCP stdin/stdout)
+ * Mounted under `/api/coordination/*`. Mirrors the Phi-1 sentinel
+ * route module shape (Standing CTO call: follow Phi-1 sibling-view
+ * pattern; spawn-prompt's `dashboard-handoff-view.ts` filename did
+ * not exist on main, so the routes live under the
+ * `coordination/` subsystem with the rest of the handoff machinery).
+ *
+ * Routes:
+ *   GET    /api/coordination/handoffs              (chronological list, filtered)
+ *   GET    /api/coordination/handoffs/stream       (SSE stream of new entries)
+ *   GET    /api/coordination/handoffs/:entry_id    (full detail incl. source audit entry)
+ *
+ * Auth-gated via existing operator middleware. Multi-fortress
+ * isolation enforced at the audit-log encryption boundary the
+ * underlying HandoffLog reads through.
+ *
+ * Two new operator-action audit events fire on these routes:
+ *  - `operator_coordination_view_opened` on the list route.
+ *  - `operator_handoff_entry_drilled` on the detail route.
  */
 
+/**
+ * In-process bridge that lets the dispatcher (or any other in-process
+ * source) push handoff events to live SSE subscribers without
+ * coupling the HandoffLog to a transport. The list route reads
+ * historical state via HandoffLog.query(); the stream route subscribes
+ * here for new entries.
+ */
+declare class HandoffEventBridge {
+    private readonly listeners;
+    subscribe(listener: (entry: HandoffEntry) => void): () => void;
+    emit(entry: HandoffEntry): void;
+}
+
 interface DashboardConfig {
     port: number;
     host: string;
@@ -7628,6 +7745,17 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * dispatcher's audited paths.
      */
     private sentinelDispatcher;
+    /**
+     * v1.3 WP-V1.3-3 Omega-1 Coordination Handoff Visualization.
+     * Mounted additively at `/api/coordination/*` when set. Read-only
+     * against the audit log; the only writes are operator-action audit
+     * events (operator_coordination_view_opened,
+     * operator_handoff_entry_drilled).
+     */
+    private handoffLog;
+    private handoffEventBridge;
+    private handoffAuditLog;
+    private handoffOperatorId;
     constructor(config: DashboardConfig);
     /**
      * Inject dependencies after construction.
@@ -7671,6 +7799,18 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * Pass `null` to detach (used by tests + during shutdown).
      */
     setSentinelDispatcher(dispatcher: SentinelDispatcher | null): void;
+    /**
+     * v1.3 WP-V1.3-3 Omega-1: bind the Coordination handoff log +
+     * event bridge + audit log + operator id. Once set, requests to
+     * `/api/coordination/*` route through `handleCoordinationRoute`.
+     * Pass `null` for any field to detach.
+     */
+    setHandoffLog(opts: {
+        handoffLog: HandoffLog | null;
+        eventBridge?: HandoffEventBridge | null;
+        auditLog?: AuditLog | null;
+        operatorId?: string | null;
+    }): void;
     /**
      * v1.3 WP-V1.3-10 dispatch entry point. Called from `handleRequest`
      * before the legacy approval route table. Returns true when served.
@@ -7682,6 +7822,12 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      * bound. Returns true when served.
      */
     private dispatchSentinel;
+    /**
+     * v1.3 WP-V1.3-3 Omega-1 dispatch entry point. Routes
+     * `/api/coordination/*` requests through the coordination router
+     * when a HandoffLog has been bound. Returns true when served.
+     */
+    private dispatchCoordination;
     /**
      * v1.1 dispatch entry point. Called from `handleRequest` before the
      * legacy route table. Returns true when the request was served by v1.1