@autorag/librarian 2.7.0 → 2.8.0

package/NOTICE

@@ -18,6 +18,9 @@ License: MIT
 @earendil-works/pi-tui@0.86.1
 License: MIT
 
+@modelcontextprotocol/server@2.3.0
+License: Apache-2.0
+
 @openrouter/sdk@1.4.21
 License: Apache-2.0
 
@@ -30,6 +33,9 @@ License: MIT
 iconv-lite@0.7.3
 License: MIT
 
+jev-use@0.8.0
+License: MIT
+
 jszip@3.10.1
 License: (MIT OR GPL-3.0-or-later)
 

package/README.md

@@ -80,6 +80,8 @@ AutoRAG uses `@earendil-works/pi-coding-agent` as the runtime host for model ses
 
 The CLI TUI (`autorag tui`) is Pi's interactive mode hosted on the AutoRAG librarian: there is no separate AutoRAG renderer. Pi owns the terminal UI and its native in-session commands — `/login`/`/logout`, `/model`, `/resume`, `/new`, `/tree`, `/compact`, and `/settings` — so provider sign-in and model selection work on first launch even when no AutoRAG model is configured. AutoRAG registers its retrieval tools and streams progress, preliminary answers, and final results into the same Pi session, so resume and two-phase search keep working together.
 
+Update notices are AutoRAG's, not Pi's: `autorag tui` suppresses Pi's "run `pi update`" banner (Pi is a bundled host, not a separate install) and instead checks the published `@autorag/librarian` release, showing a one-line notice in the session when a newer version exists. Set `AUTORAG_NO_UPDATE_CHECK=1` to skip the lookup; `AUTORAG_UPDATE_CHECK_URL` overrides the registry endpoint.
+
 
 ---
 
@@ -89,19 +91,20 @@ If you are an AI coding agent or LLM (Claude Code, Cursor, Windsurf, Codex, Senp
 
 | Skill | Directory | When to Use |
 |---|---|---|
-| **`autorag`** | [`skills/autorag/`](skills/autorag/SKILL.md) | Querying, searching, comparing, and summarizing documents with an already configured AutoRAG librarian. |
-| **`autorag-setup`** | [`skills/autorag-setup/`](skills/autorag-setup/SKILL.md) | Installing AutoRAG, configuring models, adding document roots/datasources, running health checks, and repairing indexes. |
-| **`autorag-lite-setup`** | [`skills/autorag-lite-setup/`](skills/autorag-lite-setup/SKILL.md) | Initializing and maintaining the model-free AutoRAG Lite lifecycle without an LLM. |
-| **`autorag-lite-search`** | [`skills/autorag-lite-search/`](skills/autorag-lite-search/SKILL.md) | Performing model-free retrieval, reporting evidence, and recording feedback without an LLM. |
+| **`autorag`** | [`skills/autorag/`](skills/autorag/SKILL.md) | Model-backed querying, searching, comparing, and summarizing with an already configured AutoRAG librarian. |
+| **`autorag-setup`** | [`skills/autorag-setup/`](skills/autorag-setup/SKILL.md) | Installing AutoRAG, configuring the model-backed librarian, adding roots/datasources, running health checks, and registering Lite MCP when needed. |
+| **`autorag-lite-setup`** | [`skills/autorag-lite-setup/`](skills/autorag-lite-setup/SKILL.md) | Installing/registering `autorag-mcp`, initializing model-free config, maintaining indexes, and verifying MCP search. |
 
 ### Install the skills into your coding agent
 
-Skills are not auto-discovered — copy the folders you want into the agent's skill directory. For **Claude Code** that directory is `.claude/skills/` in the project (or `~/.claude/skills/` to enable them everywhere). Once `autorag-lite-setup` and `autorag-lite-search` are in place, Claude Code drives `autorag lite retrieve` as a search tool:
+Skills are not auto-discovered — copy only the setup skill when an agent needs
+to bootstrap AutoRAG. **Routine AutoRAG Lite retrieval is provided by MCP
+tools, not by a `autorag-lite-search` skill or shell command.**
 
 ```bash
 # From a clone of this repository
 mkdir -p .claude/skills
-cp -R skills/autorag-lite-setup skills/autorag-lite-search .claude/skills/
+cp -R skills/autorag-lite-setup .claude/skills/
 ```
 
 ```bash
@@ -109,10 +112,19 @@ cp -R skills/autorag-lite-setup skills/autorag-lite-search .claude/skills/
 AUTORAG_SKILLS="$(npm root -g)/@autorag/librarian/skills"
 # Bun global installs live at ~/.bun/install/global/node_modules/@autorag/librarian/skills
 mkdir -p .claude/skills
-cp -R "$AUTORAG_SKILLS/autorag-lite-setup" "$AUTORAG_SKILLS/autorag-lite-search" .claude/skills/
+cp -R "$AUTORAG_SKILLS/autorag-lite-setup" .claude/skills/
 ```
 
-Copy `skills/autorag` and `skills/autorag-setup` the same way when the agent should also drive the model-backed librarian, and `skills/autorag-doctor` for diagnostics. Other agents read their own directories (for example `~/.agents/skills/`) — copy the same folders there and reload the agent session so it picks them up.
+Run the setup skill once to register the stdio server with the host. Reload the
+agent, then discover the actual tool names and schemas with MCP `tools/list`.
+The normal Lite path is `autorag.status` → `autorag.refresh` when needed →
+`autorag.search`; use `autorag.report`, `autorag.evidence`, and
+`autorag.feedback` for the optional curation lifecycle. Copy `skills/autorag`
+and `skills/autorag-setup` only when the agent should also drive the
+model-backed librarian, and `skills/autorag-doctor` for diagnostics. Other
+agents read their own skill directories; copy the same setup folder there and
+reload the agent session so it picks up the MCP registration instructions.
+Do not copy or retain the removed `autorag-lite-search` skill.
 
 ### Quick Agent Workflow
 
@@ -136,6 +148,29 @@ Copy `skills/autorag` and `skills/autorag-setup` the same way when the agent sho
 
 ---
 
+## AutoRAG Lite MCP Server
+
+Register the package's stdio server with the host; the host owns the process
+lifecycle and sends MCP tool calls:
+
+```bash
+AUTORAG_CONFIG=/absolute/path/to/.autorag/config.json autorag-mcp
+```
+
+For Claude Code and Codex registration commands, use
+[`skills/autorag-lite-setup/SKILL.md`](skills/autorag-lite-setup/SKILL.md).
+The MCP contract source of truth is [`src/mcp/server.ts`](src/mcp/server.ts)
+(tool registration, schemas, handlers) plus [`src/mcp/index.ts`](src/mcp/index.ts)
+(stdio entrypoint). Discover tools and schemas with MCP `tools/list`; do not
+hard-code a tool count.
+
+Core Lite tools include `autorag.status`, `autorag.search`,
+`autorag.search.files`, `autorag.datasources.list`, `autorag.datasources.get`,
+`autorag.refresh`, `autorag.report`, `autorag.evidence`, and
+`autorag.feedback`. Configured integrated datasources expose additional scoped
+search tools. Read-only MCP mode omits mutating tools such as refresh, report,
+and feedback.
+
 ## ⚡ AutoRAG Lite: Model-Free Retrieval Engine
 
 Need blazing fast local search without configuring an LLM or paying for API tokens? Use **AutoRAG Lite**.
@@ -143,8 +178,8 @@ Need blazing fast local search without configuring an LLM or paying for API toke
 AutoRAG Lite provides the exact same high-performance indexing, BM25 ranking, and local MinSync vector/hybrid retrieval engine as the full librarian, but **runs 100% model-free**:
 
 - **Zero LLM Token Usage:** Run purely local BM25 and vector search offline.
-- **Agent Integration Ready:** Use `autorag lite retrieve` inside your own agentic workflows to supply raw context chunks to an external model.
-- **Fast Local CLI:** Instant responses directly from your terminal.
+- **Agent Integration Ready:** Use the AutoRAG Lite MCP server to supply raw context chunks to an external model; the CLI remains a bootstrap and maintenance interface.
+- **Fast Local CLI:** The CLI remains available for terminal-only indexing and repair.
 
 ```bash
 # Initialize a model-free workspace
@@ -152,14 +187,12 @@ autorag lite init --search-paths ./documents
 
 # Index local files and datasources
 autorag lite refresh
-
-# Retrieve ranked document chunks (returns JSON candidates with scores)
-autorag lite retrieve "compliance policy exception process" --top-k 5 --json
-
-# Check index status and freshness
-autorag lite status
 ```
 
+Normal Lite retrieval runs through the MCP tools (`autorag.status`,
+`autorag.search`); the CLI remains the bootstrap and maintenance interface for
+indexing and repair.
+
 ---
 
 ## 🔌 Supported Datasources
@@ -179,6 +212,7 @@ AutoRAG Agent connects to external tools and communication platforms using dedic
 | **Local Mail Export**| `mail-export` | Built-in `.mbox` / `.eml` parser | Local filesystem mailboxes | Lexical |
 | **Obsidian Vaults** | `obsidian` | [`qmd`](https://github.com/tobi/qmd) CLI | Direct markdown vault indexing | BM25, Semantic |
 | **GitHub** | `github` | GitHub REST API | In-memory fetched Issues and Pull Requests | Lexical, Scoped |
+| **GitHub Gists** | `github-gist` | GitHub REST API | Incremental local index of own-account public and permitted secret Gist content/metadata; token not stored | Lexical (BM25), Local Semantic, Scoped |
 | **Cloud Drives** | `cloud-drive` | [`rclone`](https://rclone.org) CLI | Google Drive (Tier-1), OneDrive, Dropbox, etc. | Incremental Mirror + BM25 |
 | **Photos & Shots** | `clawgallery` | `clawgallery` CLI | Local screenshot and photo store | Hybrid OCR/Visual Search |
 | **RSS / News** | `rss` | Native HTTP Poller | RSS 2.0 & Atom feeds (24h deduplication) | Lexical |
@@ -295,11 +329,12 @@ agent.recordFeedbackByNumbers(response.sessionId, [1], [2]);
 | `autorag status` | Inspect corpus freshness, indexing status, and vector readiness |
 | `autorag health` | Check model provider authentication, token validity, and API reachability |
 | `autorag models list` | List chat models the pi runtime can resolve (built-ins, `models.json`, custom/extension providers) with provider auth status; never prints credential values |
+| `autorag update-check` | Compare the running `autorag` against the published npm version (also runs on `autorag tui` launch) |
 | `autorag tui` | Open Pi's interactive librarian TUI (`/login`, `/model`, `/resume`, …) |
 | `autorag duplicates [DIR]` | Read-only scan for exact and near-duplicate document families with `dupey` |
-| `autorag lite ...` | Model-free indexing, retrieval, report generation, and status |
-| `autorag feedback <session>` | Record useful / not-useful feedback by item number |
-| `autorag evidence <session>` | Inspect exact underlying document chunks and sources for a past query |
+| `autorag lite ...` | CLI bootstrap, indexing repair, terminal maintenance, and fallback interface; agents use MCP for normal Lite operation |
+| `autorag feedback <session>` | Record numbered feedback; MCP clients normally use `autorag.feedback`, and the CLI stays available for terminal maintenance |
+| `autorag evidence <session>` | Inspect persisted evidence behind numbered results; MCP clients normally use `autorag.evidence`, and the CLI stays available for terminal maintenance |
 | `autorag serve` | Start the P2P query server over SimpleX (opt-in) |
 | `autorag p2p ...` | Manage peer trust, query approvals, and sharing policies |
 
@@ -312,6 +347,7 @@ Deep dive into AutoRAG Agent's architecture, security, and integration guides:
 - **[MinSync Setup & Embedding QA](docs/minsync-setup.md):** Automatic binary installation, CDC chunking, and EmbeddingGemma verification.
 - **[Local Embedding Runtime & Gateway](docs/embedding-runtime.md):** AutoRAG-owned local gateway, model prefetching, and zero-egress semantic search. Model cards: [`qwen3-embedding-0.6b`](docs/model-cards/qwen3-embedding-0.6b.md), [`embeddinggemma-300m`](docs/model-cards/embeddinggemma-300m.md).
 - **[Datasource Skills Reference](docs/datasource-skills.md):** Full configuration contracts, connection aliases, and connector options.
+- **[Jev Decisions](docs/jev-decisions.md):** Jev query pipeline, **on by default** via OpenRouter: it routes each question to local search, web search, or a direct answer, splits multi-part questions into up to five parallel searches (`openrouter/qwen/qwen3.7-flash`), and ends the run after the fast answer when that answer is complete. Also covers the `jev` judgment tool, backends (OpenRouter, TypeSafe, Vercel AI Gateway), and how to opt out.
 - **[Manual QA & Datasource Test Harnesses](docs/manual-qa-datasources.md):** Real-world testing guides for Discord, KakaoTalk, Slack, Notion, and email.
 - **[P2P SimpleX Sharing & Path Standard](docs/p2p-path-standard.md):** Decentralized peer query sharing with SimpleX, PII redaction, and approval queues.
 - **[Supply Chain Security & License Audits](docs/supply-chain.md):** Software bill of materials (SBOM) and dependency gate policies.
@@ -357,13 +393,19 @@ autorag health --json          # model resolution + one live completion probe
 autorag gateway status --format json   # on-demand embedding runtime
 ```
 
-Indexing is not the same thing as searchability, so always confirm retrieval itself — this needs no model:
+Indexing is not the same thing as searchability, so always confirm retrieval
+itself through the connected Lite MCP server:
 
-```bash
-autorag lite retrieve 'a word that certainly appears' --top-k 3 --json
-autorag lite retrieve 'recent topic' --tags discord --top-k 3 --json
+```text
+autorag.status {}
+autorag.refresh {}
+autorag.search {"query":"a word that certainly appears","topK":3}
+autorag.search {"query":"recent topic","tags":["discord"],"topK":3}
 ```
 
+The CLI equivalents remain available for terminal repair, but do not use them
+as the agent's normal Lite search path.
+
 Common failures and their fix:
 
 | Symptom | Diagnostic code | Fix |
@@ -375,6 +417,7 @@ Common failures and their fix:
 | A datasource errors during refresh | `datasource-index-failed` | run that CLI's own `doctor` |
 | MinSync or Jikji missing | `minsync-unavailable`, `jikji-unavailable` | check the Rust toolchain, re-run refresh |
 | Windows file-name search fails during refresh | `everything-index-failed` | read the ES exit code and stderr in the message, then `autorag refresh --method everything --json` |
+| Every search does a full local search and verification, even for small talk | `query-route-fallback` | set `OPENROUTER_API_KEY` (Jev routing and decomposition are on by default) |
 
 Native datasource stores stay owned by their CLIs — AutoRAG never rebuilds them. Fix a broken archive with `lazykatok doctor`, `discrawl --json metadata`, `slacrawl --json doctor`, `wacrawl --json doctor`, `telecrawl --json doctor`, `notcrawl doctor`, `qmd status`, or `mailcrawl doctor`, then re-run `autorag refresh --method datasources --json`.
 

package/dist/agent/agent.d.ts

@@ -17,11 +17,14 @@ 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 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 WatcherFactory, type WatchRefreshHandle } from "./watch-refresh.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". */
@@ -233,6 +234,29 @@ 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 needs local search, web search, or a
+     * direct answer, 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;
+    /**
+     * 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[];
     /**
@@ -256,14 +280,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 {
@@ -320,15 +350,11 @@ export declare class AutoRAGAgent {
     private modelNativeSearchAuth;
     private retrievalTrace;
     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;
@@ -352,6 +378,15 @@ export declare class AutoRAGAgent {
     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;
+    private readonly queryDecompositionModel;
+    /** Web search routing for the pipeline's web branch; 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,6 +396,7 @@ export declare class AutoRAGAgent {
     private readonly piAgentDir;
     private readonly piSessionDir;
     private readonly persistPiSessions;
+    private readonly updateNotice;
     private boundPiRuntime;
     /** True when this agent was constructed for an untrusted remote peer. */
     readonly remoteSession: boolean;
@@ -416,6 +452,23 @@ export declare class AutoRAGAgent {
      * 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.
+     */
+    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).
+     */
+    private authorizedSourceScopes;
     /**
      * Resolve an authorized datasource agent skill by model-visible name for the
      * `load_datasource_skill` tool. Returns `undefined` for unknown or
@@ -425,20 +478,53 @@ export declare class AutoRAGAgent {
     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
+     * (local search, web search, or a direct answer) 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.
+     */
+    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.
+     */
     private prefetchInitialRetrievalContext;
+    /** Baseline web evidence for the fast answer: one web search per query, all in parallel. */
+    private prefetchWebContext;
     /**
-     * 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 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.
      */
-    /** 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;
     /**
@@ -447,7 +533,7 @@ export declare class AutoRAGAgent {
      * against it; the model then verifies with thinking on and finalizes with
      * emit_autorag_results exactly once, returning only the delta.
      */
-    buildRefinementPrompt(query: string, options: RetrievalOptions, fastAnswer: AutoRAGFastAnswerDetails | undefined, fastAnswerDelivered: boolean): string;
+    buildRefinementPrompt(query: string, options: RetrievalOptions, fastAnswer: AutoRAGFastAnswerDetails | undefined, fastAnswerDelivered: boolean, route?: QueryRoute): string;
     buildSearchPrompt(query: string, options: RetrievalOptions, initialRetrievalContext?: string): string;
     refresh(force?: boolean, opts?: AutoRAGRefreshOptions): Promise<AutoRAGRefreshResult>;
     /**
@@ -504,13 +590,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 +613,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;
     /**

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,20 @@
+/** 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 `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/index.d.ts

@@ -4,6 +4,7 @@ export { buildDatasourceSkillsPrompt, createLoadDatasourceSkillTool, type Dataso
 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 { createSearchAllDocumentsTool, SEARCH_ALL_DOCUMENTS_TOOL_NAME, type SearchAllDocumentsDetails, type SearchAllDocumentsProvider, type SearchAllDocumentsResult, } from "./search-all-tool.js";

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

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

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

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