@sanctuary-framework/mcp-server 1.2.4 → 1.2.6

package/dist/index.d.cts

@@ -252,6 +252,43 @@ interface ApprovalChannelConfig {
     webhook_url?: string;
     webhook_secret?: string;
 }
+/**
+ * WP-V1.3-10 Upsilon-2: cross-harness approval-redirect mode.
+ *
+ * `mode` selects how the underlying channel and the aggregator interact when
+ * a Tier 1/2 approval fires for a wrapped agent:
+ *
+ *  - `replace`: the underlying channel is bypassed; the gate's
+ *    `requestApproval()` blocks awaiting the operator's decision through
+ *    the aggregator HTTP `approve`/`deny` routes (or any other surface that
+ *    calls `aggregator.resolve()`). Default behavior when redirect is
+ *    enabled.
+ *  - `notify`: both the underlying channel AND the aggregator run; the
+ *    first decision wins. Right shape for harnesses (e.g. Mastra) where
+ *    full local-prompt suppression is not viable, so the operator still
+ *    sees the prompt locally but ALSO can resolve from the unified inbox.
+ *
+ * `per_agent` is a stub for v1.4 multi-agent fortresses: a map of
+ * `agent_id -> {enabled, mode}` overrides. v1.x ignores this field; the
+ * fortress-level `enabled` + `mode` apply to every wrapped agent in the
+ * fortress (which is currently single-agent in practice). v1.4 adds
+ * agent-id propagation through the gate signature and consults this map.
+ */
+interface ApprovalRedirectPerAgentOverride {
+    enabled?: boolean;
+    mode?: "replace" | "notify";
+}
+interface ApprovalRedirectConfig {
+    /** Master toggle. When false, redirect-mode is off across the fortress. */
+    enabled: boolean;
+    /** How the underlying channel and the aggregator coexist. */
+    mode: "replace" | "notify";
+    /**
+     * Per-agent overrides. v1.x stub — populated entries are validated and
+     * persisted but not enforced. Reserved for v1.4 multi-agent fortresses.
+     */
+    per_agent?: Record<string, ApprovalRedirectPerAgentOverride>;
+}
 /** Complete Principal Policy */
 interface PrincipalPolicy {
     version: number;
@@ -270,6 +307,13 @@ interface PrincipalPolicy {
      * days when absent; values <= 0 fall back to the default.
      */
     concierge_memory_retention_days?: number;
+    /**
+     * WP-V1.3-10 Upsilon-2: cross-harness approval-redirect mode. Optional;
+     * defaults to `{ enabled: false, mode: "replace" }` (preserves legacy
+     * behavior). Operator-toggled via `sanctuary agents config <tenant>
+     * --approval-redirect=<bool>` or by editing principal-policy.yaml.
+     */
+    approval_redirect?: ApprovalRedirectConfig;
 }
 /** Approval request sent to the human */
 interface ApprovalRequest {
@@ -5183,6 +5227,24 @@ interface ReadThreadOptions {
     /** Cap the number of turns returned (oldest-first within the bundle). */
     limit?: number;
 }
+/**
+ * Stable failure-reason enum for `readThreadStrict` (WP-V1.3-9 Tau-2).
+ * Mirrors the shape carried by `operator_concierge_memory_read_failed`
+ * audit payloads so the service emits the cause verbatim.
+ */
+type ConciergeMemoryReadFailure = "decrypt_failed" | "schema_mismatch" | "oversize_bundle" | "io_failed" | "unknown";
+/**
+ * Discriminated result for `readThreadStrict`. The fold-read path uses
+ * this so an empty thread (no bundle) does not look the same as a
+ * corrupted bundle (which must trigger graceful degradation).
+ */
+type ReadThreadStrictResult = {
+    ok: true;
+    turns: ConciergeTurn[];
+} | {
+    ok: false;
+    reason: ConciergeMemoryReadFailure;
+};
 interface ListThreadsOptions {
     /** Cap the number of summaries returned. */
     limit?: number;
@@ -5210,6 +5272,21 @@ declare class ConciergeMemoryStore {
      * audit events; the caller (HTTP route handler) owns audit semantics.
      */
     readThread(threadId: string, opts?: ReadThreadOptions): Promise<ConciergeTurn[]>;
+    /**
+     * Read turns with explicit failure surfacing (WP-V1.3-9 Tau-2). Where
+     * `readThread` collapses every failure mode to an empty array, this
+     * variant returns a discriminated result so the multi-turn fold path
+     * can degrade cleanly + emit `operator_concierge_memory_read_failed`
+     * with a concrete cause.
+     *
+     * - No bundle on disk → `{ ok: true, turns: [] }` (a fresh thread).
+     * - Bundle present, decode + decrypt + schema check pass → ok with turns.
+     * - Bundle present, oversize → `{ ok: false, reason: "oversize_bundle" }`.
+     * - Bundle present, decryption fails → `{ ok: false, reason: "decrypt_failed" }`.
+     * - Bundle present, schema mismatch (version / thread_id) → `schema_mismatch`.
+     * - Storage IO error → `io_failed`.
+     */
+    readThreadStrict(threadId: string, opts?: ReadThreadOptions): Promise<ReadThreadStrictResult>;
     /**
      * Enumerate concierge threads in this fortress with summary metadata.
      * Sorted newest-first by last_turn_at.
@@ -5238,6 +5315,35 @@ declare class ConciergeMemoryStore {
     private withLock;
 }
 
+/**
+ * Closed enum of categories the router may classify a query into. Adding
+ * a category requires updating: this enum, the keyword table, the
+ * fetcher interface, every wiring fetcher, and the test surface.
+ */
+type ContextCategory = "templates" | "agent_state" | "agent_activity" | "audit_log" | "sentinel_findings" | "anomaly_alerts" | "recent_receipts" | "verascore_deltas";
+/**
+ * Caller-supplied data sources. Each fetcher returns plain text the
+ * router stitches into the rendered section. Returning the empty string
+ * (or whitespace only) is treated as "nothing to fold for this category"
+ * and the category drops out of the final categoriesIncluded list.
+ */
+interface ContextFetchers {
+    templates: () => Promise<string>;
+    agent_state: (agentNameHint: string | null) => Promise<string>;
+    agent_activity: (agentNameHint: string | null) => Promise<string>;
+    audit_log: () => Promise<string>;
+    sentinel_findings: () => Promise<string>;
+    anomaly_alerts: () => Promise<string>;
+    recent_receipts: () => Promise<string>;
+    verascore_deltas: () => Promise<string>;
+}
+/**
+ * Auxiliary classifier the caller may supply for the LLM-assist fallback
+ * path. Invoked only when keyword classification returns zero matches
+ * AND the query is non-trivial (>= 8 chars, not a clear greeting).
+ */
+type LlmAssistClassifier = (query: string, categories: readonly ContextCategory[]) => Promise<ContextCategory | "none">;
+
 /**
  * Sanctuary MCP Server — Operator Chat Service
  *
@@ -5342,13 +5448,72 @@ interface OperatorChatServiceDeps {
     /**
      * WP-V1.3-9 Tau-1: optional foundation memory store. When wired,
      * `sendConcierge` dual-writes each operator+concierge turn pair into
-     * the memory store under a session-scoped thread_id. Read-side wiring
-     * (substrate-selector context-fold) lands in Tau-2.
+     * the memory store under a session-scoped thread_id. Tau-2 adds a
+     * read-fold path that surfaces the prior turns to the substrate so
+     * the concierge maintains coherence across a multi-turn session.
      *
      * Omit at construction time to disable memory-side persistence; the
      * existing `OperatorChatStore` write keeps working unchanged.
      */
     conciergeMemory?: ConciergeMemoryStore;
+    /**
+     * WP-V1.3-9 Tau-2: maximum prior turns folded into the substrate
+     * context per round-trip. Defaults to
+     * `DEFAULT_CONCIERGE_HISTORY_WINDOW_TURNS` (10). The current operator
+     * turn is always present; this caps history only.
+     */
+    conciergeHistoryWindowTurns?: number;
+    /**
+     * WP-V1.3-9 Tau-2: prior turns older than this many milliseconds are
+     * excluded from the active fold even when they remain on disk.
+     * Defaults to `DEFAULT_CONCIERGE_HISTORY_FRESHNESS_MS` (24h).
+     */
+    conciergeHistoryFreshnessMs?: number;
+    /**
+     * WP-V1.3-9 Tau-2: rough token budget for the prior-conversation
+     * portion of the substrate context. Estimated as ~4 chars per token.
+     * Defaults to `DEFAULT_CONCIERGE_HISTORY_TOKEN_BUDGET` (500). The
+     * static reference block + fortress sections are NOT subject to this
+     * budget; only the prior-conversation fold is pruned oldest-first.
+     */
+    conciergeHistoryTokenBudget?: number;
+    /**
+     * WP-V1.3-9 Tau-2: how long an active session may stay quiet before
+     * the next `sendConcierge` allocates a fresh thread_id. Defaults to
+     * `DEFAULT_CONCIERGE_SESSION_TTL_MS` (24h). Does not delete the prior
+     * thread; it remains readable through the memory store.
+     */
+    conciergeSessionTtlMs?: number;
+    /**
+     * Optional clock for the session-TTL + freshness checks. Tests inject
+     * a deterministic clock; production lets the default `Date.now`-based
+     * implementation run.
+     */
+    conciergeClock?: () => number;
+    /**
+     * WP-V1.3-9 Tau-3: caller-supplied fetchers for dynamic context
+     * injection. When wired alongside the substrate selector, every
+     * `sendConcierge` round-trip routes the operator's query through the
+     * concierge-context-router and folds matching live data into the
+     * substrate prompt between the static Sanctuary reference and the
+     * prior-turns fold. Omit to disable dynamic context (the static
+     * reference + prior-turns paths keep working unchanged).
+     */
+    conciergeContextFetchers?: ContextFetchers;
+    /**
+     * WP-V1.3-9 Tau-3: optional LLM-assist classifier for queries that
+     * fail keyword classification. Coordinator-CTO bake: when wired, the
+     * service routes the auxiliary classifier call through the substrate
+     * selector at the same `concierge` surface, so the auxiliary call
+     * shares the operator's substrate choice and never opens a new
+     * outbound surface.
+     */
+    conciergeContextLlmAssist?: LlmAssistClassifier;
+    /**
+     * WP-V1.3-9 Tau-3: rough token budget for the dynamic-context fold.
+     * Defaults to `DEFAULT_CONCIERGE_DYNAMIC_CONTEXT_BUDGET` (2000).
+     */
+    conciergeDynamicContextBudget?: number;
 }
 declare class OperatorChatService {
     private store;
@@ -5359,6 +5524,14 @@ declare class OperatorChatService {
     private piiFilter?;
     private conciergeMaxTokens;
     private memory?;
+    private historyWindowTurns;
+    private historyFreshnessMs;
+    private historyTokenBudget;
+    private sessionTtlMs;
+    private clock;
+    private contextFetchers?;
+    private contextLlmAssist?;
+    private dynamicContextBudget;
     /**
      * In-memory thread_id assigned to the active concierge session.
      * The first sendConcierge call after construction allocates a fresh
@@ -5366,6 +5539,14 @@ declare class OperatorChatService {
      * folds the prior turns into context. Cleared by `resetConciergeMemoryThread`.
      */
     private activeMemoryThreadId?;
+    /**
+     * Wall-clock ms of the most recent sendConcierge that touched the
+     * active session thread. Drives the WP-V1.3-9 Tau-2 session-TTL
+     * check: a fresh sendConcierge after `sessionTtlMs` of quiet
+     * allocates a new thread_id even though the prior one is still
+     * readable from the memory store.
+     */
+    private lastInteractionAt?;
     constructor(deps: OperatorChatServiceDeps);
     /**
      * Operator submit on the concierge surface. Persists the operator's
@@ -5378,6 +5559,13 @@ declare class OperatorChatService {
      * operator sees on the page (no silent dropping).
      */
     sendConcierge(query: string): Promise<ConciergeResponse>;
+    /**
+     * Emit the WP-V1.3-9 Tau-2 graceful-degradation audit event. Pulled
+     * out of `sendConcierge` so the read-fold path stays readable. Emits
+     * with `result: "failure"` since the concierge fell back to
+     * single-turn mode for this round-trip.
+     */
+    private emitMemoryReadFailed;
     /**
      * Read the persisted concierge thread, oldest message first. Returns
      * an empty array when no thread exists yet.
@@ -5424,6 +5612,14 @@ declare class OperatorChatService {
      *   ## Sanctuary reference
      *   <static domain reference block>
      *
+     *   ## Live fortress context          ← WP-V1.3-9 Tau-3, when present
+     *   ### <Category>
+     *   <fetcher payload>
+     *
+     *   ## Prior conversation             ← WP-V1.3-9 Tau-2, when present
+     *   OPERATOR: ...
+     *   CONCIERGE: ...
+     *
      *   ## Recent activity
      *   <recentActivity output>
      *
@@ -5433,8 +5629,39 @@ declare class OperatorChatService {
      *   ## Open inbox
      *   <openInbox output>
      *   ```
+     *
+     * The substrate selector ships a `context: string` shape (not a
+     * messages array), so multi-turn coherence is folded as a structured
+     * prior-conversation section with explicit OPERATOR / CONCIERGE
+     * boundaries. Coordinator-CTO guidance: prefer messages-array shape
+     * if available; the v1.2 selector does not expose one, so structured
+     * serialization is the canonical path for v1.3.
      */
     private assembleConciergeContext;
+    /**
+     * Run the WP-V1.3-9 Tau-3 dynamic-context fold for a single round-
+     * trip. Fail-soft on every axis: missing fetchers short-circuit to
+     * an empty fold, fetcher failures emit a per-category audit event
+     * and are omitted from the rendered section, an LLM-assist failure
+     * proceeds with no fold. Returns the rendered section + the list of
+     * categories whose data made it into the section (used for the
+     * round-trip audit emission).
+     */
+    private runDynamicContextFold;
+    /**
+     * Emit the WP-V1.3-9 Tau-3 fetcher-failure audit event. Pulled out
+     * of the fold path so the dynamic-context handler stays readable.
+     * Emits with `result: "failure"` since the named category dropped
+     * from the rendered section for this round-trip.
+     */
+    private emitContextFetcherFailed;
+    /**
+     * Render the prior-conversation section with token-budget enforcement
+     * (WP-V1.3-9 Tau-2). Drops oldest turns first when the rendered
+     * section exceeds `historyTokenBudget`. Returns an empty string when
+     * the input is empty or when the budget excludes every turn.
+     */
+    private formatPriorTurnsSection;
     private emit;
 }
 
@@ -5918,6 +6145,87 @@ interface V11Bindings {
     operatorChatService?: OperatorChatService;
 }
 
+/**
+ * Sanctuary v1.3 WP-V1.3-10 Cross-Harness Approval Inbox Upsilon-3
+ *
+ * At-rest encrypted persistence for full request payloads tied to
+ * AggregatedApproval entries. Sibling store to ApprovalAggregator: the
+ * aggregator's own entry record (status, provenance, hashes) is persisted
+ * by the aggregator class under `_approval_aggregator`; this store holds
+ * the original request payload separately under
+ * `_approval_aggregator_payloads` so the operator can replay the full
+ * payload after a server restart.
+ *
+ * Storage layout:
+ *   namespace: `_approval_aggregator_payloads`
+ *   key:       `payload.{aggregator_id}` (one record per approval)
+ *   payload:   AES-256-GCM ciphertext of the JSON-serialised bundle.
+ *   key:       `l2-approval-aggregator-payload-v1` HKDF subkey of fortress
+ *              master.
+ *   AAD:       UTF-8 bytes of `aggregator_id`. Swapping records across
+ *              aggregator_ids breaks the auth tag. Castle-walking
+ *              discipline: the encryption boundary holds even against
+ *              on-disk shuffle.
+ *
+ * Retention:
+ * Each bundle carries an ISO-8601 `retention_until`. `pruneExpired()`
+ * iterates payloads and drops entries whose retention_until is in the
+ * past. Default retention is 30 days, mirroring the audit-log retention
+ * envelope. Operator override flows through the aggregator's deps.
+ *
+ * Multi-fortress isolation:
+ * The HKDF subkey is derived from the fortress master key. Two
+ * fortresses never produce identical encryption keys for identical
+ * aggregator_ids. Isolation is enforced cryptographically; the AAD
+ * binds the ciphertext to a specific aggregator_id within a fortress.
+ */
+
+interface AggregatorPayloadStoreOptions {
+    /** Storage backend that persists the encrypted bundles. */
+    storage: StorageBackend;
+    /** 32-byte fortress master key. */
+    masterKey: Uint8Array;
+    /** Stable fortress id stamped on every bundle for audit clarity. */
+    fortressId: string;
+    /** Operator-tunable retention window. Default 30 days. */
+    retentionDays?: number;
+}
+/**
+ * Encrypted, AAD-bound, retention-aware payload persistence for the
+ * cross-harness approval inbox.
+ */
+declare class AggregatorPayloadStore {
+    private readonly storage;
+    private readonly encryptionKey;
+    private readonly fortressId;
+    private readonly retentionDays;
+    constructor(opts: AggregatorPayloadStoreOptions);
+    /**
+     * Persist `payload` under the given aggregator_id. Idempotent; calling
+     * twice with the same id rewrites the bundle (retention_until is
+     * recomputed). Returns the bundle's retention_until ISO-8601 timestamp
+     * so callers can log it.
+     */
+    savePayload(aggregatorId: string, payload: unknown): Promise<string>;
+    /**
+     * Read the persisted payload for the aggregator_id. Returns null if no
+     * bundle exists, the bundle is corrupted, or AAD binding fails.
+     */
+    loadPayload(aggregatorId: string): Promise<unknown>;
+    /**
+     * Delete the persisted payload. Returns true when a bundle was removed,
+     * false when none existed.
+     */
+    deletePayload(aggregatorId: string): Promise<boolean>;
+    /**
+     * Drop expired payload bundles. Returns the count of bundles pruned.
+     * Caller wires this into the cocoon-unlock initialization path.
+     */
+    pruneExpired(now?: Date): Promise<{
+        pruned: number;
+    }>;
+}
+
 /**
  * Sanctuary v1.3 WP-V1.3-10 Cross-Harness Approval Inbox Upsilon-1
  *
@@ -5955,6 +6263,19 @@ interface V11Bindings {
  *  - `expired`: pending past TTL on a `list()` poll without a resolution.
  */
 type AggregatedApprovalStatus = "pending" | "approved" | "denied" | "timeout" | "expired";
+/**
+ * One step in the Castle Architecture enforcement chain that led to this
+ * approval. Layers are: l1 (Castle Wall, OS-level egress), l2 (Sentinel +
+ * cooperative MCP gate), l3 (selective disclosure), l4 (reputation).
+ * v1.3 Upsilon-3 ships the schema; default resolver populates a single
+ * `l2` entry. Future Castle Wall wiring will extend the chain when a
+ * payload's egress was first observed by the kernel filter.
+ */
+interface EnforcementLayerEvent {
+    layer: "l1" | "l2" | "l3" | "l4";
+    event: string;
+    timestamp: string;
+}
 /**
  * Normalized record the aggregator stores per approval. Field set is
  * additive-stable; new fields go behind `?` so existing dashboards keep
@@ -5999,6 +6320,15 @@ interface AggregatedApproval {
      * (the cross-link signal lives on the aggregator side only).
      */
     hub_inbox_item_id?: string;
+    /**
+     * Castle Architecture enforcement-layer chain that led to this
+     * approval. Populated by the optional `resolveEnforcementChain` deps
+     * hook; default returns a single `l2` step (cooperative MCP gate
+     * fired). Persisted with the entry so the operator-replay surface can
+     * render the enforcement context after a server restart. v1.3
+     * Upsilon-3.
+     */
+    enforcement_chain?: EnforcementLayerEvent[];
 }
 /**
  * Source-context resolver. Called once per ingest to map gate context to
@@ -6087,6 +6417,23 @@ interface ApprovalAggregatorDeps {
      * hub inbox store.
      */
     resolveHubInboxItemId?: (event: ApprovalGateEvent) => string | undefined;
+    /**
+     * Optional at-rest payload store. When provided, the aggregator
+     * persists each request payload via `savePayload` on ingest, and
+     * rehydrates payloads on `getFullPayload` if the in-memory map lost
+     * them (e.g. after a server restart). Upsilon-3 surface; absent in
+     * Upsilon-1 / Upsilon-2 deployments, where payloads remain in-memory
+     * only.
+     */
+    payloadStore?: AggregatorPayloadStore;
+    /**
+     * Optional resolver for the Castle Architecture enforcement chain
+     * leading to this approval. Default returns a single `l2` step
+     * (cooperative MCP gate fired). When the Castle Wall (Layer 1) ships,
+     * its kernel-filter observer can populate richer chains by passing a
+     * resolver here.
+     */
+    resolveEnforcementChain?: (event: ApprovalGateEvent) => EnforcementLayerEvent[];
 }
 /**
  * Aggregator state. The map is hydrated lazily from the encrypted
@@ -6103,6 +6450,8 @@ declare class ApprovalAggregator {
     private readonly now;
     private readonly resolveSourceContext;
     private readonly resolveHubInboxItemId;
+    private readonly payloadStore;
+    private readonly resolveEnforcementChain;
     /** Cached entries by `aggregator_id`. */
     private readonly entries;
     /** Dedup index: `${harness}|${agent}|${audit_id}` -> aggregator_id. */
@@ -6141,10 +6490,48 @@ declare class ApprovalAggregator {
     }): Promise<AggregatedApproval[]>;
     /**
      * Return the original (unhashed) request payload for the entry. Returns
-     * `null` when the entry is unknown or the payload was evicted (e.g. the
-     * process restarted; payloads are in-memory only at v1.3 Upsilon-1).
+     * `null` when the entry is unknown. When the in-memory payload map has
+     * been evicted (e.g. after a server restart) and a `payloadStore` was
+     * provided, the at-rest bundle is decrypted and the in-memory map is
+     * refilled. Audit emission lives on the `*WithAudit` variant; this base
+     * accessor is silent so internal callers can read without polluting the
+     * audit trail.
      */
     getFullPayload(aggregatorId: string): Promise<unknown>;
+    /**
+     * Return the entry record for the given id, or null when unknown.
+     * Idempotent. v1.3 Upsilon-3.
+     */
+    getEntry(aggregatorId: string): Promise<AggregatedApproval | null>;
+    /**
+     * Audited variant of `getFullPayload`. Emits the
+     * `cross_harness_approval_payload_decrypted` audit event before
+     * returning. Used by the operator-facing /payload replay route.
+     * v1.3 Upsilon-3.
+     */
+    getFullPayloadWithAudit(aggregatorId: string, operatorId: string): Promise<unknown>;
+    /**
+     * Return the audit-log entries that led to and surround this approval.
+     * Best-effort matching: aggregator-side emissions (AGGREGATED, RESOLVED,
+     * DEDUPED, replay events) all carry `details.aggregator_id` and link
+     * directly. Gate-side emissions (`gate_*:operation`) do not carry the
+     * aggregator id at v1.3, so they are matched via timestamp window
+     * (entry.created_at to entry.resolved_at + 1s, or expires_at + 1s while
+     * pending) and operation suffix. Emits AUDIT_TRAIL_VIEWED on call.
+     * v1.3 Upsilon-3.
+     */
+    getAuditTrail(aggregatorId: string, operatorId: string): Promise<AuditEntry[]>;
+    /**
+     * List historical (resolved) approvals. Excludes pending entries by
+     * design: `list()` is the pending-inbox surface and `getHistory()` is
+     * the resolved-replay surface. Emits REPLAYED on each call. v1.3
+     * Upsilon-3.
+     */
+    getHistory(opts: {
+        status?: AggregatedApprovalStatus;
+        sinceTs?: string;
+        limit?: number;
+    } | undefined, operatorId: string): Promise<AggregatedApproval[]>;
     /**
      * Resolve an entry. Used by both:
      *   1. The gate wire-up on channel-decision return.