@sanctuary-framework/mcp-server 1.2.4 → 1.2.5

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.
@@ -5342,13 +5419,48 @@ 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;
 }
 declare class OperatorChatService {
     private store;
@@ -5359,6 +5471,11 @@ declare class OperatorChatService {
     private piiFilter?;
     private conciergeMaxTokens;
     private memory?;
+    private historyWindowTurns;
+    private historyFreshnessMs;
+    private historyTokenBudget;
+    private sessionTtlMs;
+    private clock;
     /**
      * In-memory thread_id assigned to the active concierge session.
      * The first sendConcierge call after construction allocates a fresh
@@ -5366,6 +5483,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 +5503,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 +5556,11 @@ declare class OperatorChatService {
      *   ## Sanctuary reference
      *   <static domain reference block>
      *
+     *   ## Prior conversation             ← WP-V1.3-9 Tau-2, when present
+     *   OPERATOR: ...
+     *   CONCIERGE: ...
+     *   ---
+     *
      *   ## Recent activity
      *   <recentActivity output>
      *
@@ -5433,8 +5570,22 @@ 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;
+    /**
+     * 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;
 }
 

package/dist/index.d.ts

@@ -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.
@@ -5342,13 +5419,48 @@ 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;
 }
 declare class OperatorChatService {
     private store;
@@ -5359,6 +5471,11 @@ declare class OperatorChatService {
     private piiFilter?;
     private conciergeMaxTokens;
     private memory?;
+    private historyWindowTurns;
+    private historyFreshnessMs;
+    private historyTokenBudget;
+    private sessionTtlMs;
+    private clock;
     /**
      * In-memory thread_id assigned to the active concierge session.
      * The first sendConcierge call after construction allocates a fresh
@@ -5366,6 +5483,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 +5503,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 +5556,11 @@ declare class OperatorChatService {
      *   ## Sanctuary reference
      *   <static domain reference block>
      *
+     *   ## Prior conversation             ← WP-V1.3-9 Tau-2, when present
+     *   OPERATOR: ...
+     *   CONCIERGE: ...
+     *   ---
+     *
      *   ## Recent activity
      *   <recentActivity output>
      *
@@ -5433,8 +5570,22 @@ 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;
+    /**
+     * 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;
 }