@sanctuary-framework/mcp-server 1.2.11 → 1.2.13

package/dist/index.d.cts

@@ -3522,6 +3522,44 @@ interface ExitBundleArtifactEntry {
      */
     subkind?: string;
 }
+/**
+ * did:web pointer embedded in the identity binding when the operator
+ * has issued a did:web identifier for the source fortress and asked
+ * the exit-bundle exporter to publish that pointer alongside the
+ * manifest (Recognition-Layer Path C primary build 2).
+ *
+ * The bundle does NOT carry the did:web DID Document itself; the
+ * receiving regime resolves the DID Document via standard DNS + TLS
+ * against `authority_host`. That dependency is intentional: it is
+ * the operator's HTTPS infrastructure that publishes the document,
+ * not Sanctuary's, and it is the receiving regime's resolver that
+ * verifies the document, not Sanctuary's. Recognition flows along
+ * the web's existing trust chain without trusting Sanctuary as a
+ * middleman.
+ *
+ * The signature scheme over the manifest body covers this field by
+ * construction (it lives inside `ExitBundleManifestBody`), so an
+ * attacker who substituted the did:web pointer without re-signing
+ * the body would be rejected at the existing manifest-signature
+ * gate.
+ */
+interface ExitBundleDidWebBinding {
+    /**
+     * The did:web URI string the operator published, e.g.,
+     * `did:web:alice.example.com:fortress:abc123`. The receiving
+     * regime resolves this to fetch the DID Document.
+     */
+    identifier: string;
+    /** Authority host the operator's DID Document is published on. */
+    authority_host: string;
+    /**
+     * Optional ISO 8601 timestamp at which the operator confirmed
+     * HTTPS publication. Surfaces to the verifier as evidence that
+     * the operator believes the document is reachable; the verifier
+     * still re-resolves to confirm.
+     */
+    published_at?: string;
+}
 /**
  * Identity binding embedded in the manifest. Carries only public material.
  */
@@ -3534,6 +3572,17 @@ interface ExitBundleIdentityBinding {
     fortress_master_pubkey: string;
     /** Optional DID, when one is bound to this identity. */
     did?: string;
+    /**
+     * Optional did:web pointer (Recognition-Layer Path C primary build 2).
+     * Present only when the operator has issued a did:web identifier
+     * for the source fortress AND has not explicitly opted out at
+     * export time via `--include-did-web=false`. The receiving regime
+     * resolves the pointer via DNS + TLS to verify the bundle's origin
+     * without trusting Sanctuary as intermediary. Absent on bundles
+     * exported before the recognition-layer integration shipped
+     * (backward-compatible).
+     */
+    did_web?: ExitBundleDidWebBinding;
 }
 /**
  * v1 manifest body — what the operator's fortress-master signs.
@@ -3925,6 +3974,37 @@ declare class FilesystemStorage implements StorageBackend {
     totalSize(): Promise<number>;
 }
 
+interface ResolveDidWebOpts {
+    /**
+     * Hosts the operator has explicitly allowed for outbound did:web
+     * resolution. Empty array means resolution is disabled and the
+     * call returns synchronously with `host_not_allowed`. This is
+     * the load-bearing opt-in surface for the no-outbound-by-default
+     * rule; the kernel-level Castle Wall egress filter enforces the
+     * same allowlist independently.
+     */
+    allowed_hosts: string[];
+    /** Resolution timeout. Defaults to 5000ms. */
+    timeout_ms?: number;
+    /**
+     * Optional fetcher override for tests. Defaults to globalThis.fetch.
+     * Production callers should leave this undefined.
+     */
+    fetcher?: (url: string, init?: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        ok: boolean;
+        status: number;
+        json: () => Promise<unknown>;
+    }>;
+    /**
+     * Optional expected Ed25519 public key. When set, the resolved
+     * document's verificationMethod[0].publicKeyJwk.x must match
+     * (base64url-encoded). Mismatch returns `signature_mismatch`.
+     */
+    expected_public_key?: Uint8Array;
+}
+
 /**
  * Sanctuary MCP Server — Key Derivation
  *
@@ -4052,6 +4132,21 @@ interface ExportExitBundleOptions {
      * When omitted, the export self-generates an id.
      */
     exportApprovalAuditId?: string;
+    /**
+     * Recognition-Layer Path C primary build 2: optional did:web binding
+     * to embed in the manifest's identity_binding. When provided, the
+     * export validates that the binding's identifier resolves (per the
+     * did:web spec) to a pointer over the same authority host as
+     * `binding.authority_host`, and that the operator's fortress public
+     * key matches the key the did:web identifier was issued against
+     * (the export does NOT re-fetch the published DID Document; that
+     * check is the receiving regime's job at import time).
+     *
+     * Omit to skip did:web embedding entirely. Receiving regimes that
+     * import the bundle treat absence as backward-compatible (no
+     * recognition-layer verification step).
+     */
+    didWeb?: ExitBundleDidWebBinding;
 }
 interface ExportExitBundleResult {
     bundle_dir: string;
@@ -4090,6 +4185,40 @@ interface ImportExitBundleOptions {
      * operator in to an explicit relaxed verdict (Tier 1 confirmation in CLI).
      */
     acceptUnverifiableAttestations?: boolean;
+    /**
+     * Recognition-Layer Path C primary build 2: hosts the importing
+     * operator has explicitly allowed for outbound did:web resolution.
+     * Empty array means resolution refuses to leave the fortress
+     * (preserves no-outbound-by-default). The same allowlist is also
+     * enforced at the kernel level by the operator's Castle Wall egress
+     * filter; this option is the application-level coordinator.
+     *
+     * Absent + did_web present in manifest = the importer surfaces a
+     * warning and proceeds with the manifest-signature check alone
+     * (degraded confidence). The operator can re-run with the
+     * allowlist set or with `skipDidWebVerify: true`.
+     */
+    didWebAllowedHosts?: string[];
+    /**
+     * Recognition-Layer Path C primary build 2: when true, the importer
+     * skips did:web resolution entirely even if the manifest carries a
+     * did_web binding. Operator surface: CLI flag
+     * `--skip-did-web-verify`. Tradeoff is operator-visible: skipping
+     * loses the recognition-layer cross-check that the bundle's claimed
+     * origin matches the published DID Document.
+     */
+    skipDidWebVerify?: boolean;
+    /**
+     * Recognition-Layer Path C primary build 2: optional fetcher
+     * override for tests. Defaults to globalThis.fetch via the did:web
+     * foundation's resolver. Production callers leave undefined.
+     */
+    didWebFetcher?: ResolveDidWebOpts["fetcher"];
+    /**
+     * Recognition-Layer Path C primary build 2: resolution timeout.
+     * Defaults to the did:web foundation's 5000ms default.
+     */
+    didWebTimeoutMs?: number;
 }
 /**
  * Structured error raised by `importExitBundle` for codes the CLI / hub want
@@ -7626,6 +7755,250 @@ declare class HandoffLog {
     private normalize;
 }
 
+/**
+ * Sanctuary v1.3 WP-V1.3-3 Omega-2 Context-Transfer Extractor.
+ *
+ * Decomposes a handoff into the structured TRANSFERRED-vs-WITHHELD
+ * breakdown the operator's Coordination view renders. Operates on a
+ * `HandoffEntryDetail` (Omega-1 surface) and returns a
+ * `ContextTransferBreakdown`.
+ *
+ * Why this matters: the operator needs to know not just THAT a
+ * handoff happened, but WHAT crossed the boundary. Per-handoff
+ * context-transfer breakdown makes Castle Layer 3 cooperative-MCP
+ * integrity legible at the operator UX layer.
+ *
+ * Three resolution paths in fixed order; first one that produces
+ * usable output wins. Higher paths produce higher confidence.
+ *
+ * Path A: structured-source events. Triggered when the source audit
+ * details payload carries explicit `transferred` and / or `withheld`
+ * arrays / objects. Future Tau-X work will wire the coordinator to
+ * emit these explicitly; the extractor handles them today so when
+ * those emissions arrive, no further code change is needed. Ships
+ * with confidence 1.0.
+ *
+ * Path B: composition events. Triggered when the source audit
+ * operation matches `composition_completed` (Concordia bridge).
+ * Decomposes via the receipt-references graph: items in the receipt
+ * are transferred; items in the source-state-snapshot but not in the
+ * receipt are withheld. Composition events do not flow through the
+ * audit log today (mesh-only signed envelopes; same finding as Phi-3
+ * cross-agent-chatter watcher and Omega-1's HandoffLog union scope);
+ * Path B is scaffolded so when composition wires audit emissions,
+ * extraction extends. Ships with confidence 0.9 when present.
+ *
+ * Path C: heuristic fallback. Triggered when neither A nor B fires
+ * (the common case at v1.3 Omega-2 since current Tau-3 audit
+ * emissions are minimal and composition is mesh-only). Derives
+ * transferred from the policy_rule_id (cross_harness_approval) or
+ * task-scope category (v1.1_local_handoff via the source audit
+ * payload's reason_class + status). Ships with confidence 0.5.
+ *
+ * LLM-assist fallback. Optional. Triggered when Path C returns a
+ * low-confidence result (no clear category match) AND a substrate
+ * selector is supplied. Routes through `selector.invokeClassify` on
+ * the coordination surface. Failure is silent (degrade-not-destroy);
+ * the caller still gets the heuristic Path C result with confidence
+ * 0.3. Ships with confidence 0.6 on success.
+ *
+ * Castle-walking discipline:
+ *  - No new outbound surface. The substrate selector is the only
+ *    LLM-capable channel and is opt-in via dependency injection.
+ *  - Reads server-local audit log + Concordia receipts only.
+ *  - Encryption boundary holds.
+ *  - Multi-fortress isolation preserved by the caller-supplied
+ *    HandoffEntryDetail (which is fortress-scoped via Omega-1).
+ */
+
+/** Extractor dependency contract. */
+interface ContextTransferExtractorDeps {
+    /** Optional LLM-assist substrate selector. Off by default. */
+    substrateSelector?: SubstrateSelector;
+}
+
+/**
+ * Sanctuary v1.3 WP-V1.3-3 Omega-3 Workflow Grouper.
+ *
+ * CLOSES WP-V1.3-3 Coordination Handoff Visualization. Omega-1 (#191)
+ * shipped the chronological handoff log; Omega-2 (#196) shipped the
+ * per-handoff context-transfer breakdown; Omega-3 lifts isolated
+ * handoff events into multi-handoff WORKFLOWS so the operator finally
+ * sees the shape of a multi-agent collaboration as a single object:
+ * who started it, who participated, how recently it was active, and
+ * whether it is still in progress, stalled, or done.
+ *
+ * Pure functions. No I/O, no clock side effects beyond the optional
+ * `now` argument for deterministic state determination. Tests inject
+ * synthetic `HandoffEntry[]` and assert the grouping + state
+ * decisions directly.
+ *
+ * Grouping algorithm:
+ *
+ *   1. Explicit link path: handoffs whose `workflow_link` field is
+ *      non-null group by that key. (At v1.3 Omega-1, Omega-1's
+ *      `normalize()` always sets the field to null. Omega-3 still
+ *      reads it because future Tau-X work will populate the field
+ *      from coordinator-emitted audit payloads, at which point
+ *      explicit grouping is the high-confidence path and the heuristic
+ *      becomes the fallback.)
+ *
+ *   2. Heuristic chain path: among handoffs without an explicit link,
+ *      sort by `observed_at` ascending and walk. A handoff joins an
+ *      existing workflow when (a) it shares at least one agent
+ *      (sender or recipient) with the most recent member of that
+ *      workflow AND (b) the time gap is at most HEURISTIC_WINDOW_MS
+ *      (5 minutes). Otherwise it starts a new workflow.
+ *
+ *      This relaxes the literal "same source-target pair within 5
+ *      minutes" reading of the WP-V1.3-3 scope-lock to also handle
+ *      multi-hop chains like Cline -> OpenClaw -> Cursor, which is
+ *      what the operator-facing example in the scope-lock describes.
+ *      Without this relaxation, every hop in a chain becomes its own
+ *      "workflow" of one, and the dashboard surface loses the
+ *      legibility the WP-V1.3-3 acceptance gate promises. Documented
+ *      as a deviation in the PR body; consistent with how Phi-3
+ *      cross-agent-chatter shipped its connectivity heuristic.
+ *
+ * Root handoff: the oldest handoff in a workflow group. (At v1.3 there
+ * is no audit-log surface for "this handoff was caused by handoff X",
+ * so the chronological-oldest is the load-bearing root signal; when
+ * Tau-X wires causal-link payloads, this rule extends without API
+ * change.)
+ *
+ * State determination (in priority order):
+ *
+ *   - `completed`: the last member's recipient is OPERATOR_PSEUDO_AGENT
+ *     (the workflow returned to the operator for approval / done),
+ *     OR the workflow has crossed >=2 hops and the last member returns
+ *     to the workflow's root agent (cycle closure).
+ *   - `stalled`: no member observed within STALL_THRESHOLD_MS (2h) of
+ *     `now`.
+ *   - `in_progress`: recent member within STALL_THRESHOLD_MS, no
+ *     completion signal.
+ *   - `unknown`: insufficient evidence (e.g., an empty member list,
+ *     which the grouper never emits but which we accept defensively
+ *     for downstream callers that synthesize Workflow objects).
+ *
+ * Castle-walking discipline:
+ *
+ *   - No outbound surface. Pure computation over already-server-local
+ *     `HandoffEntry` records.
+ *   - No LLM call. The heuristic is rule-based.
+ *   - Multi-fortress isolation: the grouper takes whatever input it
+ *     receives; the caller (a `HandoffLog` instance scoped to ONE
+ *     fortress) is responsible for not mixing fortress data. The
+ *     route layer reads through `HandoffLog.query()` which already
+ *     enforces fortress boundary at the encryption layer.
+ *
+ * Out of scope for Omega-3 (deferred to v1.4+ federation): cross-
+ * fortress workflow tracking. Workflow templating + operator-action
+ * UI on stalled workflows ("auto-restart") are v1.5+ scope.
+ */
+
+/** Stable lifecycle-state enum surfaced into the operator UI. */
+type WorkflowState = "in_progress" | "completed" | "stalled" | "unknown";
+/**
+ * One multi-handoff workflow grouped from the underlying handoff log.
+ *
+ * `workflow_id` is deterministic (SHA-256 of the root handoff's
+ * `entry_id` truncated to 32 hex chars) so the same workflow re-
+ * derives identical ids across server restarts. Tests and the SSE
+ * stream rely on this stability for diff-based state-change
+ * emission.
+ *
+ * `member_handoffs` is sorted oldest-first and INCLUDES the root.
+ * `involved_agents` is deduplicated, alphabetically ordered. Empty
+ * pseudo-agent strings are dropped; the OPERATOR_PSEUDO_AGENT is
+ * preserved as a member because it signals completion.
+ */
+interface Workflow {
+    workflow_id: string;
+    root_handoff: HandoffEntry;
+    member_handoffs: HandoffEntry[];
+    state: WorkflowState;
+    started_at: string;
+    last_activity_at: string;
+    involved_agents: string[];
+}
+
+/**
+ * Sanctuary v1.3 WP-V1.3-3 Omega-3 Workflow State Tracker.
+ *
+ * Tracks the most-recently-observed `state` for each workflow_id so
+ * the list-route handler can emit a `coordination_workflow_state_changed`
+ * audit event when a workflow transitions (e.g., from `in_progress`
+ * to `stalled`). Coordination state changes are operator-relevant
+ * signals; the tracker makes them legible without coupling the pure
+ * grouper to side effects.
+ *
+ * The tracker is fortress-scoped: callers construct one instance per
+ * `HandoffLog` (which is itself per-fortress). Different fortresses
+ * cannot leak state transitions into each other's audit logs because
+ * each fortress has its own tracker holding its own snapshot map.
+ *
+ * Sovereignty invariants:
+ *
+ *   - No outbound surface. The tracker is a stateful diff observer
+ *     over input from `groupHandoffsIntoWorkflows()`; it never reaches
+ *     the network and never reads storage on its own.
+ *   - No LLM call.
+ *   - Pure modulo the in-memory snapshot map. `observe()` is the only
+ *     mutating call.
+ *
+ * Threading: callers MUST NOT share a single tracker between
+ * concurrent observers; the route handler in `handoff-routes.ts`
+ * already holds the dispatch-side lock via the request lifecycle.
+ */
+
+/**
+ * One emitted state-change event. The route handler audit-emits this
+ * as `coordination_workflow_state_changed` and (optionally) pushes it
+ * to SSE subscribers so the dashboard tab updates without a poll.
+ */
+interface WorkflowStateChange {
+    workflow_id: string;
+    previous_state: WorkflowState | "unobserved";
+    new_state: WorkflowState;
+    observed_at: string;
+}
+interface WorkflowStateTrackerOptions {
+    /**
+     * Wall-clock provider for the emitted `observed_at` timestamp.
+     * Defaults to a fresh `Date.now()` on each emit. Tests inject a
+     * fixed clock so audit emissions stay deterministic.
+     */
+    now?: () => Date;
+}
+declare class WorkflowStateTracker {
+    private readonly states;
+    private readonly now;
+    constructor(opts?: WorkflowStateTrackerOptions);
+    /**
+     * Diff the supplied workflow list against the last-observed states.
+     * Returns the set of transitions detected this call; the tracker
+     * mutates its internal map to reflect the new states.
+     *
+     * Transitions emitted:
+     *   - First observation of a workflow (`previous_state` is the
+     *     sentinel `unobserved`). Lets the route handler audit-emit
+     *     the initial state so the operator sees workflows as they
+     *     surface, not only when they change.
+     *   - Subsequent observation where `previous_state !== new_state`.
+     */
+    observe(workflows: ReadonlyArray<Workflow>): WorkflowStateChange[];
+    /**
+     * Drop a workflow's recorded state. Surfaced for tests + future
+     * "operator dismissed this workflow" affordance; not currently
+     * called by the production wiring.
+     */
+    forget(workflowId: string): void;
+    /** Reset the tracker. Tests use this between runs. */
+    reset(): void;
+    /** Read-only view of the current snapshot. Useful for diagnostics. */
+    snapshot(): ReadonlyMap<string, WorkflowState>;
+}
+
 /**
  * Sanctuary v1.3 WP-V1.3-3 Omega-1 Coordination handoff HTTP routes.
  *
@@ -7754,6 +8127,8 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
      */
     private handoffLog;
     private handoffEventBridge;
+    private handoffContextTransfer;
+    private workflowStateTracker;
     private handoffAuditLog;
     private handoffOperatorId;
     constructor(config: DashboardConfig);
@@ -7810,6 +8185,19 @@ declare class DashboardApprovalChannel implements ApprovalChannel {
         eventBridge?: HandoffEventBridge | null;
         auditLog?: AuditLog | null;
         operatorId?: string | null;
+        /**
+         * v1.3 WP-V1.3-3 Omega-2: context-transfer extractor deps. When
+         * provided, the handoff detail route enriches its response with a
+         * `context_transfer_breakdown` field.
+         */
+        contextTransfer?: ContextTransferExtractorDeps | null;
+        /**
+         * v1.3 WP-V1.3-3 Omega-3: workflow state tracker. When provided,
+         * the workflow routes emit `coordination_workflow_state_changed`
+         * audit events as the tracker observes transitions and push them
+         * to SSE subscribers.
+         */
+        workflowStateTracker?: WorkflowStateTracker | null;
     }): void;
     /**
      * v1.3 WP-V1.3-10 dispatch entry point. Called from `handleRequest`