@autorag/librarian 2.4.2 → 2.5.1

package/NOTICE

@@ -0,0 +1,68 @@
+AutoRAG
+Copyright (c) 2025 NomaDamas / Marker Inc.
+
+Root package license: MIT
+legacy/ package license: Apache-2.0
+
+Third-party production dependencies:
+
+@earendil-works/pi-agent-core@0.85.1
+License: MIT
+
+@earendil-works/pi-ai@0.85.1
+License: MIT
+
+@earendil-works/pi-coding-agent@0.85.1
+License: MIT
+
+@earendil-works/pi-tui@0.85.1
+License: MIT
+
+@opendataloader/pdf@2.5.7
+License: Apache-2.0
+
+@rhwp/core@0.8.6
+License: MIT
+
+chardet@2.2.0
+License: MIT
+
+fast-xml-parser@5.11.1
+License: MIT
+
+iconv-lite@0.7.3
+License: MIT
+
+jszip@3.10.1
+License: (MIT OR GPL-3.0-or-later)
+
+mailparser@3.9.20
+License: MIT
+
+slides-grab@1.5.1
+License: MIT
+
+smol-toml@1.8.0
+License: BSD-3-Clause
+
+tesseract.js@7.0.0
+License: Apache-2.0
+
+typebox@1.3.25
+License: MIT
+
+xlsx@0.18.5
+License: Apache-2.0
+
+yaml@2.9.0
+License: ISC
+
+Embedding runtime and model notices:
+licenses/llama.cpp-MIT.txt
+licenses/qwen3-embedding-notice.txt
+licenses/apache-2.0.txt
+licenses/gemma-notice.txt
+licenses/gemma-section-3.2-flow-down.txt
+licenses/gemma-terms-of-use.txt
+licenses/gemma-terms-of-use.html
+licenses/embedding-assets.json

package/README.md

@@ -24,7 +24,7 @@ Three principles drive every design decision:
    stores (katok, discrawl, qmd, msgvault, rclone, …) in place. No forced
    ingestion into a central index, no third-party server holding a copy of
    your corpus. Results carry source-native identities
-   (`kakao:<chat>/<sender>/<chunk>`) with scope-checked access — see the
+   (`/kakao/<instance>/chunks/<chunk>`) with scope-checked access — see the
    [competitive landscape study](docs/competitive-landscape-2026-09.md) for
    why this is the durable differentiator.
 2. **Just works — no RAG degree required.** Install it and it works: minimal
@@ -200,7 +200,7 @@ Datasource skills let AutoRAG search external, server-configured data sources th
 
 Every datasource can be registered multiple times through a connection alias:
 use the config key as the unique name and set `type` to the reusable backend
-(`gmail`, `github`, `slack`, `discord`, `kakao`, `cloud-drive`, and so on).
+(`mailcrawl`, `github`, `slack`, `discord`, `kakao`, `cloud-drive`, and so on).
 Each alias becomes an independently loadable agent skill with its own source
 scope and workspace namespace. Chat aliases search all channels by default;
 trusted `channels.ids` / `channels.names` allowlists can expose a particular
@@ -224,11 +224,12 @@ Security defaults are intentionally strict:
 | Notion | `notion` | external [`notcrawl`](https://github.com/openclaw/notcrawl) CLI | local-first page/database/block archive + FTS5 search |
 | GitHub Issues/PRs | `github` | GitHub REST (token optional) | issues + PR bodies per `owner/repo`; public repos work unauthenticated |
 | Cloud drives | `cloud-drive` | **[`rclone`](https://rclone.org) CLI** | Incremental Google Drive Tier-1; OneDrive/network remotes; iCloud experimental |
-| Gmail | `gmail` | Gmail REST v1 | OAuth access token is referenced by environment variable name |
 | Local mail exports | `mail-export` | filesystem (`.mbox` / `.eml`) | classic `From_` splitting, mailparser-based; count-only warnings |
 | Mail archives | `mailcrawl` | external [`mailcrawl`](https://github.com/NomaDamas/mailcrawl) CLI | local email sync plus BM25, semantic, and hybrid retrieval |
 | Obsidian vault | `obsidian` | external [`qmd`](https://github.com/tobi/qmd) CLI | incremental `qmd update`, BM25 `qmd search`, semantic `qmd vsearch`; vault path via `connector.vaultPath` |
 | RSS / news | `rss` | HTTP feed polling | RSS 2.0 + Atom, feed/category hierarchy, 24h dedupe window |
+| ClawGallery | `clawgallery` | external `clawgallery` CLI (`cargo install clawgallery`) | local screenshots and photos; incremental bootstrap + hybrid search |
+| macOS Spotlight | `spotlight` | built-in `mdfind` | macOS only; no extra install; Full Disk Access for protected files |
 
 Connector-backed skills fetch documents into AutoRAG's local chunk store. External-crawler skills such as KakaoTalk, WhatsApp, Telegram, Slack, and Notion leave incremental archive and FTS ownership with their CLI and map query results into the same retrieval pipeline. Obsidian uses the external `qmd` CLI (incremental update + BM25 + semantic). Tokens are referenced by environment variable name only, never stored in config. Process/API failures surface as path/PII-opaque diagnostics. See [docs/manual-qa-datasources.md](docs/manual-qa-datasources.md) for the QA harnesses.
 
@@ -242,7 +243,6 @@ Configure them in `config.json` (CLI) or pass `datasourceSkills` programmaticall
     "slack":    { "connector": { "binaryPath": "slacrawl", "configPath": "/path/to/slacrawl.yaml", "syncSource": "primary" } },
     "notion":   { "connector": { "binaryPath": "notcrawl", "configPath": "/path/to/notcrawl.yaml" } },
     "github":   { "connector": { "repos": ["owner/repo"] } },
-    "gmail":    { "connector": { "tokenEnv": "GMAIL_ACCESS_TOKEN", "labelIds": ["INBOX"] } },
     "mailcrawl": { "instanceId": "personal", "connector": { "account": "personal", "mailbox": "INBOX", "binaryPath": "mailcrawl" } },
     "personal-google-drive": { "type": "cloud-drive", "instanceId": "personal", "connector": { "provider": "google-drive", "remote": "personal-gdrive:", "include": ["**/*.md"] } },
     "company-onedrive": { "type": "cloud-drive", "instanceId": "work", "connector": { "provider": "onedrive", "remote": "company-onedrive:Documents" } },
@@ -250,8 +250,8 @@ Configure them in `config.json` (CLI) or pass `datasourceSkills` programmaticall
     "rss":      { "connector": { "feeds": [{ "url": "https://example.com/feed.xml" }] } }
   },
   "datasourceAccess": {
-    "allowedTags": ["whatsapp", "telegram", "slack", "notion", "github", "gmail", "mailcrawl", "cloud-drive", "obsidian", "rss"],
-    "allowedScopes": ["/whatsapp/**", "/telegram/**", "/slack/**", "/notion/**", "/github/**", "/gmail/**", "/mailcrawl/**", "/personal-google-drive/**", "/company-onedrive/**", "/obsidian/**", "/rss/**"]
+    "allowedTags": ["whatsapp", "telegram", "slack", "notion", "github", "mailcrawl", "cloud-drive", "obsidian", "rss"],
+    "allowedScopes": ["/whatsapp/**", "/telegram/**", "/slack/**", "/notion/**", "/github/**", "/mailcrawl/**", "/personal-google-drive/**", "/company-onedrive/**", "/obsidian/**", "/rss/**"]
   }
 }
 ```
@@ -262,19 +262,18 @@ Install telecrawl with `brew install openclaw/tap/telecrawl`. AutoRAG invokes `t
 
 Install slacrawl with `brew install openclaw/tap/slacrawl`. AutoRAG invokes `slacrawl sync` during datasource refresh and `slacrawl --json search` during retrieval. Optional trusted connector fields are `binaryPath`, `configPath`, and `syncSource`. Slack credentials and source definitions remain in slacrawl's own configuration rather than AutoRAG.
 
-Install notcrawl with `brew install openclaw/tap/notcrawl`. AutoRAG invokes `notcrawl sync` during datasource refresh and `notcrawl search --json` during retrieval. Optional trusted connector fields are `binaryPath` and `configPath`. Notion credentials and workspace definitions remain in notcrawl's own configuration rather than AutoRAG.
+Install notcrawl with `brew install openclaw/tap/notcrawl`. AutoRAG invokes `notcrawl sync` during datasource refresh and `notcrawl search` during retrieval (notcrawl has no `--json` flag through v0.6.2; AutoRAG parses its tab-separated hits). Optional trusted connector fields are `binaryPath` and `configPath`. Notion credentials and workspace definitions remain in notcrawl's own configuration rather than AutoRAG.
 
 Install and configure [`mailcrawl`](https://github.com/NomaDamas/mailcrawl)
-`@nomadamas/mailcrawl@0.1.4` or newer separately. AutoRAG invokes
+`@nomadamas/mailcrawl@0.1.6` or newer separately (0.1.4 is the minimum). AutoRAG invokes
 `mailcrawl sync` followed by `mailcrawl index` during datasource refresh, then
 calls `mailcrawl search` in BM25, semantic, or hybrid mode. The archive remains
 in mailcrawl's native store unless the operator explicitly sets
 `connector.dataDir`; Himalaya credentials and provider configuration remain
 owned by mailcrawl. 0.1.3 and earlier fail a repeated
 `index` after a no-op sync.
-Use `mailcrawl` for all Himalaya-backed IMAP/Maildir retrieval. The retired
-`gmail` connector option `backend: "himalaya"` is no longer registered; migrate
-that configuration to an explicit `mailcrawl` datasource.
+Use `mailcrawl` for Gmail, IMAP, and Maildir retrieval. The former Gmail REST
+datasource and `gmail` + `backend: "himalaya"` connector are removed.
 
 Install and authenticate rclone separately (`brew install rclone && rclone
 config` on macOS), then configure the provider-neutral `cloud-drive` skill.
@@ -324,13 +323,13 @@ Discord uses the external [`discrawl`](https://github.com/openclaw/discrawl) CLI
 brew install openclaw/tap/discrawl
 ```
 
-Two archive sources are supported. `wiretap` (the default) reads the local Discord Desktop cache and needs **no token at all**; `discord` uses a bot token, which is the ToS-sanctioned automation path. AutoRAG refuses to spawn the CLI when a Discord *user* token is present in the environment — automating a user account violates Discord's Community Guidelines and can get the account terminated.
+AutoRAG reads discrawl's own local archive: `discrawl wiretap` imports the Discord Desktop cache and needs **no token at all**, and every search, embed, and sync step runs against that native store. AutoRAG carries no Discord credential — no bot token, no credential env var, no credential check in `autorag setup` — and it refuses to spawn the CLI when a Discord *user* token is present in the environment, because automating a user account violates Discord's Community Guidelines and can get the account terminated. A bot-backed archive is the CLI's own concern: configure and sync it with `discrawl` itself.
 
 ```typescript
 import { AutoRAGAgent, DiscrawlClient, DiscrawlSkill } from "@autorag/librarian";
 
 const discord = new DiscrawlSkill({
-  client: new DiscrawlClient({ source: "wiretap", root: process.cwd() }),
+  client: new DiscrawlClient({ root: process.cwd() }),
   instanceId: "community",
 });
 
@@ -351,7 +350,6 @@ Or through the trusted config factory:
     "discord": {
       "instanceId": "community",
       "connector": {
-        "source": "wiretap",
         "embeddingProvider": "ollama",
         "embeddingModel": "embeddinggemma",
         "defaultMode": "hybrid"
@@ -412,7 +410,9 @@ Config path precedence is `--config` > `AUTORAG_CONFIG` > `~/.autorag/config.jso
 
 `memory.json` stores retrieval memory and `logs/runs.jsonl` records run events. Model authentication remains with the user's configured provider or authenticated local runtime. Corpus indexes remain workspace-local: refresh keeps parsed mirrors and BM25/MinSync indexes under `<workspace>/.autorag`.
 
-`autorag refresh` and `autorag index reset|rebuild` accept `--method <csv>` (e.g. `--method bm25,minsync,parsed`) to scope which indexing methods run or which index directories are removed. When omitted, all methods run. `autorag init` accepts `--embedder-*` flags to configure the MinSync embedder endpoint in the config file.
+`autorag refresh` and `autorag index reset|rebuild` accept `--method <csv>` (e.g. `--method minsync,parsed` or `--method datasources,jikji`) to scope which indexing methods run or which index directories are removed. Valid values are `parsed`, `minsync`, `datasources`, `jikji`, and `all`. BM25 is a MinSync retrieval mode, not a `--method` name. When omitted, all methods run. `autorag init` accepts `--embedder-*` flags to configure the MinSync embedder endpoint in the config file.
+
+`autorag refresh --json` reports the MinSync outcome in a `minsync` block (`ok`, `synced`, and a `reason`/`diagnostics` on failure), and the envelope's `ok` is `false` whenever MinSync, a datasource index, or any error-severity diagnostic failed — a green envelope never hides a semantic index that did not update.
 
 `autorag health` checks model/provider auth before a search — it resolves the model, verifies credential presence, and optionally probes one completion call. Use it to diagnose model, provider, auth, or timeout failures. `autorag status` remains the model-free index-health command (corpus freshness and BM25/MinSync readiness). When `autorag search` fails for a model/provider reason, the error output includes a hint pointing to `autorag health`.
 
@@ -440,6 +440,61 @@ characters. Local use remains the safe default: omit `ui` (or leave
 `allowRemote` false) and AutoRAG binds to loopback, including a working
 `localhost` URL on systems that resolve it to IPv6.
 
+### CLI commands
+
+```bash
+autorag init                    # write ~/.autorag/config.json
+autorag refresh                 # parsed + MinSync + datasources + Jikji
+autorag watch [--once]          # filesystem watch, or one cron/poll tick
+autorag status                  # corpus freshness (model-free)
+autorag search "your question"  # curated answer (requires a configured model)
+autorag feedback <session>      # numbered useful / not-useful feedback
+autorag evidence <session>      # persisted source/chunk evidence
+autorag memory inspect          # retrieval memory snapshot
+autorag index reset|rebuild     # remove or rebuild workspace indexes
+autorag health                  # model/provider auth (no index check)
+autorag duplicates [DIR]        # read-only duplicate families; never deletes
+autorag tui                     # interactive librarian terminal UI (beta)
+autorag ui                      # loopback page to connect datasources
+autorag lite …                  # model-free setup, retrieve, report, status
+autorag setup                   # install and configure local runtime assets
+autorag models prefetch|import|verify
+                                # manage local embedding model profiles
+autorag gateway status|stop     # inspect or stop the local embedding gateway
+autorag serve                   # P2P peer query server over SimpleX (opt-in)
+autorag p2p                     # peer trust, approvals, and sharing policy
+```
+
+`autorag --help` is the command list of record; `autorag <command> --help`
+prints that command's flags and subcommands, and `autorag --version` prints the
+installed version. See
+[docs/embedding-runtime.md](docs/embedding-runtime.md) for the local embedding
+runtime and gateway setup.
+
+### P2P sharing (SimpleX)
+
+Peer query sharing is **disabled by default**. Set `p2p.enabled` to `true` in
+`config.json`, or pass `--force` to start the server once. Peers reach this
+installation through SimpleX; the local control socket binds to loopback
+(default port 5225).
+
+```bash
+autorag serve                          # start the peer query server
+autorag p2p peers                      # list trusted peers
+autorag p2p peers --add alice --contact-id 1
+autorag p2p requests                   # pending responses held for approval
+autorag p2p requests approve <id>
+autorag p2p policy list                # merged sharing rules (virtual-path keys)
+autorag p2p policy set '/docs/**' peers
+autorag p2p policy unset '/docs/**'
+```
+
+Inbound queries are screened for injection. Outbound answers are filtered by
+sharing policy (`private` / `never` / `always` / `peers`) and PII redaction,
+and held until the operator approves them. The librarian can call
+`recommend_peer_targets` to suggest local peer personas without contacting
+them.
+
 ## Installation
 
 Published as `@autorag/librarian` (dist bundled with Bun, runtime Node ≥ 24 or Bun):
@@ -448,7 +503,7 @@ Published as `@autorag/librarian` (dist bundled with Bun, runtime Node ≥ 24 or
 bun add @autorag/librarian          # library
 bun install -g @autorag/librarian   # autorag CLI
 # or run directly from the repo:
-bun add github:NomaDamas/AutoRAG-2.0
+bun add github:Marker-Inc-Korea/AutoRAG
 ```
 
 PDF parsing requires **Java 11 or newer** because the bundled
@@ -467,28 +522,18 @@ start a new shell). Java 8 is not supported by the PDF parser.
 Git-based installs build `dist/` via the `prepare` script and require Bun on the installing machine.
 External tool binaries auto-install on first use into `<workspace>/.autorag/bin`: **MinSync** installs from crates.io via `cargo install minsync` first (on by default; verified GitHub release assets are the fallback when cargo is unavailable; `minSync.autoInstall: false` to opt out), and **Jikji** compiles the [`jikji-cli`](https://crates.io/crates/jikji-cli) crate via cargo (requires the [Rust toolchain](https://rustup.rs); `jikji.autoInstall: false` to opt out). New `autorag init` configs enable Jikji find-first discovery by default. KakaoTalk (`katok`) and Discord (`discrawl`) stay manual, optional installs. All of them degrade gracefully when missing — core BM25 search works without any of them.
 
-### Experimental TUI (beta)
+### TUI (beta)
 
-The latest TUI work is currently available on the `feat/experimental-tui`
-branch. To use this beta version from source:
+`autorag tui` opens an interactive Pi-powered librarian terminal UI using the
+same config as `autorag search`:
 
 ```bash
-git clone --branch feat/experimental-tui https://github.com/Marker-Inc-Korea/AutoRAG.git
-cd AutoRAG
-bun install
-bun run build
-
-# Configure your document roots and model once:
-node dist/cli/index.js init --search-paths /path/to/documents
-
-# Start the beta TUI:
-node dist/cli/index.js tui
+autorag tui
 ```
 
 Inside the TUI, use `/resume` to browse saved sessions. Selecting a session
 replaces the current view with that session instead of mixing the two
-conversation histories. This branch is experimental and may change before the
-feature is included in a published release.
+conversation histories. The TUI is beta and may still change.
 
 ## Quick Start
 
@@ -543,4 +588,4 @@ agent.recordFeedbackByNumbers(response.sessionId, [1, 3], [2]);
 
 ## License
 
-MIT
+MIT for AutoRAG 2.0 (`LICENSE`). The legacy Python package in `legacy/` is Apache-2.0 (`legacy/LICENSE`). Production third-party licenses are listed in `NOTICE`. Supply-chain gates are documented in `docs/supply-chain.md`.

package/dist/agent/agent.d.ts

@@ -7,6 +7,7 @@ import { type JikjiFailureReason, type JikjiOptions } from "../jikji/index.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";
 import type { DefaultParserRegistryOptions } from "../parser/index.js";
 import { RetrievalEngine } from "../retrieval/engine.js";
 import { RetrievalMethodRegistry } from "../retrieval/registry.js";
@@ -29,6 +30,9 @@ export interface AutoRAGMinSyncRefreshResult {
     readonly ok: boolean;
     readonly synced: number;
     readonly reason?: string;
+    /** Count of parsed documents excluded from the MinSync index by file name. */
+    readonly stagingExcludedCount?: number;
+    readonly diagnostics?: readonly SearchDocumentDiagnostic[];
 }
 export interface AutoRAGRefreshResult extends Omit<ParsedMirrorSyncResult, "diagnostics"> {
     readonly diagnostics: readonly SearchDocumentDiagnostic[];
@@ -66,6 +70,39 @@ export interface AutoRAGWatchRefreshOptions {
     readonly watcherFactory?: WatcherFactory;
 }
 export type AutoRAGWatchRefreshHandle = WatchRefreshHandle;
+declare module "../retrieval/types.js" {
+    interface RetrievalOptions {
+        /** Server-only P2P policy identity; never included in model tool schemas. */
+        peerFingerprint?: string;
+        /** Server-only P2P policy resolver. */
+        resolvePolicy?: PolicyResolver;
+        /** Server-only run registry populated from observed retrieval output. */
+        observedSources?: Set<string>;
+        /** Server-only datasource source globs derived from the loaded policy. */
+        policyDatasourceScopes?: readonly string[];
+    }
+}
+export type RemoteSessionRejectionCode = "injection-detected" | "outbound-leak-detected";
+export declare class RemoteSessionRejectedError extends Error {
+    readonly code: RemoteSessionRejectionCode;
+    constructor(code: RemoteSessionRejectionCode);
+}
+/** 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.
+ */
+export interface AutoRAGThinkingOptions {
+    /** Thinking level for the immediate first answer. Default "off". */
+    readonly fast?: AutoRAGThinkingLevel;
+    /** Thinking level for the verification/finalization phase. Default "high". */
+    readonly final?: AutoRAGThinkingLevel;
+}
 export interface AutoRAGAgentOptions {
     model?: Model<Api>;
     apiKey?: string;
@@ -89,6 +126,10 @@ export interface AutoRAGAgentOptions {
     searchTimeoutMs?: number;
     /** Maximum number of retrieval/tool executions allowed in one search. */
     maxSearchToolCalls?: number;
+    /** 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;
 }
 export interface AutoRAGSearchSession {
     readonly agent: Agent;
@@ -121,6 +162,11 @@ export declare class AutoRAGAgent {
     private readonly sessions;
     private activeRun;
     private resultCapture;
+    private retrievalTrace;
+    private preliminaryCallback;
+    /** Per-phase thinking levels; undefined marks the legacy single-phase flow. */
+    private readonly fastThinkingLevel;
+    private readonly finalThinkingLevel;
     private autoRefreshTimer;
     private refreshing;
     private jikjiPrepareInFlight;
@@ -150,6 +196,9 @@ export declare class AutoRAGAgent {
     private readonly droppedCallerToolNames;
     private readonly searchTimeoutMs;
     private readonly maxSearchToolCalls;
+    /** True when this agent was constructed for an untrusted remote peer. */
+    readonly remoteSession: boolean;
+    private activeRetrievalOptions;
     private searchToolCallCount;
     private readonly sourceSearchCallCounts;
     constructor(options: AutoRAGAgentOptions);
@@ -210,14 +259,36 @@ export declare class AutoRAGAgent {
     /** Prepare MinSync in the background; the returned promise is for tests. */
     scheduleMinSyncPrepareForTest(): Promise<MinSyncSyncResult | undefined> | undefined;
     private scheduleMinSyncPrepare;
+    /**
+     * 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;
+    /**
+     * Verification-phase prompt for two-phase searches. The user already saw
+     * the fast answer; the model now verifies it against sources with thinking
+     * on and finalizes with emit_autorag_results exactly once.
+     */
+    buildRefinementPrompt(query: string, options: RetrievalOptions, fastAnswer: string | undefined): string;
     buildSearchPrompt(query: string, options: RetrievalOptions, initialRetrievalContext?: string): string;
     refresh(force?: boolean, opts?: AutoRAGRefreshOptions): Promise<AutoRAGRefreshResult>;
     /**
      * Path-opaque snapshot of corpus freshness and the last refresh outcome. Runs
      * a cheap parse-free staleness scan (stat only); never parses in this path.
+     *
+     * Freshness is read from disk, not from this instance's history: a separate CLI
+     * process (for example `autorag status` or `autorag lite status`) reports the
+     * corpus as current when the last refresh left parsed mirrors behind and no
+     * source has changed since.
      */
     getRefreshStatus(): Promise<AutoRAGRefreshStatus>;
-    private refreshComponentStatus;
+    /**
+     * Synchronous per-component readiness snapshot (minsync/jikji/datasources).
+     * `minsync` is "ready" only after a successful sync wrote its cursor;
+     * "configured" means the binary resolved but no index exists yet.
+     */
+    refreshComponentStatus(): AutoRAGRefreshComponentStatus;
     /**
      * Opt-in filesystem watch that keeps parsed mirrors and configured indexes
      * current. Debounced, backpressure-limited (one in-flight refresh plus one
@@ -315,6 +386,7 @@ export declare class AutoRAGAgent {
     getRetrievalEngine(): RetrievalEngine;
     getSystemPrompt(): string;
     private rerankWithMemory;
+    private remoteFilteredRetrievalMethod;
     private normalizeRetrievalOptions;
     private resolveRetrievalScope;
 }

package/dist/agent/fast-answer-tool.d.ts

@@ -0,0 +1,46 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+export declare const EMIT_FAST_ANSWER_TOOL_NAME = "emit_fast_answer";
+declare const fastAnswerSchema: Type.TObject<{
+    answer: Type.TString;
+    results: Type.TArray<Type.TObject<{
+        number: Type.TInteger;
+        title: Type.TString;
+        summary: Type.TString;
+        evidence: Type.TOptional<Type.TArray<Type.TObject<{
+            excerpt: Type.TString;
+            lineNumber: Type.TOptional<Type.TInteger>;
+        }>>>;
+        confidence: Type.TOptional<Type.TNumber>;
+    }>>;
+    sources: Type.TOptional<Type.TArray<Type.TObject<{
+        number: Type.TInteger;
+        source: Type.TString;
+    }>>>;
+}>;
+export interface AutoRAGFastAnswerResult {
+    readonly number: number;
+    readonly title: string;
+    readonly summary: string;
+    readonly evidence: readonly {
+        readonly excerpt: string;
+        readonly lineNumber?: number;
+    }[];
+    readonly confidence?: number;
+}
+export interface AutoRAGFastAnswerDetails {
+    readonly answer: string;
+    readonly results: readonly AutoRAGFastAnswerResult[];
+    readonly sources: readonly {
+        readonly number: number;
+        readonly source: string;
+    }[];
+}
+/**
+ * Builds the non-terminating fast-answer tool used by the two-phase search
+ * flow. The model calls this exactly once during the thinking-off fast phase
+ * to deliver an immediate, complete first answer; the run then continues into
+ * the verification phase, which ends with emit_autorag_results.
+ */
+export declare function createEmitFastAnswerTool(capture: (details: AutoRAGFastAnswerDetails) => void): AgentTool<typeof fastAnswerSchema, AutoRAGFastAnswerDetails>;
+export {};

package/dist/agent/peer-target-tool.d.ts

@@ -0,0 +1,19 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+export declare const RECOMMEND_PEER_TARGETS_TOOL_NAME = "recommend_peer_targets";
+declare const recommendPeerTargetsSchema: Type.TObject<{
+    query: Type.TString;
+}>;
+export interface PeerTargetRecommendation {
+    readonly alias: string;
+    readonly matchedTerms: readonly string[];
+    readonly displayName?: string;
+    readonly description?: string;
+}
+export interface RecommendPeerTargetsDetails {
+    readonly method: "recommend_peer_targets";
+    readonly resultCount: number;
+    readonly matches: readonly PeerTargetRecommendation[];
+}
+export declare function createRecommendPeerTargetsTool(workspacePath: string): AgentTool<typeof recommendPeerTargetsSchema, RecommendPeerTargetsDetails>;
+export {};

package/dist/agent/search-all-tool.d.ts

@@ -1,6 +1,7 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
 import type { RetrievalDiagnostic, RetrievalResult } from "../retrieval/types.js";
+import { type SearchDocumentRetrievalTraceResult } from "./search-documents.js";
 export declare const SEARCH_ALL_DOCUMENTS_TOOL_NAME = "search_all_documents";
 declare const searchAllSchema: Type.TObject<{
     query: Type.TString;
@@ -24,6 +25,8 @@ export interface SearchAllDocumentsDetails {
     readonly sources: readonly string[];
     readonly diagnostics: readonly RetrievalDiagnostic[];
     readonly perMethodCounts?: Readonly<Record<string, number>>;
+    /** Top candidates in traceable shape (additive; used for the run's retrieval trace). */
+    readonly results?: readonly SearchDocumentRetrievalTraceResult[];
 }
 /**
  * LLM-facing wrapper around multi-method merged retrieval. The

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

@@ -1,6 +1,7 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
 import type { RetrievalDiagnostic, RetrievalResult } from "../retrieval/types.js";
+import { type SearchDocumentRetrievalTraceResult } from "./search-documents.js";
 export declare const SEARCH_DATASOURCE_DOCUMENTS_TOOL_NAME = "search_datasource_documents";
 declare const searchDatasourceSchema: Type.TObject<{
     query: Type.TString;
@@ -12,6 +13,8 @@ export interface SearchDatasourceDocumentsDetails {
     readonly resultCount: number;
     readonly sources: readonly string[];
     readonly diagnostics: readonly RetrievalDiagnostic[];
+    /** Top candidates in traceable shape (additive; used for the run's retrieval trace). */
+    readonly results?: readonly SearchDocumentRetrievalTraceResult[];
 }
 export interface DatasourceSearchProvider {
     searchDatasourceDocuments(query: string, options?: {

package/dist/agent/search-documents.d.ts

@@ -1,6 +1,7 @@
 import { type RetrievalMemory } from "../memory/memory.js";
-import type { CuratedResult } from "../retrieval/types.js";
+import type { CuratedResult, RetrievalResult } from "../retrieval/types.js";
 import type { AutoRAGResultsDetails } from "./emit-results-tool.js";
+import type { AutoRAGFastAnswerDetails } from "./fast-answer-tool.js";
 export type SearchDocumentWarning = "empty-query";
 export type SearchDocumentDiagnosticSeverity = "info" | "warning" | "error";
 /**
@@ -9,7 +10,7 @@ export type SearchDocumentDiagnosticSeverity = "info" | "warning" | "error";
  * (#21/#22) does not require another source-breaking type change; codes not yet
  * emitted are still valid members.
  */
-export type SearchDocumentDiagnosticCode = "empty-query" | "unknown-warning" | "caller-tool-dropped" | "minsync-unavailable" | "parser-skipped" | "parser-failed" | "pdf-java-version" | "duplicate-excluded" | "unsupported-file" | "stale-index" | "deleted-mirror" | "pdf-extract-thin" | "pdf-hybrid-unavailable" | "retrieval-method-failed" | "jikji-unavailable" | "jikji-prepare-failed" | "jikji-find-failed" | "refresh-failed" | "watch-failed" | "watch-limited" | "unknown-datasource-skill";
+export type SearchDocumentDiagnosticCode = "empty-query" | "no-verified-results" | "unknown-warning" | "caller-tool-dropped" | "minsync-unavailable" | "minsync-staging-excluded" | "minsync-sync-failed" | "embedder-unavailable" | "embedding-identity-mismatch" | "parser-skipped" | "parser-failed" | "pdf-java-version" | "duplicate-excluded" | "unsupported-file" | "stale-index" | "deleted-mirror" | "pdf-extract-thin" | "pdf-hybrid-unavailable" | "retrieval-method-failed" | "jikji-unavailable" | "jikji-prepare-failed" | "jikji-find-failed" | "refresh-failed" | "watch-failed" | "watch-limited" | "unknown-datasource-skill" | "missing-final-emit";
 export interface SearchDocumentDiagnostic {
     readonly code: SearchDocumentDiagnosticCode;
     readonly severity: SearchDocumentDiagnosticSeverity;
@@ -30,6 +31,23 @@ export interface SearchDocumentResult {
     readonly feedbackId: string;
     readonly source?: string;
 }
+/** One retrieval candidate captured in a run's retrieval trace. */
+export interface SearchDocumentRetrievalTraceResult {
+    readonly source?: string;
+    readonly excerpt: string;
+    readonly score?: number;
+}
+/**
+ * What one retrieval tool execution found during a search run. Attached to the
+ * degraded fallback response when the agent never called emit_autorag_results,
+ * so an upstream agent can still inspect the raw candidates.
+ */
+export interface SearchDocumentRetrievalTraceEntry {
+    readonly tool: string;
+    readonly query?: string;
+    readonly resultCount: number;
+    readonly results: readonly SearchDocumentRetrievalTraceResult[];
+}
 export interface SearchDocumentsResponse {
     readonly sessionId: string;
     readonly query: string;
@@ -42,25 +60,52 @@ export interface SearchDocumentsResponse {
      * window, but ALWAYS populated at runtime (defaults to an empty array).
      */
     readonly diagnostics?: readonly SearchDocumentDiagnostic[];
+    /**
+     * Retrieval candidates gathered during the run. Populated on the degraded
+     * fallback path (missing final emit); absent or empty otherwise.
+     */
+    readonly retrievalTrace?: readonly SearchDocumentRetrievalTraceEntry[];
 }
+/** Cap and shape retrieval results for the run trace (additive tool details). */
+export declare function toRetrievalTraceResults(results: readonly RetrievalResult[], limit?: number, excerptChars?: number): readonly SearchDocumentRetrievalTraceResult[];
 export type SearchDocumentsStreamEvent = {
     readonly type: "progress";
     readonly sessionId: string;
     readonly query: string;
     readonly text: string;
+} | {
+    /**
+     * Immediate first answer from the thinking-off fast phase. Always
+     * yielded before `complete` when the two-phase flow produced one; the
+     * `complete` event's response remains the verified final answer.
+     */
+    readonly type: "preliminary";
+    readonly response: SearchDocumentsResponse;
 } | {
     readonly type: "complete";
     readonly response: SearchDocumentsResponse;
 };
-type SearchSessions = Map<string, {
+type SearchSession = {
     query: string;
     registry: Map<number, CuratedResult>;
-}>;
+    transient?: boolean;
+};
+type SearchSessions = Map<string, SearchSession>;
 type ReadonlySearchSessions = ReadonlyMap<string, {
     query: string;
     registry: ReadonlyMap<number, CuratedResult>;
+    transient?: boolean;
 }>;
+/**
+ * Build the preliminary (fast-phase) search response. Unlike
+ * {@link recordStructuredResultsSession} this NEVER touches memory or the
+ * feedback session registry — the final response owns those. Feedback ids are
+ * namespaced with `:preliminary:` so they can never collide with final ids.
+ */
+export declare function createPreliminarySearchDocumentsResponse(sessionId: string, query: string, details: AutoRAGFastAnswerDetails, diagnostics?: readonly SearchDocumentDiagnostic[]): SearchDocumentsResponse;
 export declare function createEmptySearchDocumentsResponse(sessionId: string, query: string, sessions: SearchSessions, diagnostics?: readonly SearchDocumentDiagnostic[]): SearchDocumentsResponse;
-export declare function recordStructuredResultsSession(sessionId: string, query: string, details: AutoRAGResultsDetails, sessions: SearchSessions, memory: RetrievalMemory, componentDiagnostics?: readonly SearchDocumentDiagnostic[]): SearchDocumentsResponse;
+export declare function recordStructuredResultsSession(sessionId: string, query: string, details: AutoRAGResultsDetails, sessions: SearchSessions, memory: RetrievalMemory, componentDiagnostics?: readonly SearchDocumentDiagnostic[], options?: {
+    readonly isolateMemory?: boolean;
+}): SearchDocumentsResponse;
 export declare function recordNumberedFeedback(sessions: ReadonlySearchSessions, memory: RetrievalMemory, sessionId: string, usefulNumbers: readonly number[], notUsefulNumbers: readonly number[]): void;
 export {};

package/dist/agent/search-minsync-tool.d.ts

@@ -1,6 +1,7 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
 import type { MinSyncVectorMethod } from "../minsync/method.js";
+import { type SearchDocumentRetrievalTraceResult } from "./search-documents.js";
 export declare const SEARCH_MINSYNC_DOCUMENTS_TOOL_NAME = "semantic_search_local_docs";
 declare const searchMinSyncSchema: Type.TObject<{
     query: Type.TString;
@@ -12,6 +13,8 @@ export interface SearchMinSyncDocumentsDetails {
     readonly resultCount: number;
     readonly sources: readonly string[];
     readonly available: boolean;
+    /** Top candidates in traceable shape (additive; used for the run's retrieval trace). */
+    readonly results?: readonly SearchDocumentRetrievalTraceResult[];
 }
 /**
  * LLM-facing wrapper around the {@link MinSyncVectorMethod} vector

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

@@ -8,5 +8,6 @@ export interface SystemPromptConfig {
     manifests: StoreManifest[];
     jikjiIndexingEnabled?: boolean;
     datasourceSkills?: readonly Skill[];
+    retrievedContentGuard?: boolean;
 }
 export declare function buildSystemPrompt(config: SystemPromptConfig): string;