@autorag/librarian 2.8.0 → 2.10.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";
@@ -18,15 +17,15 @@ 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 { 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 QueryRoute } from "./query-routing.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";
@@ -190,7 +189,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
@@ -237,8 +236,8 @@ export interface AutoRAGAgentOptions {
     /**
      * 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 needs local search, web search, or a
-     * direct answer, and whether to decompose it; after the fast answer, whether
+     * 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.
      *
@@ -247,6 +246,20 @@ export interface AutoRAGAgentOptions {
      * 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 the
+     * fast answer, receives the full `autorag-setup` skill, edits
+     * `configPath` with the pi tools, and reports what it changed as its final
+     * message. 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
@@ -266,7 +279,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. */
@@ -343,12 +355,11 @@ export declare class AutoRAGAgent {
     private readonly runLogger;
     private lastQuery;
     private lastSessionId;
-    private readonly sessions;
     private activeRun;
-    private resultCapture;
-    private interactiveFastAnswerCallback;
     private modelNativeSearchAuth;
     private retrievalTrace;
+    /** Evidence every retrieval tool returned this run; the answer's inline `[eN]` citations resolve against it. */
+    private readonly evidenceLedger;
     private preliminaryCallback;
     /** Per-phase thinking levels of the two-phase search. */
     private readonly fastThinkingLevel;
@@ -367,13 +378,11 @@ 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;
@@ -382,8 +391,10 @@ export declare class AutoRAGAgent {
     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 routing for the pipeline's web branch; undefined when web tools are off. */
+    /** 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;
@@ -398,6 +409,17 @@ export declare class AutoRAGAgent {
     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;
@@ -405,7 +427,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;
@@ -413,6 +470,15 @@ export declare class AutoRAGAgent {
     private currentSystemPromptConfig;
     subscribe(listener: Parameters<Agent["subscribe"]>[0]): () => void;
     createPiInteractiveRuntime(): Promise<AutoRAGPiInteractiveRuntime>;
+    /** Resolve the model's inline `[eN]` citations against this run's evidence and derive the structured results. */
+    private deriveAnswer;
+    /**
+     * Drives one TUI query through the two-phase search. The model's own
+     * assistant messages (progress notes before a tool call, the fast answer,
+     * the final answer) are already recorded and rendered by the bound pi
+     * session, so nothing is re-sent here: a second copy would show every answer
+     * twice and put it in the model's context twice.
+     */
     private runInteractivePiQuery;
     abort(): void;
     /**
@@ -425,61 +491,51 @@ 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>;
     /**
      * Stream bounded progress updates while retaining the stable
-     * {@link searchDocuments} promise API. Progress is sourced from model text
-     * deltas, so callers can render it in a TUI, CLI, or parent agent and can
-     * stop by calling {@link abort}.
+     * {@link searchDocuments} promise API. Progress is the text an assistant
+     * message wrote before calling a tool (`stopReason: "toolUse"`); a message
+     * that ends its turn is an answer, delivered as `preliminary` or
+     * `complete`, never as progress. Callers can render it in a TUI, CLI, or
+     * parent agent and can 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;
     /**
-     * Authorized configured datasource descriptors for catalog/listing surfaces.
-     *
-     * Built from the same trusted, server-bound access context as
-     * {@link buildAuthorizedDatasourceSkills}: only tag-authorized datasources
-     * are listed — including ones that expose no retrieval methods — and each
-     * entry carries only identity, capability tags, and authorized source scope
-     * strings (never credentials, config paths, or raw instance metadata).
-     * Duplicate datasource ids collapse to the first registration.
+     * 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.
      */
     listDatasources(): DatasourceCatalogEntry[];
     /**
-     * Opaque source scope strings for one datasource that the trusted context
-     * authorizes. Datasources without the `scoped` capability expose their
-     * sources unfiltered (they are gated only at the tag level).
+     * Opaque source scope strings for one datasource. Sources containing a `#`
+     * fragment are invalid and skipped.
      */
-    private authorizedSourceScopes;
+    private datasourceSourceScopes;
     /**
-     * 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.
+     * Resolve a configured datasource agent skill by model-visible name for the
+     * `load_datasource_skill` tool. Returns `undefined` for unknown names.
      */
-    loadDatasourceSkill(name: string): Skill | undefined;
+    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,
+     * Jev check run after the 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.
@@ -487,53 +543,68 @@ export declare class AutoRAGAgent {
     private shouldFollowUp;
     /**
      * Jev query pipeline, run before the fast answer. Jev picks the branch
-     * (local search, web search, or a direct answer) and whether the question
+     * (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).
-     * Without Jev, and on any routing failure, this is today's single local
-     * search for the original question.
+     * 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;
     /**
-     * Baseline local evidence for the fast answer. Jikji and MinSync 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.
+     * 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;
-    /** Baseline web evidence for the fast answer: one web search per query, all in parallel. */
-    private prefetchWebContext;
     /**
-     * Rerank the pre-fast-answer baseline pool — Jikji answer paths plus MinSync
-     * 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.
+     * 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.
      */
     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.
+     * is already gathered, so the model answers immediately with thinking off,
+     * as plain text, 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.
+     * reply is the final answer.
      */
     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
-     * against it; the model then verifies with thinking on and finalizes with
-     * emit_autorag_results exactly once, returning only the delta.
+     * against it; the model then verifies with thinking on and ends with the
+     * final answer as a plain reply, returning only the delta.
      */
-    buildRefinementPrompt(query: string, options: RetrievalOptions, fastAnswer: AutoRAGFastAnswerDetails | undefined, fastAnswerDelivered: boolean, route?: QueryRoute): string;
+    buildRefinementPrompt(query: string, options: RetrievalOptions, fastAnswer: string | undefined, fastAnswerDelivered: boolean): string;
     buildSearchPrompt(query: string, options: RetrievalOptions, initialRetrievalContext?: string): string;
     refresh(force?: boolean, opts?: AutoRAGRefreshOptions): Promise<AutoRAGRefreshResult>;
     /**
@@ -571,7 +642,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>;
     /**
@@ -660,10 +731,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.
      */
@@ -679,7 +749,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;
@@ -690,7 +760,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-citations.d.ts

@@ -0,0 +1,22 @@
+import { type EvidenceLedger } from "./evidence-ledger.js";
+import type { AutoRAGResultsDetails } from "./results.js";
+import type { SearchDocumentDiagnostic } from "./search-documents.js";
+export interface DerivedAnswer {
+    readonly details: AutoRAGResultsDetails;
+    readonly diagnostics: readonly SearchDocumentDiagnostic[];
+}
+/**
+ * Turn the model's plain answer into the structured results the rest of the
+ * harness consumes. The model cites with the evidence ids the retrieval tools
+ * printed (`[e3]`, `[e3, e7]`) or `[file:<abs path>]` for a file it opened
+ * itself. Each id is resolved against the run's evidence ledger, so a source,
+ * method, and chunk always come from recorded evidence, never from model text.
+ *
+ * Results are one per cited source, numbered by first appearance, and every
+ * marker in the returned answer is rewritten to its result number (`[1]`).
+ * A marker that matches no evidence, and any numeric marker the model wrote on
+ * its own, is dropped and reported: it can never point at the wrong result.
+ */
+export declare function deriveResultsFromAnswer(text: string, ledger: EvidenceLedger, options: {
+    readonly allowLocalFiles: boolean;
+}): DerivedAnswer;

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

@@ -1,19 +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.
+ * (issue #1790). Every prompt that shapes the answer uses this exact wording so
+ * a caller that can render images receives a markdown image embed whose path is
+ * a real evidence 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.";
+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 the 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>) [e2]`. Use only the real source path of retrieved evidence. 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.
+ * Inline evidence citations. The model writes the id the retrieval tools print
+ * next to each result; the harness resolves it to the recorded source and
+ * renumbers the markers `[1]`, `[2]`, ... in order of first appearance, so the
+ * caller only ever sees numbered citations backed by recorded evidence.
  */
-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.";
+export declare const ANSWER_CITATION_RULE = "**Citations**: cite supporting evidence inline with the evidence id shown next to each retrieved result, in square brackets (e.g. [e3], or [e3][e7] for two). Copy ids exactly; never invent one. For a local file you opened yourself with `bash`, cite `[file:<absolute path>]`. Cite the evidence that backs a sentence at the end of that sentence. Do not cite numbers, paths, or anything else.";

package/dist/agent/citations.d.ts

@@ -1,7 +1,39 @@
-/** Sorted, de-duplicated citation numbers in `answer` with no matching result. */
-export declare function unresolvedCitations(answer: string, results: readonly {
+/**
+ * Bracketed citations in an answer. Two grammars share one scanner:
+ *
+ * - **Final form** `[n]`: a number that must resolve to a `results[].number`
+ *   of the same response (issue #1788).
+ * - **Model form** `[e3]`, `[e3, e7]`, `[file:/abs/path]`: the evidence ids the
+ *   retrieval tools print next to each result, or a local file the model opened
+ *   itself. The harness resolves them against the run's evidence ledger and
+ *   rewrites them into the final form.
+ *
+ * A markdown image target `(<...>)` is skipped verbatim so a bracketed token
+ * inside a real file path is never mistaken for a citation; `[n](...)` is a
+ * markdown link, not a citation.
+ *
+ * `answer` is model- or caller-supplied, so this is a single linear scan rather
+ * than a regex: alternations like `\(<[^>]*>\)` / `[ \t]*\[` backtrack
+ * quadratically on inputs such as repeated `(<` or long whitespace runs.
+ */
+export type AnswerMarker = {
+    readonly kind: "number";
+    readonly start: number;
+    readonly end: number;
     readonly number: number;
-}[]): number[];
+} | {
+    readonly kind: "evidence";
+    readonly start: number;
+    readonly end: number;
+    readonly ids: readonly string[];
+} | {
+    readonly kind: "file";
+    readonly start: number;
+    readonly end: number;
+    readonly path: string;
+};
+/** Every citation marker in `answer`, in order. `isFile` decides which `[file:...]` paths are real. */
+export declare function answerMarkers(answer: string, isFile?: (path: string) => boolean): AnswerMarker[];
 /** Remove citation markers whose number has no matching result. */
 export declare function stripUnresolvedCitations(answer: string, results: readonly {
     readonly number: number;
@@ -11,10 +43,13 @@ export declare function stripUnresolvedCitations(answer: string, results: readon
 };
 export declare function formatCitationList(numbers: readonly number[]): string;
 /**
- * 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.
+ * 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.
  */
-export declare function assertCitationsResolve(label: string, answer: string, results: readonly {
+export declare function assertResultsMappingOneToOne(label: string, results: readonly {
+    readonly number: number;
+}[], mapping: 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;