@aiwayds/dsh-mcp-adapter 0.5.0 → 0.6.0

package/lib/index.d.ts

@@ -57,6 +57,9 @@ import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm';
 import type { ToolDefinition, ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools';
+import type { JevConfigValue } from './jev/config.ts';
+import type { RankCandidate } from './rank.ts';
+import type { SuggestionRecord } from './usage.ts';
 import type { ScopeKey } from '@deepseek-ai/dsh-scope';
 /** Cordis plugin name used by loader diagnostics. */
 export declare const name = "mcp-adapter";
@@ -195,8 +198,72 @@ export declare function resolveGateDir(configured: string): string;
  * synchronous (boot-time, once); writes land atomically (tmp file + rename)
  * so a crash mid-write can never leave a torn document, and the in-memory
  * mirror only advances after the file is durably renamed into place.
+ *
+ * Legacy absorption (one-time, 0.1.5 → 0.1.7): on a FRESH gate — no
+ * gate.json yet — the machine state from the removed settings registry is
+ * absorbed once from the host's legacy settings documents (see
+ * {@link absorbLegacyGate}). Opt-in through `options.home`: the legacy
+ * documents are a HOME-level concern (not this store's `dir`), and stores
+ * built without a home (bare test harnesses) stay exactly as isolated as
+ * before.
+ */
+export declare function createFileGateStore(dir: string, warn: GateWarn, options?: GateStoreOptions): GateStore;
+/**
+ * dsh 0.1.7 renamed the old `<home>/settings.yaml` to
+ * `settings.yaml.imported` after a one-shot import keyed by "section name =
+ * entry id". This plugin's old `mcp-adapter:` section (the machine-maintained
+ * id registry / disabled set) does not match the entry id `dsh-mcp-adapter`
+ * and was silently dropped by the host — the state lives on only in the
+ * renamed document. {@link absorbLegacyGate} recovers it once into the
+ * plugin's own gate.json.
+ */
+/** Legacy host settings documents, in read priority order. */
+export declare const LEGACY_SETTINGS_FILES: readonly ["settings.yaml.imported", "settings.yaml"];
+/** Legacy top-level section name in the old settings document. */
+export declare const LEGACY_GATE_SECTION = "mcp-adapter";
+/** Audit marker file name: `<home>/storages/mcp-adapter/<name>`. */
+export declare const LEGACY_IMPORT_MARKER = "legacy-import.json";
+/** Marker outcomes written for every settled absorption pass. */
+export type LegacyGateOutcome = 'imported' | 'no-op' | 'no-legacy' | 'no-section';
+/**
+ * Extract the top-level `mcp-adapter:` section of the old settings document.
+ * Handles both shapes the 0.1.5 writer produced:
+ * - single-line values (`serverIds: '{"fs": 1}'`, `disabled: '[1]'`);
+ * - block collections (`serverIds:` followed by deeper-indented
+ *   `name: <int>` lines; `disabled:` followed by `- <int>` lines).
+ * Everything else (comments, folded scalars, nested junk) is skipped.
+ * undefined = no section found. Pure function — tests run it against
+ * literal strings.
  */
-export declare function createFileGateStore(dir: string, warn: GateWarn): GateStore;
+export declare function legacyGateSection(text: string): {
+    serverIds?: unknown;
+    disabled?: unknown;
+} | undefined;
+/**
+ * Turn one decoded section into the raw candidate {@link normalizeServerGate}
+ * sanitizes: flow-JSON strings are JSON-parsed (malformed → undefined, the
+ * key degrades to "absent"), already-decoded block collections pass through.
+ */
+export declare function legacyGateCandidate(section: {
+    serverIds?: unknown;
+    disabled?: unknown;
+}): {
+    serverIds?: unknown;
+    disabled?: unknown;
+};
+/** Construction options for {@link createFileGateStore} beyond the two
+ *  historical arguments (all optional — bare harnesses change nothing). */
+export interface GateStoreOptions {
+    /** Summary-line seam for the absorption (default: silent). */
+    info?: GateWarn;
+    /**
+     * The dsh home holding the legacy settings documents and the audit marker
+     * (production: `resolveDshHome()` at the call site). Absorption runs ONLY
+     * when a home is provided — a store built without one never reads outside
+     * its own directory.
+     */
+    home?: string;
+}
 /**
  * Live config reference. 0.1.7 settings contract: volatile `Config` fields
  * reach `apply` as host-swapped references — `.get()` snapshots the current
@@ -210,8 +277,15 @@ export interface VolatileRef<T> {
  * Resolved adapter configuration as `apply` receives it. Every knob is
  * user-tunable from the settings page (entry `dsh-mcp-adapter`) and hot-reloads
  * without a plugin restart.
+ *
+ * The seven `jev*` keys are the System One decision settings (see
+ * ./jev/config.ts): the master switch, the backend/model to ask, the request
+ * timeout, the outbound secret list, and the local laya pace-maker. They are
+ * spread into {@link Config} from `JEV_CONFIG_FIELDS` so the settings schema
+ * and this interface cannot drift, and they are read through their volatile
+ * refs per use like every other knob.
  */
-export interface AdapterConfig {
+export interface AdapterConfig extends JevConfigValue {
     /** Tool-name prefix to fold out of assembled prompts. */
     prefix: VolatileRef<string>;
     /** Name patterns ("*" wildcard) kept native in the prompt. */
@@ -228,7 +302,7 @@ export interface AdapterConfig {
     /**
      * Gate storage directory override; empty (default) =
      * `<dsh home>/storages/mcp-adapter`. Read once at apply time (the store is
-     * built there); changing it takes effect on the next plugin restart.
+     * built there; changing it takes effect on the next plugin restart).
      */
     storageDir: VolatileRef<string>;
 }
@@ -322,6 +396,19 @@ export interface McpListOptions {
      * once at apply time and must observe later /mcp disable/enable writes.
      */
     getGate?: () => ServerGateState | undefined;
+    /**
+     * Optional async relevance reranker for `{ query }` calls ONLY (production:
+     * the System One seam). Called with the candidate pool — the lexical
+     * shortlist, or the whole visible catalog when the prefilter matched
+     * nothing — and resolves to the preferred order, or to `undefined` to keep
+     * the order it was given.
+     *
+     * Deliberately a promise-returning callback on a SYNCHRONOUS builder: the
+     * remote call happens in the async execute layer, and this builder stays a
+     * pure function of (args, schemas, options, ranking). Disabled, failed, or
+     * absent rerank ⇒ `undefined` ⇒ the given order, i.e. pre-seam behavior.
+     */
+    rankQuery?: (query: string, candidates: readonly RankCandidate[]) => Promise<readonly string[] | undefined>;
 }
 /** Normalized `mcp_list` arguments. */
 export interface McpListArgs {
@@ -331,6 +418,13 @@ export interface McpListArgs {
     server?: string;
     /** Inline every tool's schema in the catalog. */
     verbose?: boolean;
+    /**
+     * Free-text relevance query. Absent (or blank) = the unfiltered catalog,
+     * byte-identical to the pre-query behavior; present = a ranked SHORTLIST
+     * plus the total match count, never a silent narrowing of the only
+     * discovery path the model has.
+     */
+    query?: string;
 }
 /** One catalog entry; `parameters` is present only when expanded. */
 export interface CatalogToolEntry {
@@ -343,9 +437,24 @@ export interface CatalogServerEntry {
     server: string;
     tools: CatalogToolEntry[];
 }
-/** `mcp_list`'s canonical result: catalog, single expansion, or error. */
+/**
+ * `mcp_list`'s canonical result: catalog, single expansion, or error.
+ *
+ * The `{ servers }` variant carries four OPTIONAL keys that are present only
+ * on a query answer: `query`, `ranked`, `total` and `note`. They are what
+ * makes the subset self-describing — the model can see that this is a ranked
+ * shortlist of N of M matches and that the full catalog is one no-argument
+ * call away, and `ranked: false` says the prefilter matched nothing at all
+ * and this is the semantic fallback rather than a ranking. An unqueried
+ * catalog omits them entirely, so the wire value stays byte-identical to the
+ * pre-seam shape.
+ */
 export type McpListResult = {
     servers: CatalogServerEntry[];
+    query?: string;
+    ranked?: boolean;
+    total?: number;
+    note?: string;
 } | {
     tool: {
         name: string;
@@ -355,9 +464,43 @@ export type McpListResult = {
 } | {
     error: string;
 };
+/**
+ * A precomputed ranking for one `{ query }` catalog call — the seam between
+ * the async jev layer and the pure builder. `pool`/`total` are the LEXICAL
+ * result (so the builder does not have to redo the work and cannot disagree
+ * with the shortlist jev was asked about); `order` is jev's permutation of
+ * that pool, absent when there is no opinion (fail-open ⇒ `pool` order).
+ */
+export interface ListRanking {
+    /** The query this ranking was computed for. */
+    query: string;
+    /**
+     * The candidate set, at most {@link RANK_CANDIDATE_LIMIT} names: the lexical
+     * shortlist, best first — or, under {@link ListRanking.semantic}, the whole
+     * visible catalog in registry order.
+     */
+    pool: readonly string[];
+    /** Every lexical match, uncapped — the denominator of the `total` field. */
+    total: number;
+    /** Reranked names, best first (production: the jev answer). */
+    order?: readonly string[];
+    /**
+     * True when the lexical prefilter matched NOTHING and `pool` is instead the
+     * SEMANTIC-FALLBACK set: the whole visible catalog, capped, handed to a
+     * reranker that can still tell a Chinese query from an English description
+     * and an ASCII one cannot. Absent (the ordinary case) = a lexical ranking,
+     * and the answer says `ranked: true` with no mention of a fallback.
+     */
+    semantic?: boolean;
+}
 /**
  * Narrow arbitrary model arguments to the `mcp_list` shape, dropping
  * unknown or mistyped keys instead of throwing (the model misbehaves).
+ *
+ * A blank `query` is dropped rather than kept: an empty search is not a
+ * search, and honoring it would put the catalog on a different code path (the
+ * ranked one) for a request that means "show me everything".
+ *
  * @param args - raw model arguments.
  * @returns the normalized catalog query.
  */
@@ -385,21 +528,55 @@ export declare function serverOfToolName(name: string, prefix: string): string;
  * @returns the single-line truncated description.
  */
 export declare function truncateDescription(text: string, limit: number): string;
+/**
+ * The lexical relevance shortlist for one `query` catalog call — the pure,
+ * synchronous half of seam B. This is both what the jev reranker is asked
+ * about and the order that stands when jev is disabled or fails.
+ *
+ * @param args - the normalized catalog query (must carry a `query`).
+ * @param schemas - schemas visible to the calling agent.
+ * @param options - catalog knobs.
+ * @param gate - live disabled-server snapshot (default: none disabled).
+ * @returns the shortlist (name + full description per entry, so a reranker
+ *   can ask about them without re-reading the schemas) plus the uncapped
+ *   match count. A query the prefilter cannot lexically match comes back
+ *   `semantic` with the whole visible catalog as its pool. A structured error
+ *   means the catalog itself is empty or fully gated.
+ */
+export declare function listQueryRanking(args: McpListArgs, schemas: readonly ToolSchema[], options: McpListOptions, gate?: ServerGateState): {
+    pool: readonly RankCandidate[];
+    total: number;
+    semantic?: boolean;
+    error?: string;
+};
 /**
  * Build the `mcp_list` result over the currently visible schemas.
  *
  * Priority: `tool` (full single-tool expansion) > catalog (optionally
- * filtered by `server`, optionally `verbose`). Unknown or non-MCP `tool`,
- * and any query that selects nothing, return a structured error — never a
- * throw — so the model can correct itself.
+ * filtered by `server`, optionally `verbose`, optionally ranked by `query`).
+ * Unknown or non-MCP `tool`, and any query that selects nothing out of an
+ * empty or fully gated catalog, return a structured error — never a throw —
+ * so the model can correct itself.
+ *
+ * A `query` that the LEXICAL prefilter cannot match is NOT an error: it
+ * degrades to the semantic fallback (the whole visible catalog, capped, and
+ * `ranked: false`), because "no word of the query appeared anywhere" is not
+ * "no tool matches" — see {@link semanticFallbackPool}.
+ *
+ * `query` is a MODEL-EXPLICIT narrowing: it is the only catalog path that
+ * consults `ranking` (production: the System One seam), and a missing/failed
+ * rerank degrades to the lexical order. With no `query`, this function is the
+ * pre-seim builder unchanged.
  *
  * @param args - the normalized catalog query.
  * @param schemas - schemas visible to the calling agent.
  * @param options - catalog knobs.
  * @param gate - live disabled-server snapshot (default: none disabled).
+ * @param ranking - precomputed relevance ranking for `args.query`
+ *   (production: the async layer's jev answer).
  * @returns the canonical result value.
  */
-export declare function buildMcpListResult(args: McpListArgs, schemas: readonly ToolSchema[], options: McpListOptions, gate?: ServerGateState): McpListResult;
+export declare function buildMcpListResult(args: McpListArgs, schemas: readonly ToolSchema[], options: McpListOptions, gate?: ServerGateState, ranking?: ListRanking): McpListResult;
 /** Structural slice of a resolvable tool: what dispatch actually consumes. */
 export interface DispatchableTool<E> {
     /** Cooperative timeout budget declared by the tool, if any. */
@@ -407,6 +584,36 @@ export interface DispatchableTool<E> {
     /** The tool body dispatch invokes. */
     execute(args: unknown, exec: E): Promise<unknown>;
 }
+/**
+ * The near-miss seam of the unknown-tool branch (seam C).
+ *
+ * `candidates` is deliberately cheap and SYNCHRONOUS — it is called on a path
+ * the model is already reading an error on, and it must answer even when jev
+ * is off, timing out, or broken. `rerank` is the optional async refinement
+ * (production: the System One seam); `undefined`, a rejection, or an
+ * unusable answer all mean "keep the lexical order", which is the behavior
+ * the branch had before the seam existed.
+ */
+export interface DidYouMeanHook {
+    /** Visible tool names a near-miss may point at, in the calling scope. */
+    candidates(): readonly RankCandidate[];
+    /** Optional async reorder; absent/undefined/throw ⇒ lexical order stands. */
+    rerank?(tool: string, candidates: readonly RankCandidate[]): Promise<readonly string[] | undefined>;
+}
+/** The near-miss pool cap — the same batch ceiling the jev seams use. */
+export declare const DID_YOU_MEAN_POOL_LIMIT = 40;
+/**
+ * The visible tools a near-miss may point at: this scope's prefix-matching
+ * MCP tools under the servers whitelist, minus the meta-tools and minus
+ * disabled servers (dispatch would refuse those anyway, so naming one would
+ * be advice the model cannot take).
+ *
+ * @param schemas - schemas visible to the calling agent.
+ * @param options - adapter knobs (prefix/servers).
+ * @param gate - live disabled-server snapshot (default: none disabled).
+ * @returns the pool, in registry order.
+ */
+export declare function didYouMeanPool(schemas: readonly ToolSchema[], options: Pick<McpCommandOptions, 'prefix' | 'servers'>, gate?: ServerGateState): RankCandidate[];
 /**
  * Dispatch one `mcp_call` to the resolved child tool.
  *
@@ -433,6 +640,11 @@ export interface DispatchableTool<E> {
  * Errors never throw out of dispatch: a child rejection (or raced timeout)
  * is wrapped into a structured `{ error }` the model can correct and retry.
  *
+ * The unknown-tool branch additionally offers near-misses (seam C): a lexical
+ * prefilter over the scope's visible tools always answers, and an optional
+ * async rerank (production: System One) can reorder it. The base error text
+ * is unchanged, so this stays a pure addition to the message.
+ *
  * @param args - raw model arguments (`{ tool, arguments? }`, validated here).
  * @param prefix - the configured MCP prefix.
  * @param resolve - scope-aware tool resolver (production: `ctx.tools.get`).
@@ -442,9 +654,11 @@ export interface DispatchableTool<E> {
  *   disabled branch sits after the prefix/whitelist validation: a disabled
  *   server's tools are refused with an explicit `/mcp enable <id>` hint
  *   before the child is ever resolved.
+ * @param didYouMean - the near-miss seam for the unknown-tool branch
+ *   (default: none — the pre-seam message, unchanged).
  * @returns the child's resolved value verbatim, or a structured error.
  */
-export declare function dispatchMcpCall<E>(args: unknown, prefix: string, resolve: (name: string) => DispatchableTool<E> | undefined, exec: E, servers?: readonly string[], gate?: ServerGateState): Promise<unknown>;
+export declare function dispatchMcpCall<E>(args: unknown, prefix: string, resolve: (name: string) => DispatchableTool<E> | undefined, exec: E, servers?: readonly string[], gate?: ServerGateState, didYouMean?: DidYouMeanHook): Promise<unknown>;
 /** Knobs shared by every /mcp renderer — plain data, no Cordis. */
 export interface McpCommandOptions {
     /** Tool-name prefix identifying MCP tools. */
@@ -470,6 +684,36 @@ export interface McpCommandOptions {
      * one in the first place.
      */
     unassignedServers?: readonly string[];
+    /**
+     * The seven System One settings as plain data (production: the live
+     * volatile config refs, resolved per invocation). Absent ⇒ the views stay
+     * byte-identical to the pre-jev plugin — a caller that does not wire the
+     * decision support never sees a jev line.
+     */
+    jev?: McpJevOptions;
+    /**
+     * Recorded usage counters for the views that talk about the suggestion
+     * cadence (production: the usage mirror). Absent ⇒ those views report "no
+     * usage recorded yet" instead of a number.
+     */
+    usage?: McpUsageOptions;
+}
+/** The seven jev settings, flattened for display. */
+export interface McpJevOptions {
+    readonly jevEnabled: boolean;
+    readonly jevBackend: string;
+    readonly jevModel: string;
+    readonly jevTimeoutMs: number;
+    readonly jevSecretFile: string;
+    readonly jevLayaFallback: boolean;
+    readonly jevLayaUrl: string;
+}
+/** Recorded-usage counters, flattened for display. */
+export interface McpUsageOptions {
+    /** Dispatches recorded across every tool. */
+    readonly totalCalls: number;
+    /** Tools carrying at least one recorded call. */
+    readonly toolCount: number;
 }
 /** Usage text returned for unparseable /mcp invocations. */
 export declare const MCP_COMMAND_USAGE: string;
@@ -481,6 +725,8 @@ export type ParsedMcpCommandInput = {
     name: string;
 } | {
     form: 'config';
+} | {
+    form: 'suggest';
 } | {
     form: 'disable';
     id: number;
@@ -493,9 +739,10 @@ export type ParsedMcpCommandInput = {
 /**
  * Parse one /mcp raw input into its form. `''` and `'list'` are the tree
  * overview; `'list <name>'` is a server/tool detail; `'config'` shows the
- * effective configuration; `'disable <n>'` / `'enable <n>'` are whole-server
- * toggles (n is the stable id shown by `/mcp`, so a bare `0` or non-numeric
- * token is already usage). Everything else parses to the usage error.
+ * effective configuration; `'suggest'` shows the current keep suggestions;
+ * `'disable <n>'` / `'enable <n>'` are whole-server toggles (n is the stable id
+ * shown by `/mcp`, so a bare `0` or non-numeric token is already usage).
+ * Everything else parses to the usage error.
  * @param rawInput - exact text following the command name.
  * @returns the normalized command form.
  */
@@ -643,6 +890,24 @@ export interface McpDetailView {
  * @returns the rendered view.
  */
 export declare function renderMcpDetail(name: string, schemas: readonly ToolSchema[], options: McpCommandOptions): McpDetailView;
+/**
+ * Render the keep-suggestion view (`/mcp suggest`): the current batch of
+ * System One verdicts about which FOLDED tools earned a permanent place in
+ * every prompt, each with its probability, the usage evidence behind it, and
+ * the exact `keep` pattern the operator would write.
+ *
+ * Strictly a DISPLAY (red line ③): nothing here writes keep, prefix or the
+ * gate — the operator decides, one settings-page edit, with the same manual
+ * authority they have over every other knob.
+ *
+ * Every state is explained rather than blank: jev off, jev on with no batch
+ * yet, and jev on with rows. Output is line-capped defensively.
+ *
+ * @param suggestions - the current batch (production: suggestions.json).
+ * @param options - adapter knobs; `jev.jevEnabled` and `usage` are read.
+ * @returns the rendered view.
+ */
+export declare function renderMcpSuggest(suggestions: readonly SuggestionRecord[], options: Pick<McpCommandOptions, 'jev' | 'usage'>): string;
 /**
  * Render the effective configuration with each knob's hitting tools:
  * which names match the prefix, what each keep pattern holds back, and what
@@ -686,6 +951,13 @@ export interface McpCommandView {
      * finishes in the background — same-process code cannot hard-kill it.
      */
     signal?: AbortSignal;
+    /**
+     * The current keep-suggestion batch for `/mcp suggest` (production: read
+     * from `<gate dir>/suggestions.json` at invocation time). Absent ⇒ the view
+     * reports "no suggestions yet", which is also what a missing or unreadable
+     * document means.
+     */
+    suggestions?: readonly SuggestionRecord[];
 }
 /** CommandResult-compatible outcome (platform shape: success may omit text). */
 export interface McpCommandOutcome {
@@ -759,18 +1031,54 @@ export declare function renderDispatched(metaArgs: unknown, value: unknown, reso
 export declare function delegateFinalizeContent(metaArgs: unknown, result: Readonly<ToolExecutionResult>, exec: Readonly<ToolExecution>, resolveChild: (name: string) => ToolDefinition | undefined): ContentBlock[] | undefined;
 /**
  * Build the `mcp_list` meta-tool definition.
- * @param options - catalog knobs (prefix, description limit). MAY be a live
- *   options object (plain getters): the factory reads `prefix`, `servers`,
- *   `descriptionLimit` and `getGate` through the object on EVERY execution,
- *   so volatile config can be wired by reference — only the description text
- *   freezes at factory time.
+ *
+ * The execute layer is where the async seam lives: a no-argument call is the
+ * pre-seim builder verbatim (no promise, no remote), and only a `query` call
+ * consults `options.rankQuery` — and even then only AFTER a candidate pool
+ * exists, so a disabled/failed rerank changes the ORDER and nothing else.
+ *
+ * @param options - catalog knobs (prefix, description limit, optional
+ *   rankQuery). MAY be a live options object (plain getters): the factory
+ *   reads `prefix`, `servers`, `descriptionLimit`, `getGate` and
+ *   `rankQuery` through the object on EVERY execution, so volatile config can
+ *   be wired by reference — only the description text freezes at factory
+ *   time.
  * @param listSchemas - visible-schemas source (production: `ctx.tools.schemas`,
  *   called with the calling agent so restrictions are respected).
  * @returns the complete tool definition.
  */
 export declare function createMcpListTool(options: McpListOptions, listSchemas: (scope?: ScopeKey) => readonly ToolSchema[]): ToolDefinition;
+/**
+ * Optional seams {@link createMcpCallTool} wires into mcp_call. All three are
+ * contained: a throwing hook degrades to the pre-seam behavior and never
+ * breaks a dispatch.
+ */
+export interface McpCallHooks {
+    /**
+     * Near-miss pool for the unknown-tool branch, resolved in the CALLING
+     * agent's scope (production: the scope's visible prefix tools). Absent ⇒
+     * the pre-seam error text, unchanged.
+     */
+    didYouMean?: (scope: ScopeKey | undefined) => readonly RankCandidate[];
+    /**
+     * Async rerank of that pool (production: System One). Resolving to
+     * `undefined` or rejecting keeps the lexical order.
+     */
+    didYouMeanRank?: (scope: ScopeKey | undefined, tool: string, candidates: readonly RankCandidate[]) => Promise<readonly string[] | undefined>;
+    /**
+     * Told about every finished dispatch, success and failure alike (production:
+     * the usage store). Receives `tool: undefined` for a call that never named
+     * one. Synchronous and best-effort: this is on the hot path, so it must not
+     * return a promise and must never be awaited.
+     */
+    onDispatched?: (event: {
+        tool: string | undefined;
+        error: boolean;
+    }) => void;
+}
 /**
  * Build the `mcp_call` meta-tool definition.
+ *
  * @param prefix - the configured MCP prefix (dispatch boundary). A thunk is
  *   accepted so volatile config is re-read on every dispatch; a plain string
  *   freezes the boundary at factory time.
@@ -782,9 +1090,10 @@ export declare function createMcpListTool(options: McpListOptions, listSchemas:
  *   gate store's current mirror; default/omitted: nothing is disabled).
  *   Deliberately a callback — the definition object outlives any one gate
  *   snapshot and must observe later /mcp enable/disable writes.
+ * @param hooks - the usage/did-you-mean seams (default: none wired).
  * @returns the complete tool definition.
  */
-export declare function createMcpCallTool(prefix: string | (() => string), resolve: (name: string, scope?: ScopeKey) => ToolDefinition | undefined, servers?: readonly string[] | (() => readonly string[]), getGate?: () => ServerGateState | undefined): ToolDefinition;
+export declare function createMcpCallTool(prefix: string | (() => string), resolve: (name: string, scope?: ScopeKey) => ToolDefinition | undefined, servers?: readonly string[] | (() => readonly string[]), getGate?: () => ServerGateState | undefined, hooks?: McpCallHooks): ToolDefinition;
 /**
  * Register the two meta-tools and install the assembly folding listener.
  *
@@ -799,11 +1108,19 @@ export declare function createMcpCallTool(prefix: string | (() => string), resol
  * unreadable document degrades to the empty gate (everything enabled) at
  * load time, keeping the assemble waterfall alive.
  *
- * Config volatility: every knob (prefix/keep/servers/descriptionLimit) is a
- * volatile reference — 0.1.7 settings-page writes swap values in place
- * WITHOUT remounting the plugin, so nothing captured at apply time may go
- * stale: the waterfall, both meta-tools and the /mcp command all re-read
- * through {@link cfgNow} per use.
+ * Config volatility: every knob (prefix/keep/servers/descriptionLimit AND the
+ * seven jev* keys) is a volatile reference — 0.1.7 settings-page writes swap
+ * values in place WITHOUT remounting the plugin, so nothing captured at apply
+ * time may go stale: the waterfall, both meta-tools and the /mcp command all
+ * re-read through {@link cfgNow} / {@link jevEnv} per use.
+ *
+ * System One wiring (the only remote calls in this plugin): the decision log,
+ * the usage mirror and the suggestion document all live in the SAME gate
+ * directory as gate.json. The seams are wired to exactly three places — the
+ * background keep-suggestion batch ({@link maybeSuggestBatch}, fired by the
+ * usage counter and awaited by nobody), `mcp_list`'s model-explicit `query`,
+ * and `mcp_call`'s unknown-tool branch. Folding, an unqueried catalog, and a
+ * successful dispatch touch none of them.
  *
  * Commands: `/mcp` mounts through a runtime `ctx.inject(['commands'], ...)`,
  * so hosts without the commands service keep this plugin fully functional —