@autorag/librarian 2.8.0 → 2.10.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,54 @@
+import type { RetrievalResult } from "../retrieval/types.js";
+import type { AutoRAGEvidenceRef } from "./results.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 LookupEvidenceOptions {
+    /** False in remote sessions: only evidence a tool returned this run may be cited. */
+    readonly allowLocalFiles: boolean;
+}
+export declare function isRegularFile(path: string): 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 one cited reference 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. Returns an empty list when nothing matches: the caller drops the
+     * citation instead of failing the run.
+     */
+    lookup(raw: string, options: LookupEvidenceOptions): AutoRAGEvidenceRef[];
+    /** Forget every recorded entry. Ids are never reissued, so a previous run's id stays unresolvable. */
+    clear(): void;
+}

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/index.d.ts

@@ -2,11 +2,11 @@ export type { AutoRAGAgentOptions, AutoRefreshOptions, PeerQueryOptions } from "
 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 { 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 type { AutoRAGEmittedResult, AutoRAGMappingEntry, AutoRAGResultsDetails, } from "./results.js";
+export { reportSchema } from "./results.js";
 export { createSearchAllDocumentsTool, SEARCH_ALL_DOCUMENTS_TOOL_NAME, type SearchAllDocumentsDetails, type SearchAllDocumentsProvider, type SearchAllDocumentsResult, } from "./search-all-tool.js";
 export type { SearchDocumentDiagnostic, SearchDocumentDiagnosticCode, SearchDocumentDiagnosticSeverity, SearchDocumentEvidence, SearchDocumentResult, SearchDocumentsResponse, SearchDocumentsStreamEvent, SearchDocumentWarning, } from "./search-documents.js";
 export { createSearchMinSyncDocumentsTool, SEARCH_MINSYNC_DOCUMENTS_TOOL_NAME, type SearchMinSyncDocumentsDetails, } from "./search-minsync-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/{emit-results-tool.d.ts → results.d.ts}

@@ -1,7 +1,13 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
-export declare const EMIT_AUTORAG_RESULTS_TOOL_NAME = "emit_autorag_results";
-export declare const emitResultsSchema: Type.TObject<{
+/**
+ * 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. The librarian itself never produces this shape from the
+ * model: it writes a plain answer and the harness derives the results from the
+ * evidence ids the answer cites.
+ */
+export declare const reportSchema: Type.TObject<{
     answer: Type.TString;
     results: Type.TArray<Type.TObject<{
         number: Type.TInteger;
@@ -47,7 +53,8 @@ export interface AutoRAGEmittedResult {
     readonly title: string;
     readonly summary: string;
     readonly evidence: readonly AutoRAGEmittedEvidence[];
-    readonly confidence: number;
+    /** Absent for results the harness derived from cited evidence: nothing measured a confidence. */
+    readonly confidence?: number;
 }
 export interface AutoRAGEvidenceRef {
     readonly method: string;
@@ -79,10 +86,3 @@ export interface AutoRAGResultsDetails {
     readonly mapping: readonly AutoRAGMappingEntry[];
     readonly warnings: readonly string[];
 }
-/**
- * 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.
- */
-export declare function createEmitResultsTool(capture: (details: AutoRAGResultsDetails) => void): AgentTool<typeof emitResultsSchema, AutoRAGResultsDetails>;

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

@@ -1,7 +1,6 @@
-import { type RetrievalMemory } from "../memory/memory.js";
-import type { CuratedResult, RetrievalResult } from "../retrieval/types.js";
-import type { AutoRAGResultsDetails } from "./emit-results-tool.js";
-import type { AutoRAGFastAnswerDetails } from "./fast-answer-tool.js";
+import { type RetrievalMemory, type SessionEvidenceRef } from "../memory/memory.js";
+import type { RetrievalResult } from "../retrieval/types.js";
+import type { AutoRAGMappingEntry, AutoRAGResultsDetails } from "./results.js";
 export type SearchDocumentWarning = "empty-query";
 export type SearchDocumentDiagnosticSeverity = "info" | "warning" | "error";
 /**
@@ -10,7 +9,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" | "no-final-answer" | "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;
@@ -27,8 +26,8 @@ export interface SearchDocumentResult {
     readonly title: string;
     readonly summary: string;
     readonly evidence: readonly SearchDocumentEvidence[];
-    readonly confidence: number;
-    readonly feedbackId: string;
+    /** Absent when nothing measured one: derived results carry no model-reported confidence. */
+    readonly confidence?: number;
     readonly source?: string;
 }
 /** One retrieval candidate captured in a run's retrieval trace. */
@@ -39,7 +38,7 @@ export interface SearchDocumentRetrievalTraceResult {
 }
 /**
  * What one retrieval tool execution found during a search run. Attached to the
- * degraded fallback response when the agent never called emit_autorag_results,
+ * degraded fallback response when the agent never wrote a final answer,
  * so an upstream agent can still inspect the raw candidates.
  */
 export interface SearchDocumentRetrievalTraceEntry {
@@ -85,27 +84,15 @@ export type SearchDocumentsStreamEvent = {
     readonly type: "complete";
     readonly response: SearchDocumentsResponse;
 };
-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.
+ * {@link recordStructuredResultsSession} this NEVER touches memory — the final
+ * response owns that.
  */
-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?: {
+export declare function createPreliminarySearchDocumentsResponse(sessionId: string, query: string, details: AutoRAGResultsDetails, diagnostics?: readonly SearchDocumentDiagnostic[]): SearchDocumentsResponse;
+export declare function createEmptySearchDocumentsResponse(sessionId: string, query: string, diagnostics?: readonly SearchDocumentDiagnostic[]): SearchDocumentsResponse;
+export declare function normalizeEntryEvidenceRefs(entry: AutoRAGMappingEntry): SessionEvidenceRef[];
+export declare function recordStructuredResultsSession(sessionId: string, query: string, details: AutoRAGResultsDetails, memory: RetrievalMemory, componentDiagnostics?: readonly SearchDocumentDiagnostic[], options?: {
+    /** Skip 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 {};

package/dist/agent/search-single-datasource-tool.d.ts

@@ -1,11 +1,12 @@
 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";
 /**
  * Per-datasource search tools.
  *
- * One tool is generated per authorized datasource connection (e.g.
+ * One tool is generated per configured datasource connection (e.g.
  * `search_datasource_discord`, or `search_datasource_kakao_work` for a
  * `kakao-work` account alias). Its execution registers only that connection's
  * retrieval methods with the retriever, so no other datasource CLI is spawned
@@ -14,13 +15,13 @@ import { type SearchDocumentRetrievalTraceResult } from "./search-documents.js";
  * These generated tools are the only model-facing datasource retrieval
  * surface. Cross-datasource fan-out belongs to `search_all_documents`, which
  * already spans every configured retrieval method — including datasources — so
- * a datasource-only fan-out tool would be redundant. Every authorized
+ * a datasource-only fan-out tool would be redundant. Every configured
  * connection must therefore appear here; a datasource with no generated tool
  * would become unreachable except through the full fan-out.
  *
- * Tools are generated from the configured, access-authorized datasource skills
- * at agent construction, so a datasource that is disabled in config or denied
- * by the trusted access context never appears in the tool list.
+ * Tools are generated from the configured datasource skills at agent
+ * construction; a connection not present in the config never appears in the
+ * tool list.
  */
 export declare const SEARCH_SINGLE_DATASOURCE_TOOL_PREFIX = "search_datasource_";
 /** Model-visible tool name for one datasource connection. */
@@ -31,7 +32,7 @@ export interface SingleDatasourceToolSpec {
     readonly datasourceId: string;
     /** Operator/descriptor-authored context shown in the tool description. */
     readonly description: string;
-    /** Authorized instance roots (e.g. `/kakao/personal`) for the description. */
+    /** Instance roots (e.g. `/kakao/personal`) for the description. */
     readonly instanceScopes: readonly string[];
 }
 export interface SingleDatasourceSearchProvider {
@@ -52,12 +53,12 @@ export interface SearchSingleDatasourceDetails {
     /** Top candidates in traceable shape (additive; used for the run's retrieval trace). */
     readonly results?: readonly SearchDocumentRetrievalTraceResult[];
 }
-export declare function createSingleDatasourceSearchTools(provider: SingleDatasourceSearchProvider, specs: readonly SingleDatasourceToolSpec[]): AgentTool<typeof searchSingleDatasourceSchema, SearchSingleDatasourceDetails>[];
+export declare function createSingleDatasourceSearchTools(provider: SingleDatasourceSearchProvider, specs: readonly SingleDatasourceToolSpec[], ledger?: EvidenceLedger): AgentTool<typeof searchSingleDatasourceSchema, SearchSingleDatasourceDetails>[];
 declare const searchSingleDatasourceSchema: Type.TObject<{
     query: Type.TString;
     topK: Type.TOptional<Type.TInteger>;
     scope: Type.TOptional<Type.TString>;
 }>;
 /** Shared rendering for datasource search tool results (fan-out removed). */
-export declare function formatDatasourceResults(results: readonly RetrievalResult[], diagnostics: readonly RetrievalDiagnostic[]): string;
+export declare function formatDatasourceResults(results: readonly RetrievalResult[], diagnostics: readonly RetrievalDiagnostic[], evidenceIds: readonly string[]): string;
 export {};

package/dist/agent/self-config.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Host opt-in for agent self-configuration: the Jev `config` branch, where the
+ * agent edits its own settings with the full `autorag-setup` skill in hand.
+ */
+export interface SelfConfigOptions {
+    /** The active AutoRAG config file the agent may read and edit. */
+    readonly configPath: string;
+    /** Override for the `autorag-setup` SKILL.md; defaults to the packaged skill. */
+    readonly skillPath?: string;
+    /**
+     * Check the config file after a config turn changed it. Resolves to a
+     * problem description when the file no longer works, or `undefined` when it
+     * is fine. A reported problem restores the pre-turn file.
+     */
+    readonly validate?: (configPath: string) => Promise<string | undefined>;
+}
+/** Full text of the `autorag-setup` skill with its YAML front matter removed. */
+export declare function loadSetupSkill(skillPath?: string): string;
+export interface SelfConfigPromptInput {
+    readonly query: string;
+    readonly configPath: string;
+    readonly agentDir: string;
+    readonly skill: string;
+}
+/** The config file's current text, or `undefined` when it does not exist. */
+export declare function snapshotConfigFile(configPath: string): string | undefined;
+/**
+ * After a config turn: when the model changed the file and the host's
+ * `validate` says the result no longer works, put the pre-turn text back.
+ * Returns the problem that triggered the rollback, or `undefined` when the
+ * file is unchanged, valid, or the host supplied no validator. An unchanged
+ * file is never touched, even if it was already invalid before the turn.
+ */
+export declare function rollbackIfBroken(options: SelfConfigOptions, before: string | undefined): Promise<string | undefined>;
+/**
+ * The turn prompt for the `config` branch: the whole setup skill, where this
+ * run's config lives, the safety rules for editing it, and the user's request.
+ * The turn ends with the model's plain final message; there is no fast answer.
+ */
+export declare function buildSelfConfigPrompt(input: SelfConfigPromptInput): string;

package/dist/agent/system-prompt.d.ts

@@ -1,13 +1,12 @@
-import type { Skill } from "@earendil-works/pi-agent-core";
 import type { StoreManifest } from "../manifest/types.js";
+import type { DatasourceAgentSkill } from "./datasource-skill.js";
 export interface SystemPromptConfig {
     toolNames: string[];
     modelId?: string;
-    memorySignalCount?: number;
     memoryEntries?: readonly unknown[];
     manifests: StoreManifest[];
     jikjiIndexingEnabled?: boolean;
-    datasourceSkills?: readonly Skill[];
+    datasourceSkills?: readonly DatasourceAgentSkill[];
     retrievedContentGuard?: boolean;
     remoteSession?: boolean;
 }