@autorag/librarian 2.8.0 → 2.9.0

package/dist/agent/datasource-skill.d.ts

@@ -1,42 +1,56 @@
-import type { AgentTool, Skill } from "@earendil-works/pi-agent-core";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
 import type { DatasourceSkillManifest } from "../datasource/types.js";
 export declare const LOAD_DATASOURCE_SKILL_TOOL_NAME = "load_datasource_skill";
 /**
- * Opaque, path-free location used as the Pi `Skill.filePath` for a datasource
- * skill. Datasource skills have no real backing file, and AutoRAG must never
+ * A datasource skill as the agent sees it: name and description for the
+ * system-prompt listing, full `content` loaded on demand, and an opaque
+ * `datasource://` location. pi's own `Skill` is file-backed (`baseDir`,
+ * `sourceInfo`) and has no `content`, so datasource skills, which have no
+ * backing file, use this shape instead.
+ */
+export interface DatasourceAgentSkill {
+    readonly name: string;
+    readonly description: string;
+    /** Full skill instructions, returned by `load_datasource_skill`. */
+    readonly content: string;
+    /** Opaque `datasource://<name>` location; never a real filesystem path. */
+    readonly filePath: string;
+}
+/**
+ * Opaque, path-free location used as the `filePath` of a datasource skill.
+ * Datasource skills have no real backing file, and AutoRAG must never
  * expose real filesystem paths, so we use a `datasource://<name>` scheme.
  */
 export declare function datasourceSkillLocation(name: string): string;
 /**
- * Map a datasource skill manifest onto the Pi agent-skill layer. The resulting
- * `Skill` is injected into the system prompt (name/description/location) for
+ * Map a datasource skill manifest onto the agent-skill shape. The resulting
+ * skill is listed in the system prompt (name/description/location) for
  * progressive disclosure and its `content` is loaded on demand.
  */
-export declare function toDatasourceAgentSkill(manifest: DatasourceSkillManifest): Skill;
+export declare function toDatasourceAgentSkill(manifest: DatasourceSkillManifest): DatasourceAgentSkill;
 /**
- * Render the Pi `<available_skills>` progressive-disclosure block for the
- * authorized datasource skills using Pi's own formatter, so datasource skills
- * sit on the exact same layer as file-backed agent skills.
+ * Render the `<available_skills>` progressive-disclosure block for the
+ * configured datasource skills, in the same format pi uses for file-backed
+ * agent skills, so datasource skills sit on the same layer.
  */
-export declare function buildDatasourceSkillsPrompt(skills: readonly Skill[]): string;
+export declare function buildDatasourceSkillsPrompt(skills: readonly DatasourceAgentSkill[]): string;
 /**
- * Format the full instructions for a loaded datasource skill, matching Pi's
+ * Format the full instructions for a loaded datasource skill, matching pi's
  * `<skill …>` invocation shape but with a path-opaque location (no real
  * filesystem reference, so no "references are relative to …" line).
  */
-export declare function formatDatasourceSkillInvocation(skill: Skill): string;
+export declare function formatDatasourceSkillInvocation(skill: DatasourceAgentSkill): string;
 export interface LoadDatasourceSkillDetails {
     readonly skill: string;
     readonly loaded: boolean;
 }
 export interface DatasourceSkillProvider {
     /**
-     * Resolve an authorized datasource skill by model-visible name. Returns
-     * `undefined` when the name is unknown or not authorized by the trusted,
-     * server-bound access context (default-deny).
+     * Resolve a configured datasource skill by model-visible name. Returns
+     * `undefined` when the name is unknown or not configured.
      */
-    loadDatasourceSkill(name: string): Skill | undefined;
+    loadDatasourceSkill(name: string): DatasourceAgentSkill | undefined;
 }
 declare const loadDatasourceSkillSchema: Type.TObject<{
     name: Type.TString;

package/dist/agent/emit-results-tool.d.ts

@@ -1,7 +1,35 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
+import type { EvidenceLedger } from "./evidence-ledger.js";
 export declare const EMIT_AUTORAG_RESULTS_TOOL_NAME = "emit_autorag_results";
+/**
+ * Model-facing schema of `emit_autorag_results`. The model cites evidence by
+ * the short ids retrieval tools print next to each result (`refs`); the
+ * harness resolves them to the recorded source, method, and chunk, so the
+ * model never retypes a path or a chunk.
+ */
 export declare const emitResultsSchema: Type.TObject<{
+    answer: Type.TString;
+    results: Type.TArray<Type.TObject<{
+        number: Type.TInteger;
+        title: Type.TString;
+        summary: Type.TString;
+        evidence: Type.TArray<Type.TObject<{
+            excerpt: Type.TString;
+            lineNumber: Type.TOptional<Type.TInteger>;
+        }>>;
+        confidence: Type.TNumber;
+        refs: Type.TArray<Type.TString>;
+    }>>;
+    warnings: Type.TOptional<Type.TArray<Type.TString>>;
+}>;
+/**
+ * Report schema with the explicit number -> source mapping. This is the
+ * persisted/typed shape and the input contract of `autorag report` and the MCP
+ * report tool, where an external agent curated the evidence and no harness
+ * ledger exists.
+ */
+export declare const reportSchema: Type.TObject<{
     answer: Type.TString;
     results: Type.TArray<Type.TObject<{
         number: Type.TInteger;
@@ -79,10 +107,17 @@ export interface AutoRAGResultsDetails {
     readonly mapping: readonly AutoRAGMappingEntry[];
     readonly warnings: readonly string[];
 }
+export interface EmitResultsToolOptions {
+    /** Evidence the run's retrieval tools returned; `refs` resolve against it. */
+    readonly ledger: EvidenceLedger;
+    /** False in remote sessions: only evidence a tool returned this run may be cited. */
+    readonly allowLocalFiles: boolean;
+}
 /**
  * Builds the terminating structured-result tool. The model calls this exactly
  * once as its final action; the typed `details` plus `terminate: true` end the
  * Pi Agent run and hand the curated results back through `capture` — no
- * assistant-text parsing involved.
+ * assistant-text parsing involved. The number -> source mapping is built here
+ * from the harness-held evidence the model cited by id, never from model text.
  */
-export declare function createEmitResultsTool(capture: (details: AutoRAGResultsDetails) => void): AgentTool<typeof emitResultsSchema, AutoRAGResultsDetails>;
+export declare function createEmitResultsTool(capture: (details: AutoRAGResultsDetails) => void, options: EmitResultsToolOptions): AgentTool<typeof emitResultsSchema, AutoRAGResultsDetails>;

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,7 @@ 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";

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, type ExtensionFactory, type ToolDefinition } 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;

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

@@ -1,12 +1,17 @@
 import type { JevJudge } from "./jev-extension.js";
 /**
  * Where a user question is answered from:
- * - `local`: information only the user can reach (their files, chats, mail).
- * - `web`: public information one internet search would answer.
- * - `direct`: general knowledge or small talk the model answers on its own.
+ * - `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" | "web" | "direct";
-/** Jev question id of the three-way branch. */
+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";
@@ -18,6 +23,19 @@ export declare const FALLBACK_QUERY_ROUTE: QueryRoute;
 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;
@@ -34,21 +52,64 @@ export interface FollowUpDecision {
  */
 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. */
+    /** 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 chosen branch, when it reported a distribution. */
+    /** 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, or an unusable verdict falls back to a single local
- * search, with the reason recorded.
+ * 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 routeQuery(judge: JevJudge, query: string): Promise<QueryRouteDecision>;
+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" | "query-routed" | "query-route-fallback" | "query-decomposition-failed" | "follow-up-skipped" | "follow-up-check-fallback" | "citation-without-result";
+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[]): boolean;
 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 {};