@autorag/librarian 2.7.0 → 2.9.0

package/dist/agent/evidence-judgment.d.ts

@@ -0,0 +1,58 @@
+import type { JevJudge } from "./jev-extension.js";
+/**
+ * Retrieval memory stores only evidence that really supports the answer, so
+ * every cited piece is put back to Jev: does this evidence support the
+ * sentence it backs, and is answering the user's question impossible to trust
+ * without it? One batched call covers all of a run's evidence at once.
+ *
+ * The judgment is scoped per evidence and never merges units: a run can cite
+ * one result with several evidence pieces, each backing a different sentence,
+ * and only some of them needed.
+ */
+/** One evidence a final answer cites. */
+export interface EvidenceJudgmentUnit {
+    /** Unique within one call, e.g. `${resultNumber}:${stableEvidenceId}`. */
+    readonly id: string;
+    /** The cited result [n] this evidence backs. */
+    readonly resultNumber: number;
+    /** That result's title. */
+    readonly title: string;
+    /** That result's summary. */
+    readonly summary: string;
+    /** The query that surfaced the evidence. */
+    readonly searchQuery: string;
+    /** Retrieval method that surfaced it. */
+    readonly method: string;
+    /** The evidence text. */
+    readonly excerpt: string;
+}
+export interface EvidenceJudgmentInput {
+    readonly question: string;
+    readonly answer: string;
+    readonly units: readonly EvidenceJudgmentUnit[];
+}
+export interface EvidenceJudgment {
+    /** Jev's P(evidence supports the question), per unit id, for every unit Jev answered. */
+    readonly probabilities: Readonly<Record<string, number>>;
+    /** Unit ids with probability >= {@link EVIDENCE_SUPPORT_THRESHOLD}, in input order. */
+    readonly kept: readonly string[];
+    /** Set when Jev gave no usable verdict for ANY unit (judge threw, or no numeric verdicts); verbatim error / hint text. Absent when Jev decided. */
+    readonly fallbackReason?: string;
+}
+/** Jev question id of one evidence support check. */
+export declare const EVIDENCE_QUESTION_ID_PREFIX = "evidence:";
+/** Jev question id of the support check for one evidence unit. */
+export declare function evidenceQuestionId(unitId: string): string;
+/**
+ * The sentences/lines of `answer` that cite result `number` with a bracketed
+ * `[number]` marker (not a markdown link `[n](...)`). Splits on sentence
+ * terminators followed by whitespace or end, so Korean and English bullet
+ * lists both survive, and dedupes so one sentence backs a result once.
+ */
+export declare function answerSentencesCiting(answer: string, number: number): string[];
+/**
+ * Ask Jev, in one batched call, whether each cited evidence supports its backed
+ * sentence. Never throws: a rejecting judge keeps nothing and reports why, and
+ * a unit Jev left unanswered is simply absent from `probabilities`.
+ */
+export declare function judgeEvidence(judge: JevJudge, input: EvidenceJudgmentInput): Promise<EvidenceJudgment>;

package/dist/agent/evidence-ledger.d.ts

@@ -0,0 +1,59 @@
+import type { RetrievalResult } from "../retrieval/types.js";
+import type { AutoRAGEvidenceRef } from "./emit-results-tool.js";
+export interface LedgerEvidenceInput {
+    readonly method: string;
+    readonly source: string;
+    readonly content: string;
+    readonly retrievalResultId?: string;
+    readonly chunkIndex?: number;
+    readonly lineNumber?: number;
+    readonly parserType?: string;
+    readonly documentType?: string;
+    readonly documentArea?: string;
+    readonly evidenceType?: string;
+    readonly evidenceLocation?: string;
+}
+export interface ResolveEvidenceOptions {
+    /** Tool name used to prefix corrective errors. */
+    readonly label: string;
+    /** Result number the refs belong to; named in corrective errors. */
+    readonly number: number;
+    /** Excerpt recorded for a local file the model opened itself (no search returned it). */
+    readonly fallbackContent: string;
+    /** False in remote sessions: only evidence a tool returned this run may be cited. */
+    readonly allowLocalFiles: boolean;
+}
+/**
+ * Per-run record of every piece of evidence a retrieval tool returned.
+ *
+ * Tools hand the model a short id (`e1`, `e2`, ...) next to each result. The
+ * model cites evidence by id; the harness resolves the id back to the exact
+ * source, method, content, and chunk metadata it recorded. The model never
+ * retypes a path or a chunk, so it cannot misquote or invent one, and the
+ * stable evidence id stored in memory is always derived from real evidence.
+ */
+export declare class EvidenceLedger {
+    private entries;
+    private readonly byKey;
+    private readonly byId;
+    /**
+     * Ordinal of the last issued id. Survives {@link clear}: a hosted (TUI)
+     * conversation keeps earlier runs' tool output in context, so restarting at
+     * e1 would let a stale id silently resolve to a different chunk.
+     */
+    private lastOrdinal;
+    /** Record evidence and return its id. The same chunk always gets the same id. */
+    register(input: LedgerEvidenceInput): string;
+    /** Record one retrieval result as returned by `tool`; backend metadata is carried over. */
+    registerResult(tool: string, result: RetrievalResult): string;
+    /**
+     * Resolve model-supplied refs to recorded evidence. A ref is an evidence id
+     * (`e3` or `[e3]`), the exact source a tool returned (a URL, a datasource
+     * id, a path), or the absolute path of a real local file the model opened
+     * itself. Anything else throws a corrective error naming the result.
+     */
+    resolve(refs: readonly string[], options: ResolveEvidenceOptions): AutoRAGEvidenceRef[];
+    /** Forget every recorded entry. Ids are never reissued, so a previous run's id stays unresolvable. */
+    clear(): void;
+    private unresolvedMessage;
+}

package/dist/agent/evidence-origins.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Remembers which search query and retrieval method surfaced each retrieval
+ * result during a run, so a final answer's evidence refs (which carry only a
+ * source, method, and text) can be mapped back to the query that found them.
+ * Retrieval memory needs both to store an evidence record; the refs alone do
+ * not know their query.
+ */
+/** The query, retrieval method, and source of a remembered result. */
+export interface EvidenceOrigin {
+    readonly query: string;
+    readonly method: string;
+    readonly source: string;
+}
+/** One retrieval result the agent saw, together with the query that produced it. */
+export interface EvidenceOriginCandidate extends EvidenceOrigin {
+    readonly content: string;
+}
+/** The parts of a cited evidence ref that identify its origin. */
+export interface EvidenceRefLike {
+    readonly source: string;
+    readonly method: string;
+    readonly excerpt?: string;
+    readonly content?: string;
+}
+/**
+ * Insertion-ordered index of retrieval results keyed by their source. Matching
+ * is deliberately text-based: a final answer's ref text is the same excerpt the
+ * retrieval returned, so it shares the candidate's content even when the ref
+ * carries a different method.
+ */
+export declare class EvidenceOriginIndex {
+    private readonly candidates;
+    /** Sources already remembered, to the normalized contents seen for each. */
+    private readonly seen;
+    /**
+     * Remember one retrieval result and the query/method that produced it.
+     * First write wins for an identical (source, normalized content) pair.
+     */
+    add(candidate: EvidenceOriginCandidate): void;
+    /** Where `ref` came from, or undefined when no remembered result matches. */
+    resolve(ref: EvidenceRefLike): EvidenceOrigin | undefined;
+    /**
+     * Match a ref that carries no source (its text is the evidence text the
+     * answering model cited, possibly several excerpts joined by newlines)
+     * against every remembered candidate by text alone.
+     */
+    private resolveSourceless;
+    clear(): void;
+}

package/dist/agent/fast-answer-tool.d.ts

@@ -1,5 +1,7 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
+import type { AutoRAGEvidenceRef } from "./emit-results-tool.js";
+import type { EvidenceLedger } from "./evidence-ledger.js";
 export declare const EMIT_FAST_ANSWER_TOOL_NAME = "emit_fast_answer";
 declare const fastAnswerSchema: Type.TObject<{
     answer: Type.TString;
@@ -12,11 +14,8 @@ declare const fastAnswerSchema: Type.TObject<{
             lineNumber: Type.TOptional<Type.TInteger>;
         }>>>;
         confidence: Type.TOptional<Type.TNumber>;
+        refs: Type.TOptional<Type.TArray<Type.TString>>;
     }>>;
-    sources: Type.TOptional<Type.TArray<Type.TObject<{
-        number: Type.TInteger;
-        source: Type.TString;
-    }>>>;
 }>;
 export interface AutoRAGFastAnswerResult {
     readonly number: number;
@@ -31,16 +30,27 @@ export interface AutoRAGFastAnswerResult {
 export interface AutoRAGFastAnswerDetails {
     readonly answer: string;
     readonly results: readonly AutoRAGFastAnswerResult[];
+    /** Number -> primary source, derived from `evidenceRefs`. */
     readonly sources: readonly {
         readonly number: number;
         readonly source: string;
     }[];
+    /** Harness-recorded evidence each result cited; never model-written text. */
+    readonly evidenceRefs: readonly {
+        readonly number: number;
+        readonly refs: readonly AutoRAGEvidenceRef[];
+    }[];
+}
+export interface EmitFastAnswerToolOptions {
+    /** Evidence the baseline retrieval produced; `refs` resolve against it. */
+    readonly ledger: EvidenceLedger;
 }
 /**
  * Builds the non-terminating fast-answer tool used by the two-phase search
  * flow. The model calls this exactly once during the thinking-off fast phase
  * to deliver an immediate, complete first answer; the run then continues into
- * the verification phase, which ends with emit_autorag_results.
+ * the verification phase, which ends with emit_autorag_results. Sources are
+ * derived from the evidence ids the model cites, never typed by the model.
  */
-export declare function createEmitFastAnswerTool(capture: (details: AutoRAGFastAnswerDetails) => void): AgentTool<typeof fastAnswerSchema, AutoRAGFastAnswerDetails>;
+export declare function createEmitFastAnswerTool(capture: (details: AutoRAGFastAnswerDetails) => void, options: EmitFastAnswerToolOptions): AgentTool<typeof fastAnswerSchema, AutoRAGFastAnswerDetails>;
 export {};

package/dist/agent/index.d.ts

@@ -3,7 +3,8 @@ export { AutoRAGAgent } from "./agent.js";
 export { buildDatasourceSkillsPrompt, createLoadDatasourceSkillTool, type DatasourceSkillProvider, datasourceSkillLocation, formatDatasourceSkillInvocation, LOAD_DATASOURCE_SKILL_TOOL_NAME, type LoadDatasourceSkillDetails, toDatasourceAgentSkill, } from "./datasource-skill.js";
 export { createScanDuplicateDocumentsTool, SCAN_DUPLICATE_DOCUMENTS_TOOL_NAME, type ScanDuplicateDocumentsDetails, type ScanDuplicateDocumentsProvider, } from "./dupey-tool.js";
 export type { AutoRAGEmittedResult, AutoRAGMappingEntry, AutoRAGResultsDetails, } from "./emit-results-tool.js";
-export { createEmitResultsTool, EMIT_AUTORAG_RESULTS_TOOL_NAME, emitResultsSchema, } from "./emit-results-tool.js";
+export { createEmitResultsTool, EMIT_AUTORAG_RESULTS_TOOL_NAME, emitResultsSchema, reportSchema, } from "./emit-results-tool.js";
+export { createJevExtension, JEV_TOOL_NAME, type JevBackendName, type JevToolOptions, } from "./jev-extension.js";
 export { createJikjiFindTool, JIKJI_FIND_TOOL_NAME, type JikjiFindDetails, type JikjiFindPerRootPolicy, type JikjiFindProvider, type JikjiFindProviderResult, type MergedJikjiPolicy, } from "./jikji-find-tool.js";
 export { createQueryPeerAgentTool, QUERY_PEER_AGENT_TOOL_NAME, type QueryPeerAgentDetails, type QueryPeerAgentResult, type QueryPeerAgentToolOptions, } from "./query-peer-tool.js";
 export { createSearchAllDocumentsTool, SEARCH_ALL_DOCUMENTS_TOOL_NAME, type SearchAllDocumentsDetails, type SearchAllDocumentsProvider, type SearchAllDocumentsResult, } from "./search-all-tool.js";

package/dist/agent/jev-extension.d.ts

@@ -0,0 +1,68 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { type JevBackend, type Judgment, type Question, type State } from "jev-use";
+/** `jev` tool name, kept in AutoRAG's reserved set and system prompt. */
+export declare const JEV_TOOL_NAME = "jev";
+/**
+ * Jev backends the `jev-use` engine resolves from the environment, in
+ * auto-select order: TypeSafe -> OpenRouter -> Vercel AI Gateway.
+ */
+export type JevBackendName = "typesafe" | "openrouter" | "vercel";
+/**
+ * OpenRouter's live Jev model id. `jev-use` 0.8.0 ships `typesafe/jev-latest`,
+ * which OpenRouter rejects with HTTP 400 ("Model ... does not exist"), so the
+ * OpenRouter path is pinned here.
+ */
+export declare const OPENROUTER_DEFAULT_MODEL = "typesafe/jev-1.13";
+/**
+ * Options for the `jev` decision tool. Secrets never appear here: `jev-use`
+ * reads the backend credential from its own environment variable
+ * (`TYPESAFE_API_KEY`, `OPENROUTER_API_KEY`, or `AI_GATEWAY_API_KEY`).
+ */
+export interface JevToolOptions {
+    /**
+     * Force one backend by name; omit to let the first credential present win.
+     * A ready-made `jev-use` backend instance is a programmatic seam (tests,
+     * custom transports); config only accepts names.
+     */
+    readonly backend?: JevBackendName | JevBackend;
+    /**
+     * Wire model id sent with every call. Omit for the backend default;
+     * OpenRouter is pinned to {@link OPENROUTER_DEFAULT_MODEL} because
+     * `jev-use` 0.8.0's own default (`typesafe/jev-latest`) is not a live
+     * OpenRouter model id.
+     */
+    readonly model?: string;
+    /** Escalate verdicts below this confidence. Default: per-source thresholds. */
+    readonly confidenceThreshold?: number;
+}
+/** {@link JevToolOptions} plus the environment `jev-use` resolves credentials from. */
+export interface JevJudgeOptions extends JevToolOptions {
+    /** Environment consulted for the backend credential. Default `process.env`. */
+    readonly env?: Record<string, string | undefined>;
+}
+/**
+ * One batched Jev judgment. Rejects only when no backend can be built (for
+ * example a missing credential); an unreachable backend resolves with
+ * `escalate: true` verdicts, per `jev-use`'s contract.
+ */
+export type JevJudge = (state: State, questions: Question[], options?: {
+    readonly confidenceThreshold?: number;
+}) => Promise<Judgment>;
+/**
+ * Builds the Jev judge shared by the `jev` tool and the query router. The
+ * `jev-use` client is created lazily on the first call, so no credential
+ * resolves at construction time, and the OpenRouter model pin applies to
+ * every caller.
+ */
+export declare function createJevJudge(options?: JevJudgeOptions): JevJudge;
+/**
+ * Builds the pi extension that registers the `jev` decision tool on top of the
+ * [`jev-use`](https://www.npmjs.com/package/jev-use) engine.
+ *
+ * Jev is TypeSafe's judgment model: typed questions about a state in, calibrated
+ * probabilities out — no generated text. `jev-use` owns backend auto-selection,
+ * request screening, and response validation; this extension only adapts the
+ * pi tool surface over {@link createJevJudge}. Pass the agent's shared judge
+ * so the tool and the query router reuse one lazily built client.
+ */
+export declare function createJevExtension(judgeOrOptions?: JevJudge | JevToolOptions): ExtensionFactory;

package/dist/agent/jikji-find-tool.d.ts

@@ -1,6 +1,7 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
 import type { JikjiAnswerPack, JikjiCandidate, JikjiDiagnostic, JikjiEvidence, JikjiHandoffAction } from "../jikji/index.js";
+import { EvidenceLedger } from "./evidence-ledger.js";
 export declare const JIKJI_FIND_TOOL_NAME = "jikji_find";
 /**
  * Run-scoped merged policy assembled from per-root Jikji answer packs using
@@ -71,5 +72,5 @@ declare const jikjiFindSchema: Type.TObject<{
  * Jikji is unavailable or all roots failed, the tool returns a short fallback
  * message so the agent falls back to bash, and no policy is set.
  */
-export declare function createJikjiFindTool(provider: JikjiFindProvider): AgentTool<typeof jikjiFindSchema, JikjiFindDetails>;
+export declare function createJikjiFindTool(provider: JikjiFindProvider, ledger?: EvidenceLedger): AgentTool<typeof jikjiFindSchema, JikjiFindDetails>;
 export {};

package/dist/agent/pi-session.d.ts

@@ -1,7 +1,14 @@
 import type { AgentMessage, AgentTool } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
-import { type AgentSession, type AgentSessionRuntime, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, type AgentSessionRuntime, type ExtensionAPI, type ExtensionFactory, SettingsManager, type ToolDefinition, type TuiMode } from "@earendil-works/pi-coding-agent";
 export declare const PI_BUILTIN_TOOL_NAMES: readonly ["read", "bash", "edit", "write", "grep", "find", "ls"];
+/**
+ * Terminal UI mode for AutoRAG's interactive session. pi 1.0 switched its own default to
+ * fullscreen; AutoRAG shipped on pi's scrollback UI, so that stays the default. A `tuiMode` the
+ * user saved in pi's global or project settings still wins, and `InteractiveMode` accepts the
+ * result directly (its constructor otherwise falls back to pi's fullscreen default).
+ */
+export declare function resolveInteractiveTuiMode(settingsManager: SettingsManager): TuiMode;
 export interface AutoRAGPiSessionOptions {
     readonly cwd: string;
     readonly agentDir?: string;
@@ -13,6 +20,17 @@ export interface AutoRAGPiSessionOptions {
     readonly providerApiKeys?: Readonly<Record<string, string>>;
     readonly getSystemPrompt: () => string;
     readonly customTools: readonly AgentTool[];
+    /**
+     * Extra pi extensions to load alongside AutoRAG's own prompt/context
+     * extension. Each factory registers its tools, commands, and events with pi.
+     */
+    readonly extensionFactories?: readonly ExtensionFactory[];
+    /**
+     * Tool names registered by {@link extensionFactories}. pi's `tools`
+     * allow-list keeps only named tools active, so every extension tool that
+     * should be callable must appear here too.
+     */
+    readonly extensionToolNames?: readonly string[];
     readonly remoteSession?: boolean;
     readonly contextTransform?: (messages: AgentMessage[]) => Promise<AgentMessage[]>;
 }
@@ -20,12 +38,21 @@ export interface AutoRAGPiInteractiveRuntimeOptions extends Omit<AutoRAGPiSessio
     readonly model?: Model<Api>;
     readonly inactiveToolNames?: readonly string[];
     readonly onQuery: (query: string, pi: ExtensionAPI) => void | Promise<void>;
+    /**
+     * Optional best-effort provider for a startup update notice. Resolves to the
+     * notice text, or `undefined` when there is nothing to announce. Called once
+     * per session; failures are swallowed so the check never blocks or fails a
+     * launch.
+     */
+    readonly updateNotice?: () => Promise<string | undefined>;
 }
 export interface AutoRAGPiSession {
     readonly session: AgentSession;
     readonly baseToolNames: readonly string[];
     readonly sessionFile: string | undefined;
 }
+/** Adapts a pi-agent-core {@link AgentTool} to pi's extension {@link ToolDefinition}. */
+export declare function toToolDefinition(tool: AgentTool): ToolDefinition;
 /** Creates a pi session with AutoRAG's tools and prompt. */
 export declare function createAutoRAGPiSession(options: AutoRAGPiSessionOptions): Promise<AutoRAGPiSession>;
 export interface AutoRAGPiInteractiveRuntime {

package/dist/agent/query-decomposition.d.ts

@@ -0,0 +1,25 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+/** Hard cap on search queries one question may decompose into. */
+export declare const MAX_DECOMPOSED_QUERIES = 5;
+/** Prompt in, raw completion text out. The seam the decomposer calls. */
+export type DecompositionCompleter = (prompt: string) => Promise<string>;
+/** A pi-ai model plus the credential used only for decomposition calls. */
+export interface DecompositionModel {
+    readonly model: Model<Api>;
+    readonly apiKey?: string;
+}
+export declare function buildDecompositionPrompt(query: string): string;
+/**
+ * Parse the model's reply into at most {@link MAX_DECOMPOSED_QUERIES} unique,
+ * non-empty queries. Accepts `{"queries": [...]}`, a bare array (optionally
+ * fenced or wrapped in prose), or one query per line as a last resort.
+ */
+export declare function parseDecomposedQueries(text: string): string[];
+/**
+ * Decompose one question into up to {@link MAX_DECOMPOSED_QUERIES} search
+ * queries. A reply with no usable query falls back to the original question,
+ * so the caller always has something to search.
+ */
+export declare function decomposeQuery(complete: DecompositionCompleter, query: string): Promise<string[]>;
+/** Completer over a pi-ai model: one user turn, thinking off, short output. */
+export declare function createModelDecompositionCompleter(target: DecompositionModel, signal?: AbortSignal): DecompositionCompleter;

package/dist/agent/query-peer-tool.d.ts

@@ -3,6 +3,7 @@ import { Type } from "typebox";
 import { type SimplexQueryState } from "../p2p/simplex-query-store.js";
 import type { SimplexTransport } from "../p2p/simplex-transport.js";
 import type { PeerQueryResponse } from "../p2p/wire.js";
+import { EvidenceLedger } from "./evidence-ledger.js";
 export declare const QUERY_PEER_AGENT_TOOL_NAME = "query_peer_agent";
 declare const queryPeerAgentSchema: Type.TObject<{
     alias: Type.TString;
@@ -39,6 +40,8 @@ export interface QueryPeerAgentToolOptions {
     readonly sessionId?: () => string | undefined;
     readonly onResponse?: (state: SimplexQueryState, response: PeerQueryResponse) => void;
     readonly onExpired?: (state: SimplexQueryState) => void;
+    /** Run evidence ledger; each peer result is registered so the final emit can cite it by id. */
+    readonly ledger?: EvidenceLedger;
 }
 export interface QueryPeerAgentTool extends AgentTool<typeof queryPeerAgentSchema, QueryPeerAgentDetails> {
     readonly ready: Promise<void>;

package/dist/agent/query-routing.d.ts

@@ -0,0 +1,115 @@
+import type { JevJudge } from "./jev-extension.js";
+/**
+ * Where a user question is answered from:
+ * - `local`: anything needing information beyond the model's own knowledge —
+ *   the user's files, chats, mail, or any fact the model cannot reliably recall.
+ *   Local retrieval runs first; web search is left to the agent after the fast
+ *   answer, when local evidence falls short.
+ * - `direct`: intrinsic knowledge or small talk the model answers on its own.
+ * - `config`: the user wants to inspect or change AutoRAG's own settings
+ *   (model, providers, datasources). Offered only when the host enables
+ *   agent self-configuration.
+ */
+export type QueryRoute = "local" | "direct" | "config";
+/** Jev question id of the intrinsic-knowledge / local branch. */
+export declare const QUERY_ROUTE_QUESTION_ID = "route";
+/** Jev question id of the "does this need decomposition?" check. */
+export declare const DECOMPOSE_QUESTION_ID = "decompose";
+/** Jev question id of the post-fast-answer "needs follow-up?" check. */
+export declare const FOLLOW_UP_QUESTION_ID = "follow_up";
+/** Route used whenever Jev gives no usable branch: today's local search. */
+export declare const FALLBACK_QUERY_ROUTE: QueryRoute;
+/** A `noul` probability at or above this asks for question decomposition. */
+export declare const DECOMPOSE_PROBABILITY_THRESHOLD = 0.5;
+/** A `noul` probability at or above this sends the fast answer on to verification. */
+export declare const FOLLOW_UP_PROBABILITY_THRESHOLD = 0.5;
+/**
+ * Minimum Jev branch probability required to leave local search. A `direct`
+ * branch at or below this floor — or one Jev reported without a probability —
+ * keeps the run on local search, the corpus-grounded default.
+ * Without the floor a weakly-favored `direct` verdict (observed at p 0.57-0.63
+ * on personal-corpus questions) skips retrieval entirely and answers from
+ * general knowledge, so the caller loses the evidence the question depends on.
+ */
+export declare const NON_LOCAL_ROUTE_PROBABILITY_THRESHOLD = 0.75;
+/** A `noul` probability at or above this searches that datasource before the fast answer. */
+export declare const DATASOURCE_PROBABILITY_THRESHOLD = 0.5;
+/** Jev question id of the "search this datasource?" check for one datasource. */
+export declare function datasourceQuestionId(datasourceId: string): string;
+export interface FollowUpDecision {
+    /** True when the run continues into the verification phase. */
+    readonly followUp: boolean;
+    /** Jev's P(follow-up needed), when it answered. */
+    readonly probability?: number;
+    /** Why the check fell back to verifying instead of following Jev; absent when Jev decided. */
+    readonly fallbackReason?: string;
+}
+/**
+ * Ask Jev whether the fast answer needs correction, clarification, or further
+ * research. Never throws: a missing credential, an unreachable backend, or a
+ * verdict with no probability keeps verifying, because ending early on an
+ * unchecked answer is the costlier mistake.
+ */
+export declare function needsFollowUp(judge: JevJudge, query: string, answer: string): Promise<FollowUpDecision>;
+export interface QueryRouteDecision {
+    /** Most probable branch; {@link FALLBACK_QUERY_ROUTE} when Jev gave none or its non-local branch missed {@link NON_LOCAL_ROUTE_PROBABILITY_THRESHOLD}. */
+    readonly route: QueryRoute;
+    /** True when Jev judged the question needs decomposition (never for `direct`). */
+    readonly decompose: boolean;
+    /** Probability Jev gave the winning branch, including a rejected non-local branch whose floor moved the route to local. */
+    readonly routeProbability?: number;
+    /** Jev's P(decomposition needed), when it answered. */
+    readonly decomposeProbability?: number;
+    /** Why the decision fell back instead of following Jev; absent when Jev decided. */
+    readonly fallbackReason?: string;
+}
+export interface RouteQueryOptions {
+    /** Offer the `config` branch: the agent may change its own settings. */
+    readonly selfConfig?: boolean;
+}
+/**
+ * Ask Jev, in one batched call about the user question, which branch answers
+ * it and whether it needs decomposition. Never throws: a missing credential,
+ * an unreachable backend, an unusable verdict, or a `direct` branch that does
+ * not clear {@link NON_LOCAL_ROUTE_PROBABILITY_THRESHOLD} falls back to a
+ * single local search, with the reason recorded.
+ */
+export declare function routeQuery(judge: JevJudge, query: string, options?: RouteQueryOptions): Promise<QueryRouteDecision>;
+/** One configured datasource Jev may send the question to. */
+export interface DatasourceCandidate {
+    readonly datasourceId: string;
+    /** Content kind, e.g. `chat`, `mail`, `docs`. */
+    readonly type: string;
+    /** Operator- or connector-authored description of what the datasource holds. */
+    readonly description: string;
+}
+export interface DatasourceSelection {
+    /** Datasource ids to search, in registration order. */
+    readonly selected: readonly string[];
+    /** Jev's P(search needed) per datasource id, for every datasource it answered. */
+    readonly probabilities: Readonly<Record<string, number>>;
+    /** Why no datasource is searched instead of following Jev; absent when Jev decided. */
+    readonly fallbackReason?: string;
+}
+/** A similar question asked before, its results, and where each was found. */
+export interface PastSearchHint {
+    readonly query: string;
+    /**
+     * Results it returned. `foundIn` names registered datasource ids, `local
+     * files`, or `web`; a title can also record that nothing was found there.
+     */
+    readonly results: readonly {
+        readonly title: string;
+        readonly foundIn: readonly string[];
+    }[];
+}
+/**
+ * Ask Jev, in one batched call, one `noul` per registered datasource: does
+ * answering the question need that datasource searched? The state describes
+ * every datasource (descriptions are flagged as non-exhaustive summaries), so
+ * Jev judges each one against the others, plus where similar past questions
+ * were answered, when retrieval memory has any. Never throws: a missing
+ * credential or an unreachable backend searches no datasource, which is the
+ * behavior without Jev.
+ */
+export declare function selectDatasources(judge: JevJudge, query: string, datasources: readonly DatasourceCandidate[], pastSearches?: readonly PastSearchHint[]): Promise<DatasourceSelection>;

package/dist/agent/search-all-tool.d.ts

@@ -1,6 +1,7 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
 import type { RetrievalDiagnostic, RetrievalResult } from "../retrieval/types.js";
+import { EvidenceLedger } from "./evidence-ledger.js";
 import { type SearchDocumentRetrievalTraceResult } from "./search-documents.js";
 export declare const SEARCH_ALL_DOCUMENTS_TOOL_NAME = "search_all_documents";
 declare const searchAllSchema: Type.TObject<{
@@ -30,10 +31,9 @@ export interface SearchAllDocumentsDetails {
 }
 /**
  * LLM-facing wrapper around multi-method merged retrieval. The
- * schema accepts only `{ query, topK?, scope? }`; datasource trust fields such
- * as `allowedTags`/`allowedScopes` are not part of the schema and are never
- * forwarded to the provider — only `query`, `topK`, and `scope` are passed
- * through, so model-provided extra properties cannot widen datasource access.
+ * schema accepts only `{ query, topK?, scope? }`; extra model-provided
+ * properties are not part of the schema and are never forwarded to the
+ * provider — only `query`, `topK`, and `scope` are passed through.
  */
-export declare function createSearchAllDocumentsTool(provider: SearchAllDocumentsProvider): AgentTool<typeof searchAllSchema, SearchAllDocumentsDetails>;
+export declare function createSearchAllDocumentsTool(provider: SearchAllDocumentsProvider, ledger?: EvidenceLedger): AgentTool<typeof searchAllSchema, SearchAllDocumentsDetails>;
 export {};

package/dist/agent/search-documents.d.ts

@@ -10,7 +10,7 @@ export type SearchDocumentDiagnosticSeverity = "info" | "warning" | "error";
  * (#21/#22) does not require another source-breaking type change; codes not yet
  * emitted are still valid members.
  */
-export type SearchDocumentDiagnosticCode = "empty-query" | "no-verified-results" | "unknown-warning" | "caller-tool-dropped" | "minsync-unavailable" | "minsync-staging-excluded" | "minsync-sync-failed" | "embedder-unavailable" | "embedding-identity-mismatch" | "parser-skipped" | "parser-failed" | "parser-warning" | "duplicate-excluded" | "unsupported-file" | "stale-index" | "deleted-mirror" | "pdf-extract-thin" | "retrieval-method-failed" | "rerank-failed" | "jikji-unavailable" | "jikji-prepare-failed" | "jikji-find-failed" | "everything-index-failed" | "fsearch-index-failed" | "fsearch-binary-missing" | "refresh-failed" | "refresh-interrupted" | "watch-failed" | "watch-limited" | "unknown-datasource-skill" | "missing-final-emit" | "model-request-failed";
+export type SearchDocumentDiagnosticCode = "empty-query" | "no-verified-results" | "unknown-warning" | "caller-tool-dropped" | "minsync-staging-excluded" | "minsync-sync-failed" | "embedder-unavailable" | "embedding-identity-mismatch" | "parser-skipped" | "parser-failed" | "source-vanished" | "source-unreadable" | "parser-warning" | "duplicate-excluded" | "unsupported-file" | "stale-index" | "deleted-mirror" | "pdf-extract-thin" | "retrieval-method-failed" | "rerank-failed" | "jikji-unavailable" | "jikji-prepare-failed" | "jikji-find-failed" | "everything-index-failed" | "fsearch-index-failed" | "fsearch-binary-missing" | "refresh-failed" | "refresh-interrupted" | "watch-failed" | "watch-limited" | "unknown-datasource-skill" | "missing-final-emit" | "model-request-failed" | "search-timeout" | "query-routed" | "query-route-fallback" | "query-decomposition-failed" | "follow-up-skipped" | "follow-up-check-fallback" | "datasources-selected" | "datasource-selection-fallback" | "citation-without-result" | "evidence-judged" | "evidence-judgment-fallback" | "memory-search-fallback" | "self-config-unavailable" | "self-config-rolled-back";
 export interface SearchDocumentDiagnostic {
     readonly code: SearchDocumentDiagnosticCode;
     readonly severity: SearchDocumentDiagnosticSeverity;
@@ -28,7 +28,6 @@ export interface SearchDocumentResult {
     readonly summary: string;
     readonly evidence: readonly SearchDocumentEvidence[];
     readonly confidence: number;
-    readonly feedbackId: string;
     readonly source?: string;
 }
 /** One retrieval candidate captured in a run's retrieval trace. */
@@ -88,24 +87,17 @@ export type SearchDocumentsStreamEvent = {
 type SearchSession = {
     query: string;
     registry: Map<number, CuratedResult>;
-    transient?: boolean;
 };
 type SearchSessions = Map<string, SearchSession>;
-type ReadonlySearchSessions = ReadonlyMap<string, {
-    query: string;
-    registry: ReadonlyMap<number, CuratedResult>;
-    transient?: boolean;
-}>;
 /**
  * Build the preliminary (fast-phase) search response. Unlike
  * {@link recordStructuredResultsSession} this NEVER touches memory or the
- * feedback session registry — the final response owns those. Feedback ids are
- * namespaced with `:preliminary:` so they can never collide with final ids.
+ * session registry — the final response owns those.
  */
 export declare function createPreliminarySearchDocumentsResponse(sessionId: string, query: string, details: AutoRAGFastAnswerDetails, diagnostics?: readonly SearchDocumentDiagnostic[]): SearchDocumentsResponse;
 export declare function createEmptySearchDocumentsResponse(sessionId: string, query: string, sessions: SearchSessions, diagnostics?: readonly SearchDocumentDiagnostic[]): SearchDocumentsResponse;
 export declare function recordStructuredResultsSession(sessionId: string, query: string, details: AutoRAGResultsDetails, sessions: SearchSessions, memory: RetrievalMemory, componentDiagnostics?: readonly SearchDocumentDiagnostic[], options?: {
+    /** Record the session registry only, skipping the retrieval-memory write. */
     readonly isolateMemory?: boolean;
 }): SearchDocumentsResponse;
-export declare function recordNumberedFeedback(sessions: ReadonlySearchSessions, memory: RetrievalMemory, sessionId: string, usefulNumbers: readonly number[], notUsefulNumbers: readonly number[]): void;
 export {};

package/dist/agent/search-minsync-tool.d.ts

@@ -1,6 +1,7 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
 import type { MinSyncVectorMethod } from "../minsync/method.js";
+import { EvidenceLedger } from "./evidence-ledger.js";
 import { type SearchDocumentRetrievalTraceResult } from "./search-documents.js";
 export declare const SEARCH_MINSYNC_DOCUMENTS_TOOL_NAME = "semantic_search_local_docs";
 declare const searchMinSyncSchema: Type.TObject<{
@@ -12,16 +13,15 @@ export interface SearchMinSyncDocumentsDetails {
     readonly method: "semantic_search_local_docs";
     readonly resultCount: number;
     readonly sources: readonly string[];
-    readonly available: boolean;
     /** Top candidates in traceable shape (additive; used for the run's retrieval trace). */
     readonly results?: readonly SearchDocumentRetrievalTraceResult[];
 }
 /**
  * LLM-facing wrapper around the {@link MinSyncVectorMethod} vector
  * retrieval. The model can only supply `query`, `topK`, and an opaque `scope`.
- * When the method is missing, the binary is missing, or retrieval errors, the
- * tool returns a path-free unavailable message with `available: false` and a
- * zero result count — never a real binary or workspace path.
+ * MinSync is required, so a missing binary or a failed query is not turned
+ * into an "unavailable" result: the error propagates with its own message and
+ * the harness reports it as a failed tool call.
  */
-export declare function createSearchMinSyncDocumentsTool(getMethod: () => MinSyncVectorMethod | undefined, resolveScope?: (scope: string | undefined) => string | undefined): AgentTool<typeof searchMinSyncSchema, SearchMinSyncDocumentsDetails>;
+export declare function createSearchMinSyncDocumentsTool(getMethod: () => MinSyncVectorMethod, resolveScope?: (scope: string | undefined) => string | undefined, ledger?: EvidenceLedger): AgentTool<typeof searchMinSyncSchema, SearchMinSyncDocumentsDetails>;
 export {};