@sanctuary-framework/mcp-server 1.2.9 → 1.2.11

package/dist/index.d.cts

@@ -7129,6 +7129,72 @@ declare class ApprovalAggregator {
     private hydrate;
 }
 
+/**
+ * Sanctuary v1.3 WP-V1.3-1 Sentinel Finding Store.
+ *
+ * Encrypted at-rest persistence for sentinel findings. Sibling to the
+ * Upsilon-3 aggregator-store: same fortress-master-key-derived HKDF
+ * subkey shape, AAD-bound to the finding_id, retention-aware.
+ *
+ * Storage layout:
+ *   namespace: `_sentinel_findings`
+ *   key:       `finding.{finding_id}` (one record per finding)
+ *   payload:   AES-256-GCM ciphertext of the JSON-serialized record.
+ *   key:       `l2-sentinel-finding-v1` HKDF subkey of fortress master.
+ *   AAD:       UTF-8 bytes of `finding_id`.
+ *
+ * Multi-fortress isolation: HKDF subkey derives from the fortress
+ * master key. Two fortresses never produce identical encryption keys
+ * for identical finding_ids.
+ *
+ * Retention: 30 days default, mirroring the audit-log envelope and the
+ * aggregator payload store.
+ */
+
+interface SentinelFindingStoreOptions {
+    storage: StorageBackend;
+    masterKey: Uint8Array;
+    fortressId: string;
+    /** Operator-tunable retention window. Default 30 days. */
+    retentionDays?: number;
+    /** Wall-clock provider for deterministic tests. */
+    now?: () => Date;
+}
+declare class SentinelFindingStore {
+    private readonly storage;
+    private readonly encryptionKey;
+    private readonly fortressId;
+    private readonly retentionDays;
+    private readonly now;
+    constructor(opts: SentinelFindingStoreOptions);
+    /**
+     * Persist a finding. Truncates the operator-visible summary to
+     * SENTINEL_SUMMARY_MAX_CHARS so the dashboard render stays bounded.
+     * Returns the retention deadline so callers can audit it.
+     */
+    saveFinding(finding: SentinelFinding): Promise<string>;
+    /** Load a single finding by id, or null when absent / corrupted. */
+    loadFinding(findingId: string): Promise<SentinelFinding | null>;
+    /**
+     * List findings, newest first. Optional filters: since (ISO 8601),
+     * severity, sentinel_id, agent_id, limit. Default limit 100.
+     */
+    listFindings(opts?: {
+        since?: string;
+        severity?: SentinelSeverity;
+        sentinelId?: string;
+        agentId?: string;
+        limit?: number;
+    }): Promise<SentinelFinding[]>;
+    /**
+     * Drop expired findings. Returns the count removed.
+     */
+    pruneExpired(now?: Date): Promise<{
+        pruned: number;
+    }>;
+    private decode;
+}
+
 /**
  * Sanctuary v1.3 WP-V1.3-1 Sentinel Baseline Pack (Castle Layer 2 anchor)
  *
@@ -7166,6 +7232,22 @@ interface SentinelContext {
     substrateSelector?: SubstrateSelector;
     /** Wall-clock provider. Tests inject a deterministic clock. */
     now: () => Date;
+    /**
+     * Optional read view of the per-fortress sentinel finding store
+     * (Phi-1 surface). First-order sentinels (Phi-1/2/3/4) do not need
+     * this; the Phi-5 meta-sentinel reads it to detect patterns ACROSS
+     * other sentinels' findings (compound finding, fortress-wide count
+     * spikes, novel sentinel-ID combinations). The dispatcher attaches
+     * the store automatically on `subscribeSentinel`; tests can omit it
+     * when constructing a context literal for a first-order watcher.
+     *
+     * Multi-fortress isolation rides on the store's existing key shape:
+     * the store is constructed per-fortress from the fortress master
+     * key, so two fortresses' stores produce distinct ciphertext for
+     * identical finding-ids and one fortress's read cannot decode
+     * another fortress's findings.
+     */
+    findingStore?: SentinelFindingStore;
 }
 /**
  * One observation a sentinel produced. Persisted under the sentinel
@@ -7331,72 +7413,6 @@ declare class SentinelRegistry {
     unsubscribeAll(): Promise<void>;
 }
 
-/**
- * Sanctuary v1.3 WP-V1.3-1 Sentinel Finding Store.
- *
- * Encrypted at-rest persistence for sentinel findings. Sibling to the
- * Upsilon-3 aggregator-store: same fortress-master-key-derived HKDF
- * subkey shape, AAD-bound to the finding_id, retention-aware.
- *
- * Storage layout:
- *   namespace: `_sentinel_findings`
- *   key:       `finding.{finding_id}` (one record per finding)
- *   payload:   AES-256-GCM ciphertext of the JSON-serialized record.
- *   key:       `l2-sentinel-finding-v1` HKDF subkey of fortress master.
- *   AAD:       UTF-8 bytes of `finding_id`.
- *
- * Multi-fortress isolation: HKDF subkey derives from the fortress
- * master key. Two fortresses never produce identical encryption keys
- * for identical finding_ids.
- *
- * Retention: 30 days default, mirroring the audit-log envelope and the
- * aggregator payload store.
- */
-
-interface SentinelFindingStoreOptions {
-    storage: StorageBackend;
-    masterKey: Uint8Array;
-    fortressId: string;
-    /** Operator-tunable retention window. Default 30 days. */
-    retentionDays?: number;
-    /** Wall-clock provider for deterministic tests. */
-    now?: () => Date;
-}
-declare class SentinelFindingStore {
-    private readonly storage;
-    private readonly encryptionKey;
-    private readonly fortressId;
-    private readonly retentionDays;
-    private readonly now;
-    constructor(opts: SentinelFindingStoreOptions);
-    /**
-     * Persist a finding. Truncates the operator-visible summary to
-     * SENTINEL_SUMMARY_MAX_CHARS so the dashboard render stays bounded.
-     * Returns the retention deadline so callers can audit it.
-     */
-    saveFinding(finding: SentinelFinding): Promise<string>;
-    /** Load a single finding by id, or null when absent / corrupted. */
-    loadFinding(findingId: string): Promise<SentinelFinding | null>;
-    /**
-     * List findings, newest first. Optional filters: since (ISO 8601),
-     * severity, sentinel_id, agent_id, limit. Default limit 100.
-     */
-    listFindings(opts?: {
-        since?: string;
-        severity?: SentinelSeverity;
-        sentinelId?: string;
-        agentId?: string;
-        limit?: number;
-    }): Promise<SentinelFinding[]>;
-    /**
-     * Drop expired findings. Returns the count removed.
-     */
-    pruneExpired(now?: Date): Promise<{
-        pruned: number;
-    }>;
-    private decode;
-}
-
 /**
  * Sanctuary v1.3 WP-V1.3-1 Sentinel Dispatcher.
  *
@@ -7509,25 +7525,142 @@ declare class SentinelDispatcher {
 }
 
 /**
- * Sanctuary MCP Server — Principal Dashboard
+ * Sanctuary v1.3 WP-V1.3-3 Omega-1 Coordination Handoff Log.
  *
- * HTTP-based approval channel that serves a real-time web dashboard
- * for human principals to approve/deny agent operations.
+ * 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.
  *
- * 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
+ * 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.
  *
- * 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)
+ * 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.
+ *
+ * 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).
+ *
+ * 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.
+ *
+ * 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;
@@ -7612,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.
@@ -7655,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.
@@ -7666,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