@autorag/librarian 2.7.0 → 2.9.0

package/dist/agent/agent.d.ts

@@ -1,13 +1,12 @@
-import type { Agent, AgentTool, Skill } from "@earendil-works/pi-agent-core";
+import type { Agent, AgentTool } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
-import { type DatasourceAccessContextOptions } from "../datasource/access-context.js";
 import type { DatasourceIndexResult, DatasourceSkill } from "../datasource/types.js";
 import { type DupeyCliOptions } from "../dupey/index.js";
+import { type Embedder } from "../embedding-runtime/gateway-embedder.js";
 import { type EverythingClientOptions, type EverythingSearchRequest, type EverythingSearchResult } from "../everything/index.js";
 import { type FSearchClientOptions, type FSearchFailureReason, type FSearchSearchRequest, type FSearchSearchResult } from "../fsearch/index.js";
 import { type JikjiFailureReason, type JikjiOptions } from "../jikji/index.js";
 import { type LanguageTag } from "../language.js";
-import type { ResultFeedback } from "../memory/memory.js";
 import { type MinSyncSyncResult, type MinSyncVectorMethodOptions } from "../minsync/index.js";
 import { type ParsedMirrorSyncResult } from "../mirror/sync.js";
 import type { PolicyResolver } from "../p2p/policy-filter.js";
@@ -17,13 +16,17 @@ import type { PeerQueryResponse } from "../p2p/wire.js";
 import { type DefaultParserRegistryOptions } from "../parser/index.js";
 import { RetrievalEngine } from "../retrieval/engine.js";
 import { RetrievalMethodRegistry } from "../retrieval/registry.js";
+import type { DatasourceCatalogEntry } from "../retrieval/selection.js";
 import type { CuratedResult, RetrievalDiagnostic, RetrievalOptions, RetrievalResult } from "../retrieval/types.js";
+import { type DatasourceAgentSkill } from "./datasource-skill.js";
 import { type ScanDuplicateDocumentsDetails } from "./dupey-tool.js";
 import { type AutoRAGFastAnswerDetails } from "./fast-answer-tool.js";
+import { type JevToolOptions } from "./jev-extension.js";
 import { type JikjiFindProviderResult } from "./jikji-find-tool.js";
 import { type AutoRAGPiInteractiveRuntime, type AutoRAGPiSession } from "./pi-session.js";
 import { type RefreshProgressCounts, type RefreshProgressPhase } from "./refresh-progress.js";
 import { type SearchDocumentDiagnostic, type SearchDocumentsResponse, type SearchDocumentsStreamEvent } from "./search-documents.js";
+import { type SelfConfigOptions } from "./self-config.js";
 import { type WatcherFactory, type WatchRefreshHandle } from "./watch-refresh.js";
 import { type WebFetchToolOptions } from "./web-fetch-tool.js";
 import { type WebSearchToolOptions } from "./web-search-tool.js";
@@ -36,7 +39,7 @@ import { type WebSearchToolOptions } from "./web-search-tool.js";
 export interface AutoRAGRetrievalLimits {
     /** `search_all_documents` merge ceiling when the model omits `topK`. Default 500. */
     readonly mergedEvidenceCeiling?: number;
-    /** `search_datasource_*` merge default when the model omits `topK`. Default 50. */
+    /** `search_datasource_*` merge default when the model omits `topK`. Default 20. */
     readonly singleDatasourceTopK?: number;
     /** MinSync semantic retrieval default `topK`. Default 50. */
     readonly minSyncTopK?: number;
@@ -160,12 +163,10 @@ export declare class RemoteSessionRejectedError extends Error {
 /** Thinking level applied per search phase. "off" requests no reasoning. */
 export type AutoRAGThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 /**
- * Two-phase progressive answers: the fast phase delivers an immediate first
- * answer with {@link AutoRAGThinkingOptions.fast} thinking (default "off"),
- * then the verification phase re-checks and finalizes with
- * {@link AutoRAGThinkingOptions.final} thinking (default "high"). Pass
- * `false` on {@link AutoRAGAgentOptions.thinking} to keep the legacy
- * single-phase flow.
+ * Per-phase thinking for AutoRAG's two-phase search: the fast phase delivers
+ * an immediate first answer with {@link AutoRAGThinkingOptions.fast} thinking
+ * (default "off"), then the verification phase re-checks and finalizes with
+ * {@link AutoRAGThinkingOptions.final} thinking (default "high").
  */
 export interface AutoRAGThinkingOptions {
     /** Thinking level for the immediate first answer. Default "off". */
@@ -189,7 +190,7 @@ export interface AutoRAGAgentOptions {
     memoryPath?: string;
     workspacePath?: string;
     tools?: AgentTool[];
-    minSync?: Omit<MinSyncVectorMethodOptions, "root"> | false;
+    minSync?: Omit<MinSyncVectorMethodOptions, "root">;
     jikji?: JikjiOptions | false;
     /**
      * Windows-only instant file/folder name search through the bundled
@@ -233,6 +234,43 @@ export interface AutoRAGAgentOptions {
     autoRefresh?: AutoRefreshOptions;
     parserOptions?: DefaultParserRegistryOptions;
     dupey?: DupeyCliOptions | false;
+    /**
+     * Jev (TypeSafe's judgment model: typed questions in, calibrated
+     * probabilities out). When set, the two-phase search asks Jev before the
+     * fast answer whether the question is answerable from intrinsic knowledge
+     * (direct answer) or needs local search, and whether to decompose it; after the fast answer, whether
+     * verification is needed. It also exposes the `jev` tool. Always omitted for
+     * remote P2P sessions.
+     *
+     * The CLI config enables this by default on OpenRouter (`buildAgentOptions`
+     * fills it in). On this programmatic option, absent or `false` keeps Jev
+     * off, so library callers never make paid network calls they did not ask for.
+     */
+    jev?: JevToolOptions | false;
+    /**
+     * Embedder used to find similar past questions in memory (semantic half of
+     * the hybrid search). Defaults to the local embedding gateway; `false` keeps
+     * memory search keyword-only.
+     */
+    memoryEmbedder?: Embedder | false;
+    /**
+     * Agent self-configuration. When set (and Jev is on), Jev gains a `config`
+     * branch for questions about AutoRAG's own settings: the turn skips
+     * `emit_fast_answer`, receives the full `autorag-setup` skill, edits
+     * `configPath` with the pi tools, and reports through
+     * `emit_autorag_results`. Always omitted for remote P2P sessions.
+     */
+    selfConfig?: SelfConfigOptions;
+    /**
+     * Question decomposition used by the Jev query pipeline. `model` (with its
+     * `apiKey`) is the LLM that splits one question into at most five search
+     * queries; omitted, the search session's own model decomposes. The CLI
+     * resolves its configured or default model (`openrouter/qwen/qwen3.7-flash`).
+     */
+    queryDecomposition?: {
+        readonly model?: Model<Api>;
+        readonly apiKey?: string;
+    };
     excludeExactDuplicates?: boolean;
     excludePaths?: readonly string[];
     /**
@@ -242,7 +280,6 @@ export interface AutoRAGAgentOptions {
      */
     limits?: AutoRAGRetrievalLimits;
     datasourceSkills?: readonly DatasourceSkill[];
-    datasourceAccess?: DatasourceAccessContextOptions;
     /** Non-fatal diagnostics from config/agent construction (e.g. skipped unknown datasources). */
     startupDiagnostics?: readonly SearchDocumentDiagnostic[];
     /** Maximum time a model/tool search may run before it is aborted. */
@@ -256,14 +293,20 @@ export interface AutoRAGAgentOptions {
     peerQuery?: PeerQueryOptions | false;
     /** Restrict the agent to retrieval and result-emission tools for remote runs. */
     remoteSession?: boolean;
-    /** Two-phase progressive answers with per-phase thinking control. Default enabled. */
-    thinking?: AutoRAGThinkingOptions | false;
+    /** Per-phase thinking levels for the two-phase (fast → verification) search. */
+    thinking?: AutoRAGThinkingOptions;
     /** pi agent directory for auth/models/extensions. Defaults to ~/.pi/agent. */
     piAgentDir?: string;
     /** Optional persistent pi session directory. */
     piSessionDir?: string;
     /** Persist one pi session transcript per AutoRAG search. Defaults true. */
     persistPiSessions?: boolean;
+    /**
+     * Best-effort provider for an interactive-only startup notice (e.g. a newer
+     * AutoRAG release). Resolves to the notice text or `undefined`; never fails
+     * a launch.
+     */
+    updateNotice?: () => Promise<string | undefined>;
 }
 /** Post-merge reranking options. Mirrors the CLI `RerankConfig` (secrets via env). */
 export interface RerankAgentOptions {
@@ -319,16 +362,14 @@ export declare class AutoRAGAgent {
     private interactiveFastAnswerCallback;
     private modelNativeSearchAuth;
     private retrievalTrace;
+    /** Evidence every retrieval tool returned this run; emit tools resolve model-cited ids against it. */
+    private readonly evidenceLedger;
     private preliminaryCallback;
-    /** Per-phase thinking levels; undefined marks the legacy single-phase flow. */
+    /** Per-phase thinking levels of the two-phase search. */
     private readonly fastThinkingLevel;
     private readonly finalThinkingLevel;
     private autoRefreshTimer;
     private refreshing;
-    private jikjiPrepareInFlight;
-    private jikjiReady;
-    private minSyncPrepareInFlight;
-    private minSyncReady;
     private refreshState;
     private readonly searchPaths;
     private readonly configuredSearchPaths;
@@ -341,17 +382,26 @@ export declare class AutoRAGAgent {
     private readonly merger;
     private readonly reranker;
     private readonly rerankTopN;
-    private readonly datasourceFilter;
     private readonly minSyncMethod;
     private readonly jikjiClient;
     private readonly everythingClient;
     private readonly fsearchClient;
     private readonly datasourceSkills;
-    private readonly datasourceAccessOptions;
     private readonly startupDiagnostics;
     private readonly datasourceAgentSkills;
     private readonly parserOptions;
     private readonly dupeyOptions;
+    /** pi extension registering the optional `jev` tool; undefined when disabled. */
+    private readonly jevExtension;
+    /** Jev judge shared by the `jev` tool and the query router; undefined when disabled. */
+    private readonly jevJudge;
+    /** Self-configuration, enabled only with Jev on a local session. */
+    private readonly selfConfig;
+    private readonly queryDecompositionModel;
+    /** Web search options for the agent's `web_search` / `web_fetch` tools; undefined when web tools are off. */
+    private readonly webSearchOptions;
+    /** Routing diagnostics for the in-flight search; reset per run. */
+    private routingDiagnostics;
     private readonly excludeExactDuplicates;
     private readonly excludePaths;
     private readonly baseSystemPromptConfig;
@@ -361,7 +411,19 @@ export declare class AutoRAGAgent {
     private readonly piAgentDir;
     private readonly piSessionDir;
     private readonly persistPiSessions;
+    private readonly updateNotice;
     private boundPiRuntime;
+    /** Embeds past questions for similar-question search; undefined keeps memory search keyword-only. */
+    private readonly memoryEmbedder;
+    private readonly memoryVectorPath;
+    /** Every retrieval result of the in-flight run with the query/method that surfaced it. */
+    private readonly evidenceOrigins;
+    /** Search-tool queries by tool call id, read back when the call ends. */
+    private readonly searchToolQueries;
+    /** Identifies this agent's conversation: everything judged in it is "current" memory. */
+    private readonly conversationId;
+    /** The memory context loaded for the in-flight run; cleared whenever a run starts. */
+    private memoryContextCache;
     /** True when this agent was constructed for an untrusted remote peer. */
     readonly remoteSession: boolean;
     private activeRetrievalOptions;
@@ -369,7 +431,42 @@ export declare class AutoRAGAgent {
     private readonly limits;
     constructor(options: AutoRAGAgentOptions);
     scanDuplicateDocuments(): Promise<ScanDuplicateDocumentsDetails>;
+    /**
+     * Reference memory for the current question: everything judged earlier in
+     * this conversation, up to 25 similar past questions, and matching
+     * long-term insights. Computed once per run (the datasource check and every
+     * model turn share it) so the similar-question search and its embedder call
+     * are not repeated and a fallback is reported once. Remote peers never read it.
+     */
+    private loadMemoryContextFor;
     private withMemoryContext;
+    /**
+     * Where evidence came from, or undefined when this run may not see it.
+     * Datasource chunks carry a virtual path rooted at the skill name
+     * (`/kakao/default/...`), but the model sometimes maps a datasource hit to a
+     * bare chunk id. The evidence method then still names the datasource
+     * (`search_datasource_kakao_work`, `datasource:kakao`, `kakao-work-lexical`):
+     * both sides collapse every non-alphanumeric to `_` exactly like generated
+     * tool names, and a datasource id that appears as a whole token attributes
+     * it; longer ids are checked first so `kakao-work` wins over `kakao`.
+     * Indexed files are absolute paths under a search path; web evidence is a URL.
+     * Memory is global (shared across workspaces and configs), so evidence from
+     * an unconfigured datasource, and evidence with no recognizable origin, is
+     * never attributed.
+     */
+    private evidenceAttribution;
+    /** Options shared by the prompt injection and the `check_memory` tool; rebuilt on every call because datasource configuration follows live settings. */
+    private memoryContextOptions;
+    /** Remember which query and method surfaced each retrieval result, so cited evidence can be traced back. */
+    private rememberEvidenceOrigins;
+    /**
+     * After the final answer: map every cited evidence back to the search query
+     * and method that found it, ask Jev (one batched call, evidence judged in
+     * parallel) whether it really supports the answer sentence it backs, and
+     * keep only what clears the threshold. Remote peers and runs without Jev
+     * store nothing; a failed judgment stores nothing and says why.
+     */
+    private recordJudgedEvidence;
     private resolveSessionModel;
     private createSearchSession;
     private configureSearchSession;
@@ -389,10 +486,6 @@ export declare class AutoRAGAgent {
     }): void;
     stopAutoRefresh(): void;
     private runAutoRefreshTick;
-    submitFeedback(sessionId: string | undefined, satisfied: boolean): void;
-    recordResultFeedback(feedback: ResultFeedback[]): void;
-    recordFeedbackByNumbers(sessionId: string, usefulNumbers: number[], notUsefulNumbers?: number[]): void;
-    recordFeedbackByIds(usefulFeedbackIds: readonly string[], notUsefulFeedbackIds?: readonly string[]): void;
     getResultRegistry(sessionId?: string): ReadonlyMap<number, CuratedResult>;
     searchDocuments(query: string, options?: RetrievalOptions): Promise<SearchDocumentsResponse>;
     /**
@@ -402,45 +495,103 @@ export declare class AutoRAGAgent {
      * stop by calling {@link abort}.
      */
     searchDocumentsStream(query: string, options?: RetrievalOptions): AsyncGenerator<SearchDocumentsStreamEvent, void, void>;
-    private datasourceAccessContext;
     /**
-     * Build the Pi agent-skill list for datasource skills authorized by the
-     * trusted, server-bound access context. Only authorized skills become
-     * model-visible; unauthorized skills are omitted entirely (default-deny).
+     * Build the Pi agent-skill list for every configured datasource skill. All
+     * configured skills are model-visible; a connection is removed from the
+     * model surface by removing it from the config, not by a permission layer.
      */
-    private buildAuthorizedDatasourceSkills;
+    private buildDatasourceAgentSkills;
     /**
      * Per-connection tool specs for the generated `search_datasource_<id>`
-     * tools, built from the same trusted config and access context as
-     * {@link buildAuthorizedDatasourceSkills}. One spec per authorized
-     * datasource skill; duplicate ids collapse to the first registration.
+     * tools, one per configured datasource skill; duplicate ids collapse to the
+     * first registration.
      */
     private singleDatasourceToolSpecs;
     /**
-     * Resolve an authorized datasource agent skill by model-visible name for the
-     * `load_datasource_skill` tool. Returns `undefined` for unknown or
-     * unauthorized names — model/tool input can never widen authorization.
+     * Configured datasource descriptors for catalog/listing surfaces: every
+     * configured datasource is listed — including ones that expose no retrieval
+     * methods — and each entry carries only identity, capability tags, and
+     * source scope strings (never credentials, config paths, or raw instance
+     * metadata). Duplicate datasource ids collapse to the first registration.
      */
-    loadDatasourceSkill(name: string): Skill | undefined;
+    listDatasources(): DatasourceCatalogEntry[];
+    /**
+     * Opaque source scope strings for one datasource. Sources containing a `#`
+     * fragment are invalid and skipped.
+     */
+    private datasourceSourceScopes;
+    /**
+     * Resolve a configured datasource agent skill by model-visible name for the
+     * `load_datasource_skill` tool. Returns `undefined` for unknown names.
+     */
+    loadDatasourceSkill(name: string): DatasourceAgentSkill | undefined;
     private indexDatasources;
     /** Path-opaque component diagnostics for the search response. */
     private collectComponentDiagnostics;
+    /**
+     * Jev check run after emit_fast_answer: does the answer need correction,
+     * clarification, or further research? "No" ends the run with the fast
+     * answer as the final answer. Without Jev, or when the check fails, the run
+     * always continues into verification.
+     */
+    private shouldFollowUp;
+    /**
+     * Jev query pipeline, run before the fast answer. Jev picks the branch
+     * (direct answer or local search) and whether the question
+     * needs decomposition; a "yes" splits it into at most five search queries
+     * with the configured decomposition model (default: the session model). On
+     * the local branch, Jev also judges, per registered datasource, whether it
+     * must be searched (in parallel with decomposition). Without Jev, and on any
+     * routing failure, this is today's single local search for the original
+     * question with no datasource search.
+     */
+    private planQuery;
+    /**
+     * Jev datasource check for the local branch: one `noul` per configured
+     * datasource that has retrieval methods, with where similar past questions
+     * were answered (from retrieval memory) in the state. Returns the ids to
+     * search with every query before the rerank; a failed check searches none.
+     */
+    private selectSearchDatasources;
+    /**
+     * Baseline local evidence for the fast answer. Jikji, MinSync, and every
+     * Jev-selected datasource run for every search query in parallel (MinSync
+     * itself queues per workspace), the per-query hits are interleaved and
+     * deduplicated into one pool, and that pool is reranked against the
+     * original question.
+     */
     private prefetchInitialRetrievalContext;
     /**
-     * Prepare MinSync lazily without holding up the current search. Parsed
-     * mirrors are built first because MinSync stages and indexes those mirrors.
+     * Rerank the pre-fast-answer baseline pool — Jikji answer paths, MinSync
+     * chunks, and Jev-selected datasource chunks — down to the configured
+     * `rerank.topN`. With decomposition the pool merges every search query's
+     * hits (interleaved), capped at the same per-source sizes as a single query
+     * so the rerank request does not grow with the query count. Returns
+     * `undefined` when reranking is disabled/unavailable or the pool is empty,
+     * so the caller keeps the unranked sections; a rerank failure never blocks
+     * the fast answer.
      */
-    /** Prepare MinSync in the background; the returned promise is for tests. */
-    scheduleMinSyncPrepareForTest(): Promise<MinSyncSyncResult | undefined> | undefined;
-    private scheduleMinSyncPrepare;
+    private rerankPrefetchPool;
     /**
      * Fast-phase prompt for two-phase searches. The baseline retrieval context
      * is already gathered, so the model answers immediately with thinking off
      * via emit_fast_answer, without any further tool calls.
      */
     buildFastAnswerPrompt(query: string, options: RetrievalOptions, baseline: string): string;
+    /**
+     * Prompt for a question Jev routed to a direct answer: general knowledge or
+     * small talk. No retrieval ran and no verification phase follows, so the
+     * answer emitted here is final.
+     */
+    buildDirectAnswerPrompt(query: string): string;
     /** Discovery-tool hint naming only the registered discovery tools; empty when none. */
     private discoveryHint;
+    /**
+     * Verification-phase nudge toward the internet. Jev no longer routes to web
+     * search, so the agent decides after the fast answer: when local evidence is
+     * missing, thin, or possibly stale, it searches the web. Empty when web tools are off.
+     */
+    private webFallbackHint;
     /**
      * Verification-phase prompt for two-phase searches. The fast answer, when a
      * consumer already received it, is embedded verbatim so the model can diff
@@ -485,7 +636,7 @@ export declare class AutoRAGAgent {
      */
     private scanMirrorStaleness;
     private exactDuplicateExclusions;
-    syncMinSync(force?: boolean): Promise<MinSyncSyncResult | undefined>;
+    syncMinSync(force?: boolean): Promise<MinSyncSyncResult>;
     /** Provider for the Windows-only everything_search tool. */
     searchEverything(request: EverythingSearchRequest): Promise<EverythingSearchResult>;
     /**
@@ -504,13 +655,13 @@ export declare class AutoRAGAgent {
      */
     stopFsearch(): Promise<void>;
     prepareJikji(): Promise<readonly AutoRAGJikjiPrepareResult[] | undefined>;
-    private executeJikjiPrepare;
     /**
-     * Start Jikji preparation without delaying the current search turn. A
-     * subsequent turn can use the prepared index, while the child process keeps
-     * running after emit_autorag_results has terminated the agent loop.
+     * Build or incrementally update every root's Jikji index. Called only by
+     * refresh/watch (and the explicit `prepareJikji()` API), never by a query:
+     * `jikji prepare` reuses unchanged documents, and roots run in parallel so
+     * one slow root does not serialize the rest.
      */
-    private scheduleJikjiPrepare;
+    private executeJikjiPrepare;
     private sanitizeJikjiPrepareResult;
     /**
      * Provider method for the jikji_find tool. Runs JikjiClient.find over all
@@ -527,6 +678,14 @@ export declare class AutoRAGAgent {
      * Merge per-root answer packs into one. Concatenates answer_paths/candidates
      * preserving per-root order; dedupes by normalized path. Does NOT cross-root
      * rerank when any root has agentShouldNotRerank=true.
+     *
+     * Honours `excludePaths` at the retrieval boundary: Jikji indexes the source
+     * folders directly, bypassing the parsed mirror, so an excluded source still
+     * appears in the on-disk `.jikji_agent_map.md`. Dropping excluded paths here
+     * keeps them out of the agent-facing answer pack (the `jikji_find` tool and
+     * the baseline prefetch) while leaving the shared map artifact complete.
+     * Excluded paths remain reachable through direct file reads, as Jikji never
+     * blocks source verification.
      */
     private mergeAnswerPacks;
     /**
@@ -566,10 +725,9 @@ export declare class AutoRAGAgent {
      * Search one datasource connection only. Only the target connection's
      * retrieval methods are registered with the retriever, so no other
      * datasource CLI is spawned at all and only that connection's hits are
-     * returned. Access is still gated by the trusted datasource context: an
-     * unknown or unauthorized `datasourceId` yields an empty result set.
+     * returned. An unknown `datasourceId` yields an empty result set.
      *
-     * This backs the generated `search_datasource_<id>` tools; every authorized
+     * This backs the generated `search_datasource_<id>` tools; every configured
      * connection has one. Cross-datasource fan-out is
      * {@link searchAllDocuments}, which spans every retrieval method.
      */
@@ -585,7 +743,7 @@ export declare class AutoRAGAgent {
     /**
      * The standalone retrieval engine for this agent's method pipeline.
      * Built on first access using the agent's registered methods and configured
-     * datasource access context. Model-free — no agent state required.
+     * datasource catalog. Model-free — no agent state required.
      */
     private retrievalEngine;
     getRetrievalEngine(): RetrievalEngine;
@@ -596,7 +754,6 @@ export declare class AutoRAGAgent {
      * the merged order is preserved — a reranker outage never hides evidence.
      */
     private applyRerank;
-    private rerankWithMemory;
     private remoteFilteredRetrievalMethod;
     private normalizeRetrievalOptions;
     private resolveRetrievalScope;

package/dist/agent/answer-guidelines.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The single file-path exception to the answer "no file paths" rule
+ * (issue #1790). Every prompt and tool description that shapes `answer` uses
+ * this exact wording so a caller that can render images receives a markdown
+ * image embed whose path is a real result source, while the no-path rule
+ * otherwise still stands.
+ */
+export declare const ANSWER_IMAGE_EMBED_RULE = "**Images**: when a retrieved result is itself an image file (png, jpg, jpeg, gif, webp, svg, bmp, avif, heic, tiff) and showing it answers the question, embed it in `answer` as a markdown image on its own line: `![short description](<absolute source path>)`, followed by its citation, e.g. `![Q3 revenue chart](</data/reports/q3 chart.png>) [2]`. Use only the real source path of a result in `results`/`mapping`. Never invent a path, use relative paths, or embed remote URLs. Apart from these image embeds, the no-file-paths rule stands.";
+/**
+ * Delta (verification) answers must not re-embed an image the first answer
+ * already showed.
+ */
+export declare const ANSWER_IMAGE_DELTA_RULE = "An image already embedded in the first answer must not be embedded again.";
+/**
+ * One numbering space for citations (issue #1788): every `[n]` in `answer`
+ * must be a `results[].number` emitted in the same call. Retrieval candidate
+ * numbers and first-answer unit numbers are never citation numbers.
+ */
+export declare const ANSWER_CITATION_RULE = "**Citation numbers**: every bracketed citation [n] in `answer` must be the `number` of a result you emit in `results` of the same call. Numbers shown in retrieval candidates or in an earlier first answer are NOT citation numbers \u2014 renumber against your own `results`, and add a result for any evidence you cite.";

package/dist/agent/citations.d.ts

@@ -0,0 +1,43 @@
+/** Sorted, de-duplicated citation numbers in `answer` with no matching result. */
+export declare function unresolvedCitations(answer: string, results: readonly {
+    readonly number: number;
+}[]): number[];
+/** Remove citation markers whose number has no matching result. */
+export declare function stripUnresolvedCitations(answer: string, results: readonly {
+    readonly number: number;
+}[]): {
+    readonly answer: string;
+    readonly unresolved: readonly number[];
+};
+export declare function formatCitationList(numbers: readonly number[]): string;
+/**
+ * Throw a corrective error when two results share a number. A repeated number
+ * collapses into one registry entry and one feedback id, so the other result's
+ * evidence would be lost. Emit tools call this at tool time so the model sees
+ * the error and re-emits.
+ */
+export declare function assertUniqueResultNumbers(label: string, results: readonly {
+    readonly number: number;
+}[]): void;
+/**
+ * Throw a corrective error unless `results` and `mapping` carry the same
+ * numbers, exactly one entry each. Duplicates are rejected even when both
+ * sides repeat them: a repeated number collapses into a single registry entry,
+ * so the other entry's evidence would be lost.
+ * Emit tools call this at tool time (issue #1807) so the model sees the error
+ * and re-emits; checking only after the run ended failed the whole search and
+ * discarded an already-delivered answer.
+ */
+export declare function assertResultsMappingOneToOne(label: string, results: readonly {
+    readonly number: number;
+}[], mapping: readonly {
+    readonly number: number;
+}[]): void;
+/**
+ * Throw a corrective error when `answer` cites numbers absent from `results`.
+ * Emit tools surface the message to the model as a tool error so it re-emits
+ * with one consistent numbering.
+ */
+export declare function assertCitationsResolve(label: string, answer: string, results: readonly {
+    readonly number: number;
+}[]): void;

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>;