@fonlan/dsh-gitmemo 0.4.0 → 0.4.1

package/lib/index.js

@@ -23,6 +23,7 @@
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { GitMemo, GitMemoError, resolveProjectRoot } from "./mem.js";
+import { evaluateGate } from "./systemone.js";
 /** Cordis plugin name. */
 const name = "dsh-gitmemo";
 /** Host services this plugin needs. */
@@ -40,8 +41,160 @@ const Config = z.object({
     /** Cross-process lock wait timeout in milliseconds. Default 30000. */
     lockTimeoutMs: z.number().default(30000),
     /** Optional explicit project root; defaults to the calling session's cwd. */
-    projectRoot: z.string()
+    projectRoot: z.string(),
+    /**
+     * Optional System-one recall gate. When an endpoint and a credential are
+     * configured, each `mem_search` page is narrowed by a System-one model
+     * (TypeSafe Jev by default) before it reaches the model; when nothing is
+     * configured the gate is a no-op and recall behaves exactly as before.
+     *
+     * `.volatile()` is REQUIRED here, not cosmetic: the settings plane only
+     * exposes a field that sits on or under a volatile node (`volatileForm()`
+     * returns undefined otherwise, and `describe()` then skips this entry
+     * entirely while `write()` throws). Verified against
+     * `@deepseek-ai/dsh-settings`. Note that DSH 0.1.7-alpha.1 ships no client
+     * that auto-generates a page from the schema, so this plugin also ships its
+     * own settings card (see `src/client/`).
+     */
+    systemOne: z.object({
+        /** Master switch. Defaults to true; with no credential the gate stays a no-op. */
+        enabled: z.boolean().default(true).volatile(),
+        /** Endpoint accepting the System-one request contract. */
+        endpoint: z.string().default("https://api.typesafe.ai/v1/systemone").volatile(),
+        /** Model identifier sent in the request body. */
+        model: z.string().default("jev-latest").volatile(),
+        /** Literal API key. Declared secret: redacted on every read, write-only in the form. */
+        apiKey: z.string().role("secret").volatile(),
+        /** Credential reference resolved through the credentials service, then the environment. */
+        apiKeyEnv: z.string().role("credential-ref").default("TYPESAFE_API_KEY").volatile(),
+        /** Question type used to judge each candidate. */
+        mode: z.union(["noul", "score"]).default("noul").volatile(),
+        /** noul mode: keep a candidate when its probability is at least this value. */
+        threshold: z.number().min(0).max(1).default(0.5).volatile(),
+        /** score mode: keep a candidate when its score is at least this value.
+         * Jev's `score` is Σ(level_index × probability) over 0…levels−1, NOT 0–1;
+         * with the default 5 levels the range is 0…4, where 2 = "partially relevant". */
+        scoreMin: z.number().default(2).volatile(),
+        /** Retain at least this many candidates when the model rejects an entire page. */
+        minKeep: z.number().step(1).min(0).default(1).volatile(),
+        /** Never judge more than this many candidates per request. */
+        maxCandidates: z.number().step(1).min(1).default(20).volatile(),
+        /** Truncate the task text to this many characters before sending it. */
+        maxTaskChars: z.number().step(1).min(1).default(2000).volatile(),
+        /** End-to-end request deadline in milliseconds. */
+        timeoutMs: z.number().step(1).min(1).default(8000).volatile()
+    })
 });
+/**
+ * Read a config node that may be a plain value or a live (`.volatile()`) node.
+ *
+ * A plugin whose Config declares volatile fields receives a reactive config
+ * whose fields expose `get()`, while hand-written config objects and tests pass
+ * plain values. Both shapes are supported here so the same code path serves the
+ * settings page, `cordis.patch.yml`, and the unit tests.
+ */
+function liveValue(node, fallback) {
+    if (node === undefined || node === null)
+        return fallback;
+    const getter = node.get;
+    if (typeof getter === "function") {
+        const value = getter.call(node);
+        return value === undefined ? fallback : value;
+    }
+    return node;
+}
+/** Read the live `systemOne` section in whichever shape the loader supplied. */
+function systemOneSection(config) {
+    const section = liveValue(config?.systemOne, undefined);
+    return (section ?? {});
+}
+/** Project a (possibly reactive) `systemOne` section into plain settings. */
+function readSystemOne(config) {
+    const section = systemOneSection(config);
+    const mode = liveValue(section.mode, "noul");
+    return {
+        enabled: liveValue(section.enabled, true),
+        endpoint: liveValue(section.endpoint, "https://api.typesafe.ai/v1/systemone"),
+        model: liveValue(section.model, "jev-latest"),
+        mode: mode === "score" ? "score" : "noul",
+        threshold: liveValue(section.threshold, 0.5),
+        scoreMin: liveValue(section.scoreMin, 2),
+        minKeep: liveValue(section.minKeep, 1),
+        maxCandidates: liveValue(section.maxCandidates, 20),
+        maxTaskChars: liveValue(section.maxTaskChars, 2000),
+        timeoutMs: liveValue(section.timeoutMs, 8000),
+        apiKey: liveValue(section.apiKey, undefined),
+        apiKeyEnv: liveValue(section.apiKeyEnv, "TYPESAFE_API_KEY")
+    };
+}
+/**
+ * Resolve the API key for the configured credential reference: a literal key
+ * from the settings page wins, then the harness credentials service, then the
+ * launching environment. Mirrors the shipped web-search provider's order.
+ */
+async function resolveApiKey(hostCtx, section) {
+    if (typeof section.apiKey === "string" && section.apiKey.length > 0)
+        return section.apiKey;
+    const ref = section.apiKeyEnv;
+    if (typeof ref !== "string" || ref.length === 0)
+        return undefined;
+    try {
+        const get = hostCtx?.get;
+        const credentials = typeof get === "function" ? get.call(hostCtx, "credentials") : undefined;
+        const resolve = credentials?.resolve;
+        if (typeof resolve === "function") {
+            const resolved = await resolve.call(credentials, ref);
+            if (resolved?.value !== undefined && resolved.value.length > 0)
+                return resolved.value;
+        }
+    }
+    catch {
+        // Credentials are optional: fall through to the environment.
+    }
+    const ambient = process.env[ref];
+    return ambient !== undefined && ambient.length > 0 ? ambient : undefined;
+}
+/** One text part's worth of content, whatever shape the message carries. */
+function messageText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = content
+        .filter((part) => part?.type === "text")
+        .map((part) => part.text)
+        .filter((text) => typeof text === "string");
+    return parts.length > 0 ? parts.join("\n") : undefined;
+}
+/**
+ * The agent's current task: the most recent user message in the derived
+ * history. Without it the gate would judge candidates against bare keywords,
+ * which is exactly the weak signal the gate is meant to compensate for.
+ */
+function currentTask(exec) {
+    const session = exec?.agent?.session;
+    const derive = session?.deriveMessages;
+    if (typeof derive !== "function")
+        return undefined;
+    let messages;
+    try {
+        messages = derive.call(session);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(messages))
+        return undefined;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message?.role !== "user")
+            continue;
+        const text = messageText(message.content);
+        if (text !== undefined && text.trim().length > 0)
+            return text.trim();
+    }
+    return undefined;
+}
 /** The calling agent's session workspace, when it has one. */
 function sessionCwd(exec) {
     return exec.agent?.session?.header?.cwd;
@@ -152,6 +305,33 @@ function formatSearchResults(value) {
     }
     if (value.results.length === 0)
         lines.push("(no matching memories)");
+    if (value.gated !== undefined) {
+        lines.push("gated: mode=" +
+            value.gated.mode +
+            " model=" +
+            value.gated.model +
+            " judged=" +
+            value.gated.judged +
+            // Only surfaced when the page exceeded maxCandidates, so the default
+            // line stays byte-identical to before this field existed.
+            (value.gated.untouched > 0 ? " untouched=" + value.gated.untouched : "") +
+            " kept=" +
+            value.gated.kept +
+            " dropped=" +
+            value.gated.dropped +
+            // A degraded gate explains itself; a floor (every candidate rejected,
+            // minKeep applied) must be just as visible — otherwise `kept=1` reads
+            // as "one candidate genuinely passed".
+            (value.gated.degraded
+                ? " DEGRADED(" + (value.gated.reason ?? "unknown") + ")"
+                : value.gated.reason === undefined
+                    ? ""
+                    : " NOTE(" + value.gated.reason + ")"));
+        if (value.gated.dropped_hashes.length > 0) {
+            lines.push("  dropped by the gate (mem_read one of these short hashes to recover it): " +
+                value.gated.dropped_hashes.join(","));
+        }
+    }
     if (value.warning !== undefined)
         lines.push("warning: " + value.warning);
     for (const diagnostic of value.diagnostics ?? [])
@@ -162,7 +342,7 @@ function formatSearchResults(value) {
 function registerMemTools(ctx, config) {
     ctx.tools.register(defineTool({
         name: "mem_search",
-        description: "Search the gitmemo long-term memory (.mem git repo) for past task outcomes. Call BEFORE starting repo-related work: extract 1-12 中英文关键词 from the user request (include synonyms in both languages when useful) and run mem_search; pure chat and general Q&A need no search. Returns a snapshot, total, next_skip and up to 20 scored hits with summary/keywords/kind/matched_keywords — score = distinct matched keywords + a mild recency bonus, so newer entries rank slightly higher and superseded conclusions lose to their replacements. Select at most 5 most relevant hits and mem_read them (prefer kind:\"topic\" hits as topic-page entry points). Paginate by passing skip and the returned snapshot back unchanged; a stale snapshot is rejected explicitly.",
+        description: "Search the gitmemo long-term memory (.mem git repo) for past task outcomes. Call BEFORE starting repo-related work: extract 1-12 中英文关键词 from the user request (include synonyms in both languages when useful) and run mem_search; pure chat and general Q&A need no search. Returns a snapshot, total, next_skip and up to 20 scored hits with summary/keywords/kind/matched_keywords — score = distinct matched keywords + a mild recency bonus, so newer entries rank slightly higher and superseded conclusions lose to their replacements. Select at most 5 most relevant hits and mem_read them (prefer kind:\"topic\" hits as topic-page entry points). Paginate by passing skip and the returned snapshot back unchanged; a stale snapshot is rejected explicitly. An optional System-one gate may narrow the page: when the output carries a `gated` block, the entries it removed are listed as 8-char `dropped_hashes` — mem_read one of those if you suspect a relevant memory was filtered out (they stay fully readable). A `NOTE(...)` on the `gated` line means every candidate was judged irrelevant and only a `minKeep` floor was retained, not that one candidate passed.",
         parameters: {
             keywords: { ...KEYWORDS_ARRAY, required: true },
             skip: {
@@ -193,6 +373,47 @@ function registerMemTools(ctx, config) {
                         type: "array",
                         items: { type: "string" },
                         description: "Malformed commit/file mappings skipped during search."
+                    },
+                    gated: {
+                        type: "object",
+                        additionalProperties: false,
+                        description: "Present only when the System-one recall gate ran: how many candidates it judged (and how many past the cap it left untouched), how many it kept, the short hashes it dropped, and whether it had to fail open.",
+                        properties: {
+                            mode: { type: "string", required: true, description: "Question type used: noul or score." },
+                            model: { type: "string", required: true, description: "System-one model the request named." },
+                            candidates: { type: "number", required: true, description: "Size of the candidate page the gate was handed." },
+                            judged: {
+                                type: "number",
+                                required: true,
+                                description: "Candidates actually sent to the endpoint, i.e. min(maxCandidates, candidates)."
+                            },
+                            untouched: {
+                                type: "number",
+                                required: true,
+                                description: "Candidates past maxCandidates: never evaluated, therefore never dropped. Non-zero only on a page larger than the cap."
+                            },
+                            kept: { type: "number", required: true, description: "Candidates the gate retained." },
+                            dropped: { type: "number", required: true, description: "Candidates the gate removed." },
+                            degraded: {
+                                type: "boolean",
+                                required: true,
+                                description: "True when the gate failed open (endpoint/parse failure); every candidate was kept."
+                            },
+                            reason: {
+                                type: "string",
+                                description: "Why the gate degraded, or that it floored a wholly-rejected page (no candidate cleared the threshold, so minKeep were retained)."
+                            },
+                            input_tokens: {
+                                type: "number",
+                                description: "Input tokens the endpoint billed for the gate request (output tokens are free)."
+                            },
+                            dropped_hashes: {
+                                type: "array",
+                                required: true,
+                                items: { type: "string" },
+                                description: "8-char hashes of dropped candidates. Pass one to mem_read to recover a memory the gate judged irrelevant."
+                            }
+                        }
                     }
                 }
             },
@@ -201,11 +422,64 @@ function registerMemTools(ctx, config) {
         isConcurrencySafe: () => true,
         async execute(args, exec) {
             const memo = await engineFor(exec, config);
-            return await memo.search(args.keywords, {
+            const result = await memo.search(args.keywords, {
                 skip: args.skip ?? 0,
                 snapshot: args.snapshot,
                 mode: args.mode
             });
+            // System-one recall gate: purely subtractive, and only ever reached when
+            // an endpoint credential is configured. No credential => this returns the
+            // untouched engine result, so recall behaves exactly as it did before.
+            if (config.gateFor === undefined || result.results.length === 0)
+                return result;
+            const options = await config.gateFor();
+            if (options === undefined)
+                return result;
+            const task = currentTask(exec) ??
+                (Array.isArray(args.keywords) ? args.keywords.join(" ") : String(args.keywords));
+            const candidates = result.results.map((hit) => ({
+                hash: hit.hash,
+                title: hit.title,
+                summary: hit.summary,
+                keywords: hit.keywords,
+                kind: hit.kind
+            }));
+            const decision = await evaluateGate(task, candidates, options, exec?.signal);
+            // Per-candidate values go to the log (for threshold tuning) rather than
+            // into the model context, which is the very thing the gate is shrinking.
+            config.log?.("mem_search gate" +
+                (decision.degraded ? " DEGRADED" : "") +
+                " mode=" + decision.mode +
+                " model=" + decision.model +
+                " candidates=" + candidates.length +
+                " judged=" + decision.judged +
+                (decision.untouched === 0 ? "" : " untouched=" + decision.untouched) +
+                " kept=" + decision.kept.length +
+                " dropped=" + decision.dropped.length +
+                (decision.reason === undefined ? "" : " reason=" + decision.reason) +
+                (decision.usage?.inputTokens === undefined ? "" : " input_tokens=" + decision.usage.inputTokens) +
+                " verdicts=" +
+                decision.verdicts
+                    .map((verdict) => verdict.hash.slice(0, 8) + ":" + (verdict.value ?? "na") + ":" + (verdict.keep ? "keep" : "drop"))
+                    .join(","));
+            const kept = new Set(decision.kept);
+            return {
+                ...result,
+                results: result.results.filter((hit) => kept.has(hit.hash)),
+                gated: {
+                    mode: decision.mode,
+                    model: decision.model,
+                    candidates: candidates.length,
+                    judged: decision.judged,
+                    untouched: decision.untouched,
+                    kept: decision.kept.length,
+                    dropped: decision.dropped.length,
+                    degraded: decision.degraded,
+                    ...(decision.reason === undefined ? {} : { reason: decision.reason }),
+                    ...(decision.usage?.inputTokens === undefined ? {} : { input_tokens: decision.usage.inputTokens }),
+                    dropped_hashes: decision.dropped.map((hash) => hash.slice(0, 8))
+                }
+            };
         },
         presentCall: (args) => ({
             card: "generic",
@@ -489,10 +763,42 @@ function registerPromptSection(ctx) {
  * registration time.
  */
 async function apply(ctx, config = {}) {
+    const log = (message) => {
+        if (typeof ctx.logger.info === "function")
+            ctx.logger.info(message);
+    };
     const resolved = {
         searchLimit: config.searchLimit ?? 20,
         lockTimeoutMs: config.lockTimeoutMs ?? 30000,
-        projectRoot: config.projectRoot
+        projectRoot: config.projectRoot,
+        log,
+        /**
+         * Resolved per search so settings-page edits take effect immediately.
+         * Returns undefined — leaving recall byte-for-byte unchanged — whenever the
+         * gate is switched off or has no usable credential.
+         */
+        gateFor: async () => {
+            const section = readSystemOne(config);
+            if (!section.enabled)
+                return undefined;
+            if (typeof section.endpoint !== "string" || section.endpoint.length === 0)
+                return undefined;
+            const apiKey = await resolveApiKey(ctx, section);
+            if (apiKey === undefined)
+                return undefined;
+            return {
+                endpoint: section.endpoint,
+                model: section.model,
+                mode: section.mode,
+                threshold: section.threshold,
+                scoreMin: section.scoreMin,
+                minKeep: section.minKeep,
+                maxCandidates: section.maxCandidates,
+                maxTaskChars: section.maxTaskChars,
+                timeoutMs: section.timeoutMs,
+                apiKey
+            };
+        }
     };
     if (config.branchAlign !== undefined && config.branchAlign !== true) {
         ctx.logger.warn("dsh-gitmemo: `branchAlign` is deprecated and has no effect — .mem always stays on main");

package/lib/systemone.d.ts

@@ -0,0 +1,213 @@
+/**
+ * dsh-gitmemo — System-one recall gate.
+ *
+ * Optional narrowing stage for `mem_search`. After the engine produces a page
+ * of lexical candidates, a System-one model (TypeSafe Jev by default, or any
+ * endpoint speaking the same request/answer contract) is asked one typed
+ * question per candidate, in a single request. Candidates the model judges
+ * irrelevant are dropped from the page the root agent sees, which cuts the
+ * tokens injected into the conversation.
+ *
+ * Design rules (deliberate, see README):
+ *  - FAIL-OPEN: the gate may only ever REMOVE noise. Any transport, HTTP,
+ *    timeout, or parse failure keeps every candidate and reports `degraded`,
+ *    so a broken or unconfigured endpoint can never hide a memory.
+ *  - NEVER EMPTY: when the gate would drop every candidate on a page, the
+ *    `minKeep` best-ranked candidates are retained. A filter that silently
+ *    returns nothing is indistinguishable from "no memory exists", which is
+ *    the one failure mode a recall path must not have.
+ *  - AUDITABLE: per-candidate values and the keep/drop verdict are returned in
+ *    the tool output's `gated` block, so the decision can be inspected rather
+ *    than trusted.
+ *
+ * This module imports nothing from the harness and performs no I/O of its own
+ * beyond `fetch`, so it is unit-testable with a fake fetch implementation.
+ *
+ * @module dsh-gitmemo/systemone
+ */
+/** Question types this gate can drive. */
+export type SystemOneMode = "noul" | "score";
+/** One candidate memory offered to the gate. */
+export interface GateCandidate {
+    /** Commit hash — the identity used to keep/drop the candidate. */
+    hash: string;
+    /** Entry title (commit subject). */
+    title: string;
+    /** Entry summary (commit body). */
+    summary: string;
+    /** Structured keywords stored with the entry. */
+    keywords: string[];
+    /** Entry kind: `task` or `topic`. */
+    kind: string;
+}
+/** Resolved gate settings for one search. */
+export interface GateOptions {
+    /** Absolute endpoint URL accepting the System-one request contract. */
+    endpoint: string;
+    /** Model identifier sent in the request body (e.g. `jev-latest`). */
+    model: string;
+    /** Question type used to judge each candidate. */
+    mode: SystemOneMode;
+    /** noul mode: keep a candidate when its probability is >= this value (0..1). */
+    threshold: number;
+    /** score mode: keep a candidate when its score is >= this value. */
+    scoreMin: number;
+    /** Retain at least this many candidates when the model rejects the whole page. */
+    minKeep: number;
+    /** Never send more than this many candidates in one request. */
+    maxCandidates: number;
+    /** Truncate the task text to this many characters. */
+    maxTaskChars: number;
+    /** End-to-end request deadline in milliseconds. */
+    timeoutMs: number;
+    /** Literal API key, when one is configured in the settings section. */
+    apiKey?: string;
+    /** Late-bound credential lookup, used when no literal key is configured. */
+    resolveApiKey?: () => Promise<string | undefined>;
+    /** Injectable fetch, for tests. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * One candidate's verdict, retained for auditability.
+ *
+ * `value` is `null` when no readable answer came back for that candidate;
+ * `null` rather than `NaN` because the harness rejects non-finite numbers in
+ * session events and tool output must stay losslessly JSON-serializable.
+ */
+export interface GateVerdict {
+    hash: string;
+    /** Probability (noul) or score (score) returned for this candidate, or null. */
+    value: number | null;
+    /** Whether the candidate survived the gate. */
+    keep: boolean;
+}
+/** Token accounting reported by the endpoint, when it reports any. */
+export interface GateUsage {
+    /** Input tokens billed for the request (Jev bills input only). */
+    inputTokens?: number;
+    /** Output tokens; free on Jev, but reported. */
+    outputTokens?: number;
+}
+/** Outcome of one gate evaluation. */
+export interface GateDecision {
+    /** Hashes retained, in their original order. */
+    kept: string[];
+    /** Hashes removed, in their original order. */
+    dropped: string[];
+    /** Per-candidate verdicts, in candidate order. */
+    verdicts: GateVerdict[];
+    /** Question type actually used. */
+    mode: SystemOneMode;
+    /** Model identifier the request named. */
+    model: string;
+    /** True when the gate failed open (every candidate retained as a result). */
+    degraded: boolean;
+    /**
+     * Why the gate degraded — or, on a `false` {@link degraded} page, that it
+     * floored: no candidate cleared the threshold and `minKeep` was applied.
+     */
+    reason?: string;
+    /**
+     * Candidates actually sent to the endpoint, i.e. `min(maxCandidates, page
+     * size)`. Reported separately from the page size so a truncated judgement is
+     * never mistaken for a full one.
+     */
+    judged: number;
+    /**
+     * Candidates past `maxCandidates`, which were never evaluated and therefore
+     * can never be dropped. Always `0` unless the page exceeded the cap.
+     */
+    untouched: number;
+    /** Endpoint-reported token usage, so the gate's own cost is observable. */
+    usage?: GateUsage;
+}
+/** Score levels offered to the model in `score` mode (ordered low to high). */
+export declare const SCORE_LEVELS: readonly ["unrelated to the task", "same general area but not actionable for this task", "partially relevant background", "substantially relevant and worth reusing", "directly reusable conclusions for this exact task"];
+/**
+ * The judgement asked of the model, verbatim. Kept in English on purpose:
+ * Jev's primary training language is English and the vendor documents lower
+ * accuracy for other scripts, so only the (possibly CJK) candidate text and
+ * task text are non-English.
+ */
+export declare const NOUL_INSTRUCTION = "Does the `candidate` memory record contain conclusions, decisions, constraints, or reusable findings that are directly relevant to the `task`? Answer yes only if reading that memory would inform or change how the task is carried out. Answer no when it is merely on a related topic, is superseded, or concerns a different area.";
+/**
+ * Clarifies what yes and no mean for {@link NOUL_INSTRUCTION}.
+ *
+ * A noul `criteria` is an object with exactly `true` and `false` keys — a bare
+ * string is rejected by the endpoint's validation, so this shape is required.
+ */
+export declare const NOUL_CRITERIA: {
+    readonly true: "yes — the memory is directly reusable for this task";
+    readonly false: "no — unrelated, superseded, or only loosely related to this task";
+};
+/** The judgement asked of the model in `score` mode. */
+export declare const SCORE_INSTRUCTION = "How relevant is the `candidate` memory record to the `task`? Rate how reusable its conclusions, decisions, constraints, or findings are for this exact task.";
+/**
+ * Build the System-one request body: the task is the shared `state`, and each
+ * candidate travels inside its own question's structured `instructions`, so
+ * every candidate is judged against the same task in one request and no
+ * candidate payload is repeated across questions.
+ *
+ * @param task - the agent's current task, used as the shared state.
+ * @param candidates - candidates to judge, already capped by the caller.
+ * @param options - resolved gate settings.
+ * @returns a JSON-serializable request body.
+ */
+export declare function buildRequest(task: string, candidates: readonly GateCandidate[], options: Pick<GateOptions, "mode" | "model" | "maxTaskChars">): {
+    state: {
+        task: string;
+    };
+    model: string;
+    questions: Record<string, unknown>;
+};
+/**
+ * Extract one numeric answer per question id from a System-one response.
+ *
+ * Tolerates both documented envelope shapes (a top-level map of answers, or
+ * the same map nested under `answers`) and both `noul`/`score` field spellings,
+ * so an endpoint that is merely contract-compatible still works.
+ *
+ * @param payload - parsed response JSON.
+ * @param mode - the question type that was asked.
+ * @param count - number of questions sent (ids are `m0`..`m<count-1>`).
+ * @returns the value per question index, or undefined where absent/unreadable.
+ */
+export declare function parseAnswers(payload: unknown, mode: SystemOneMode, count: number): Array<number | undefined>;
+/**
+ * Read the endpoint's token accounting.
+ *
+ * @param payload - parsed response JSON.
+ * @returns camel-cased usage, or undefined when the endpoint reported none.
+ */
+export declare function parseUsage(payload: unknown): GateUsage | undefined;
+/**
+ * Turn per-candidate values into a keep/drop decision.
+ *
+ * Applies the configured threshold, then the `minKeep` floor that guarantees a
+ * non-empty page whenever candidates existed. Candidates with a missing or
+ * unreadable answer are KEPT (fail-open at the per-candidate level).
+ *
+ * @param candidates - candidates in page order.
+ * @param values - value per candidate index (undefined when unreadable).
+ * @param options - resolved gate settings.
+ * @returns kept/dropped hash lists and per-candidate verdicts.
+ */
+export declare function decide(candidates: readonly GateCandidate[], values: ReadonlyArray<number | undefined>, options: Pick<GateOptions, "mode" | "threshold" | "scoreMin" | "minKeep">): {
+    kept: string[];
+    dropped: string[];
+    verdicts: GateVerdict[];
+    floored: boolean;
+};
+/**
+ * Evaluate the gate for one search page.
+ *
+ * Never throws and never returns an empty `kept` list while candidates exist:
+ * every failure path degrades to "keep everything" with a reason.
+ *
+ * @param task - the agent's current task text (shared state).
+ * @param candidates - page candidates; only the first `maxCandidates` are judged.
+ * @param options - resolved gate settings.
+ * @param signal - caller cancellation.
+ * @returns the decision to apply to the page.
+ */
+export declare function evaluateGate(task: string, candidates: readonly GateCandidate[], options: GateOptions, signal?: AbortSignal): Promise<GateDecision>;