@sanctuary-framework/mcp-server 1.2.6 → 1.2.7

package/dist/index.d.cts

@@ -5315,27 +5315,204 @@ declare class ConciergeMemoryStore {
     private withLock;
 }
 
+/**
+ * Sanctuary MCP Server, Operator Chat, Concierge Query Grammar
+ *
+ * WP-V1.3-9 Tau-4 (criterion (d) of the v1.3 scope-lock revision). Builds
+ * on Tau-3 (PR #171, dynamic context router). The grammar layer parses
+ * operator queries into structured parameters: time ranges, agent names,
+ * event types, and a free-form intent residual. Tau-3 fetchers receive
+ * the parsed hints alongside the query so the substrate sees the most
+ * relevant data slice.
+ *
+ * The module is pure: rule-based extraction, no I/O, no clock side
+ * effects beyond the optional `now` parameter for deterministic tests.
+ * The optional LLM-assist fallback is invoked by the caller when the
+ * rule-based parser produces low confidence.
+ *
+ * Castle-walking discipline:
+ * - No new outbound surface; the LLM-assist fallback routes through the
+ *   substrate selector at the same `concierge` surface Tau-3 already
+ *   uses.
+ * - Encryption boundaries hold: this module receives plain strings
+ *   already produced inside the fortress.
+ * - Failure-mode handling is fail-soft: low-confidence parses surface a
+ *   structured fallback menu so the operator sees what the concierge
+ *   can answer, never a silent drop.
+ *
+ * Privacy invariant:
+ * The runtime `ParsedQuery` carries `intent_phrase` (free-form residual
+ * pulled from the operator's query) for the router's own consumption.
+ * The audit emission MUST NOT include `intent_phrase`; consumers serialize
+ * via `auditSafeSummary()` which strips it. See `OperatorConciergeChatPayload`
+ * safe-metadata invariant in `contracts/v1.2/operator-chat-events.ts`.
+ *
+ * Out of scope here (Tau-5 + later):
+ * - Agent-context awareness (proactive parsing without an explicit
+ *   query). Tau-4 parses off explicit query content only.
+ * - Voice input or natural-language-as-API surface (defer to v1.5+).
+ * - Cross-fortress concierge query (defer to v1.4 cross-tenant scope).
+ * - Window markers like "around the time of <event>" that require an
+ *   audit-log lookup to resolve. Tau-4 ships static patterns only.
+ */
+
+/**
+ * A resolved time range. `relative_label` carries the original token
+ * ("yesterday", "past hour", etc.) when the range was derived from a
+ * relative pattern, so consumers can render operator-readable copy.
+ */
+interface ParsedTimeRange {
+    start: Date;
+    end: Date;
+    relative_label?: string;
+}
+/**
+ * Stable structured-failure flags surfaced when the parser cannot
+ * resolve a token confidently. The strings are enum-like (no free text)
+ * so the audit emission stays safe-metadata-only and the dashboard can
+ * group by cause.
+ */
+type AmbiguityFlag = "unknown_time_token" | "unknown_agent_token" | "unknown_event_token" | "ambiguous_time_range" | "no_signal_extracted";
+/**
+ * Runtime parsed-query shape. Used by the router to thread parameters
+ * into context fetchers, and by the structured-fallback menu builder.
+ *
+ * `intent_phrase` is the residual after time/agent/event tokens are
+ * stripped, useful for router-level intent routing. It carries operator
+ * query content and MUST NOT be serialized into the audit log.
+ */
+interface ParsedQuery {
+    time_range: ParsedTimeRange | null;
+    agent_names: string[];
+    event_types: string[];
+    intent_phrase: string;
+    ambiguity_flags: AmbiguityFlag[];
+    /** 0..1; 1.0 = every component resolved cleanly. */
+    parse_confidence: number;
+}
+/**
+ * Read-only registry view consumed by `parseQuery` for agent-name
+ * extraction. The grammar matches operator query tokens against the
+ * `agent_id` field of each record (case-insensitive, prefix-or-exact).
+ *
+ * Wired from `HubAgentRegistrySource.list()` at the service layer; tests
+ * can hand a literal array. Both shapes are accepted so callers do not
+ * have to wrap a hub registry in an adapter just to feed the parser.
+ */
+type AgentRegistryView = readonly {
+    agent_id: string;
+}[] | {
+    list: () => readonly {
+        agent_id: string;
+    }[];
+};
+/**
+ * Optional LLM-assist completion. Invoked by `parseQueryWithLlmAssist`
+ * when the rule-based parse confidence is below `LLM_ASSIST_THRESHOLD`.
+ * The classifier sees the query plus the partial parse and may return
+ * `null` (no completion) or a partial-shape patch the caller merges.
+ *
+ * The runtime caller (operator-chat-service) MUST route this through
+ * the substrate selector at the `concierge` surface so no new outbound
+ * channel opens. See Castle-walking discipline at the top of the file.
+ */
+type LlmAssistGrammarCompletion = (query: string, partial: ParsedQuery) => Promise<Partial<{
+    time_range: ParsedTimeRange;
+    agent_names: string[];
+    event_types: string[];
+}> | null>;
+
+/**
+ * Sanctuary MCP Server, Operator Chat, Concierge Dynamic Context Router
+ *
+ * WP-V1.3-9 Tau-3 (criterion (c) of the v1.3 scope-lock revision). Builds
+ * on Tau-1 (PR #164, concierge memory store) and Tau-2 (PR #166, multi-turn
+ * coherence read-fold path). At each operator turn the concierge fetches
+ * live data relevant to the operator's query and folds it into context
+ * between the static Sanctuary reference and the prior-turns fold.
+ *
+ * Tau-4 (PR #_, criterion (d)) layers an operator-query grammar on top:
+ * the caller (`operator-chat-service`) parses the query into a
+ * `ParsedQuery` via `concierge-query-grammar`, threads the result into
+ * `classifyQuery` + `foldContext`, and the matches carry the parsed
+ * grammar through to fetchers as `FetcherHints` (time range + agent
+ * names + event types). Existing fetcher implementations that do not
+ * read the second argument continue to work unchanged.
+ *
+ * The module is intentionally pure: keyword classification + a small
+ * amount of hint extraction + a fold orchestrator that calls caller-
+ * provided fetchers. The wiring layer assembles the concrete fetchers
+ * (templates registry, agent registry, audit log, sentinel store, etc.)
+ * so this module stays test-isolatable and composable.
+ *
+ * Castle-walking discipline:
+ * - No new outbound surface; the optional auxiliary classifier is invoked
+ *   through the substrate selector by the caller (the service threads the
+ *   classifier callback through, this module never owns the channel).
+ * - Encryption boundaries hold for the underlying data sources; this
+ *   module receives plain strings already produced inside the fortress.
+ * - Failure-mode handling is fail-soft: a fetcher failure omits its
+ *   category from the fold and surfaces an audit event through the
+ *   caller's onFetcherFailure hook. The user-facing concierge query is
+ *   never broken by a context-assembly failure.
+ *
+ * Out of scope here (Tau-5):
+ * - Agent-context awareness (proactive folding without an explicit
+ *   query). The router still routes off explicit query content only.
+ */
+
 /**
  * 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";
+/**
+ * Structured hints passed to fetchers as the optional second argument
+ * (Tau-4). Derived from `ParsedQuery` by the router; fetchers are free
+ * to read or ignore individual fields. Tau-3 fetchers that take no
+ * second argument continue to work because the slot is optional.
+ */
+interface FetcherHints {
+    /** Time range derived from the operator's query, when one resolved. */
+    time_range?: {
+        start: Date;
+        end: Date;
+        relative_label?: string;
+    };
+    /**
+     * All agent names the parser matched against the registry, in the
+     * order they surfaced. Distinct from the `agentNameHint` first arg
+     * (which carries only the first match for back-compat).
+     */
+    agent_names?: readonly string[];
+    /**
+     * Event-type names the parser matched against the canonical audit-
+     * event-class enumeration. Already filtered to the closed set.
+     */
+    event_types?: readonly string[];
+}
 /**
  * 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.
+ *
+ * Tau-4 extends every fetcher with an optional `hints?: FetcherHints`
+ * argument carrying the parsed-query attachments (time range, agent
+ * names, event types). Fetchers that ignore the argument continue to
+ * compile; fetchers that consume it can scope queries against the
+ * audit log, activity feed, etc., to the operator's stated window.
  */
 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>;
+    templates: (hints?: FetcherHints) => Promise<string>;
+    agent_state: (agentNameHint: string | null, hints?: FetcherHints) => Promise<string>;
+    agent_activity: (agentNameHint: string | null, hints?: FetcherHints) => Promise<string>;
+    audit_log: (hints?: FetcherHints) => Promise<string>;
+    sentinel_findings: (hints?: FetcherHints) => Promise<string>;
+    anomaly_alerts: (hints?: FetcherHints) => Promise<string>;
+    recent_receipts: (hints?: FetcherHints) => Promise<string>;
+    verascore_deltas: (hints?: FetcherHints) => Promise<string>;
 }
 /**
  * Auxiliary classifier the caller may supply for the LLM-assist fallback
@@ -5514,6 +5691,26 @@ interface OperatorChatServiceDeps {
      * Defaults to `DEFAULT_CONCIERGE_DYNAMIC_CONTEXT_BUDGET` (2000).
      */
     conciergeDynamicContextBudget?: number;
+    /**
+     * WP-V1.3-9 Tau-4: read-only registry view consumed by the operator-
+     * query grammar to extract agent-name parameters. Wired from
+     * `HubAgentRegistrySource.list()` at the hub-service layer; absent
+     * services skip agent-name extraction (the grammar still resolves
+     * time ranges and event types). The registry is read at every
+     * `sendConcierge` call so newly-wrapped agents are visible without
+     * service reconstruction.
+     */
+    conciergeAgentRegistry?: AgentRegistryView;
+    /**
+     * WP-V1.3-9 Tau-4: optional LLM-assist completion for low-confidence
+     * grammar parses. When wired alongside the substrate selector, the
+     * service routes the call through the substrate selector at the
+     * `concierge` surface, so the grammar fallback shares the operator's
+     * substrate choice and never opens a new outbound surface. Distinct
+     * from `conciergeContextLlmAssist`, which classifies queries into
+     * fetcher categories; this hook completes structured grammar fields.
+     */
+    conciergeGrammarLlmAssist?: LlmAssistGrammarCompletion;
 }
 declare class OperatorChatService {
     private store;
@@ -5532,6 +5729,8 @@ declare class OperatorChatService {
     private contextFetchers?;
     private contextLlmAssist?;
     private dynamicContextBudget;
+    private agentRegistry?;
+    private grammarLlmAssist?;
     /**
      * In-memory thread_id assigned to the active concierge session.
      * The first sendConcierge call after construction allocates a fresh
@@ -5646,8 +5845,20 @@ declare class OperatorChatService {
      * 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).
+     *
+     * Tau-4: receives the pre-parsed `ParsedQuery` and forwards it as the
+     * `parsed` opt to `foldContext`, so fetchers see the structured
+     * `FetcherHints` derived from it.
      */
     private runDynamicContextFold;
+    /**
+     * WP-V1.3-9 Tau-4: parse the (PII-filtered) operator query into a
+     * `ParsedQuery`. Routes through the LLM-assist completion hook when
+     * configured and the rule-based parse is below
+     * `LLM_ASSIST_THRESHOLD`. Always returns a parse object (never
+     * throws) so the audit emission can carry the result unconditionally.
+     */
+    private runGrammarParse;
     /**
      * 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.
@@ -6329,6 +6540,22 @@ interface AggregatedApproval {
      * Upsilon-3.
      */
     enforcement_chain?: EnforcementLayerEvent[];
+    /**
+     * Aggregator revision number stamped at entry creation. Stable across
+     * status transitions. Used by the v1.4 mobile companion sync API to
+     * separate "added" from "changed" deltas (created_at_revision >
+     * sinceRevision means added; otherwise it is a status change).
+     * v1.3 Upsilon-4.
+     */
+    created_at_revision?: number;
+    /**
+     * Aggregator revision number stamped at the last mutation (creation,
+     * resolution, expiration). Sync-API consumers compare against the
+     * revision they last saw to compute the delta. Monotonically
+     * increasing per fortress; gaps are normal (one bump per mutation).
+     * v1.3 Upsilon-4.
+     */
+    last_modified_revision?: number;
 }
 /**
  * Source-context resolver. Called once per ingest to map gate context to
@@ -6385,11 +6612,35 @@ type ApprovalAggregatorUnsubscribe = () => void;
 interface ApprovalAggregatorEmit {
     /**
      * `aggregated` on first ingest, `resolved` on a status leaving pending,
-     * `deduped` when an ingest dropped because the same dedup key was seen.
+     * `deduped` when an ingest dropped because the same dedup key was seen,
+     * `removed` when an entry was pruned (v1.3 Upsilon-4).
      */
-    type: "aggregated" | "resolved" | "deduped";
+    type: "aggregated" | "resolved" | "deduped" | "removed";
     entry: AggregatedApproval;
 }
+/**
+ * Sync-API delta returned by `getSync()`. v1.3 Upsilon-4. Mobile
+ * companions poll this for cheap state-sync without re-fetching the
+ * full inbox. The `revision` field on the response is the aggregator's
+ * current revision; pass it back as `sinceRevision` on the next call.
+ *
+ * `added` carries entries created after `sinceRevision`. `changed`
+ * carries entries that existed at `sinceRevision` but have transitioned
+ * status (resolved, expired) since. `removed` carries the
+ * aggregator_ids of entries pruned after `sinceRevision`.
+ *
+ * Tombstone caveat: removal tombstones live in-process memory. Server
+ * restart clears them. Mobile clients reconnecting after the server
+ * restarted MUST re-bootstrap from `list()` rather than rely on the
+ * sync delta. The v1.4 mobile companion build wires the bootstrap-on-
+ * reconnect flow; v1.3 documents the constraint.
+ */
+interface ApprovalAggregatorSyncDelta {
+    revision: number;
+    added: AggregatedApproval[];
+    changed: AggregatedApproval[];
+    removed: string[];
+}
 /**
  * Constructor dependencies. `pendingTtlMs` and `maxListLimit` default to
  * coordinator-CTO defaults; tests pass overrides for deterministic timing.
@@ -6464,12 +6715,63 @@ declare class ApprovalAggregator {
     private hydrated;
     /** Active SSE listeners. */
     private readonly listeners;
+    /**
+     * Monotonic revision counter, bumped on every mutation (ingest of new
+     * entry, resolve, expire, delete). Hydrated from max(last_modified_revision)
+     * across persisted entries on first read; in-memory after that. v1.3
+     * Upsilon-4.
+     */
+    private currentRevision;
+    /**
+     * Removal tombstones: aggregator_id -> revision at removal. Used by the
+     * sync API to surface "removed" entries to mobile consumers between
+     * polls. In-memory only; server restart clears tombstones (mobile
+     * bootstraps via `list()` on reconnect). v1.3 Upsilon-4.
+     */
+    private readonly removedTombstones;
     constructor(deps: ApprovalAggregatorDeps);
     /**
      * Subscribe an event listener. Returns an unsubscribe fn. SSE handlers
      * use this to forward aggregator emissions to the dashboard.
      */
     onEvent(listener: (event: ApprovalAggregatorEmit) => void): ApprovalAggregatorUnsubscribe;
+    /**
+     * Current aggregator revision. v1.3 Upsilon-4. Mobile companions
+     * poll the lightweight `/revision` route to detect that something
+     * changed before fetching a full sync delta.
+     */
+    getRevision(): Promise<number>;
+    /**
+     * Compute a delta since `sinceRevision`. v1.3 Upsilon-4. Mobile
+     * clients poll this for cheap state-sync. Behavior:
+     *  - `added`: entries whose `created_at_revision > sinceRevision`.
+     *  - `changed`: entries that existed at `sinceRevision` but had a
+     *    status transition (resolve, expire) since.
+     *  - `removed`: aggregator_ids deleted after `sinceRevision`.
+     *  - `revision`: current aggregator revision; pass this back as
+     *    `sinceRevision` on the next call.
+     *
+     * `limit` caps the total count returned across all three lists,
+     * prioritized as added -> changed -> removed (newer-state first).
+     * When more changes exist than fit, the next call with the returned
+     * revision will pick up the rest because each entry's
+     * last_modified_revision is unchanged by truncation.
+     */
+    getSync(opts?: {
+        sinceRevision?: number;
+        limit?: number;
+    }): Promise<ApprovalAggregatorSyncDelta>;
+    /**
+     * Delete an entry. Drops the in-memory record, the persisted bundle,
+     * and the at-rest payload (if a payload store is wired). Records a
+     * tombstone with the new revision so sync-API consumers see a
+     * `removed` delta. Returns true when an entry was deleted, false on
+     * unknown id. v1.3 Upsilon-4. Reserved for v1.4+ retention housekeeping;
+     * Upsilon-4 ships the surface so mobile sync-API tests can exercise the
+     * removal path.
+     */
+    deleteEntry(aggregatorId: string): Promise<boolean>;
+    private nextRevision;
     /**
      * Ingest a gate event. Returns the aggregator entry on first sight,
      * `null` when deduped. Resolution events update the existing record;