@autorag/librarian 2.0.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2025 NomaDamas / Marker Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note: The legacy AutoRAG (Python) package located in the `legacy/` directory
+of this repository is licensed separately under the Apache License 2.0.
+See `legacy/LICENSE`.

package/README.md

@@ -0,0 +1,275 @@
+# AutoRAG
+
+**A self-evolving librarian agent for document collections.**
+
+> [!IMPORTANT]
+> **Looking for the original AutoRAG (RAG AutoML / pipeline optimization tool)?**
+> This repository now hosts **AutoRAG 2.0**, a complete reimagining of AutoRAG as a self-evolving librarian agent. The original Python-based AutoRAG — the RAG AutoML tool for automatically finding an optimal RAG pipeline for your data — now lives in the [`legacy/`](legacy/) directory of this repository.
+>
+> **The legacy AutoRAG is NOT abandoned.** It continues to be maintained (bug fixes, dependency updates, and PyPI releases via `pip install AutoRAG`) in maintenance mode. Existing users can keep using it exactly as before — see the [legacy README](legacy/README.md) for its documentation, and file issues in this repository as usual. New feature development is focused on AutoRAG 2.0.
+
+AutoRAG searches your PDFs, wikis, notes, research papers, and knowledge bases — then curates the results into clean, numbered knowledge units. No raw grep dumps. Just answers.
+
+AutoRAG is a customized [Pi](https://github.com/earendil-works/pi-mono) agent — the Pi agent loop configured into a librarian. Searches use a two-tier workflow: a parent orchestrator delegates exploration to explorer agents. The roles and providers are independently configured from the models available in the user's authenticated runtime; AutoRAG does not ship a private provider default.
+
+## Why AutoRAG
+
+### The problem with search tools
+
+Every search tool gives you the same thing: a list of file paths and matching lines. Then *you* have to:
+- Open each file
+- Read the surrounding context
+- Decide what's relevant
+- Synthesize an answer
+- Remember what worked for next time
+
+That's the human doing all the hard work. The tool just points.
+
+### AutoRAG does the hard work
+
+AutoRAG is not a search tool. It's a **librarian** — it searches, reads, thinks, and reports back:
+
+```
+You ask:  "What were the key findings in the Q3 report?"
+
+AutoRAG:
+[1] Revenue grew 23% YoY to $4.2M, driven by enterprise contracts. (pages 3-5)
+[2] Three new risk factors: supply chain, regulatory, talent retention. (pages 12-14)
+[3] Headcount target missed by 12 — engineering hiring bottleneck. (page 8)
+```
+
+No file paths. No line numbers. Just curated knowledge you can act on.
+
+### It gets smarter over time
+
+AutoRAG has a **self-evolving memory system**. Every search teaches it something:
+
+- Which retrieval methods work for which types of queries
+- Which document areas are most productive
+- What the caller found useful (via explicit feedback)
+
+A fresh AutoRAG tries everything. A seasoned one knows exactly where to look. This is not a static configuration — it's learned behavior from real usage.
+
+### Multiple retrieval methods, one interface
+
+Different documents need different search strategies:
+
+| Your documents | Best method | Why |
+|---|---|---|
+| Plain text, config files | grep (pattern matching) | Fast, precise, literal |
+| Research papers, dense prose | Vector search (semantic) | Understands meaning, not just keywords |
+| Legal documents, specifications | BM25 (keyword ranking) | Handles domain terminology well |
+| Mixed collections | Hybrid (vector + BM25) | Combines precision and recall |
+
+AutoRAG supports **pluggable retrieval methods**. It ships with lexical **BM25** and semantic **MinSync** methods wired through the `RetrievalMethodRegistry`, and the architecture is ready for additional vector and hybrid backends. The parent orchestrator owns process-bound retrieval tools and gives bounded seed packs to explorers; explorers use read-only `read`/`grep`/`find`/`ls` tools to inspect the underlying documents. The `ResultMerger` handles cross-method score normalization and deduplication — you get one unified result set regardless of how many methods contributed.
+
+BM25 and MinSync are **enabled by default** — no explicit configuration is needed for standard lexical + semantic retrieval. Both can be disabled by setting `"bm25": false` or `"minSync": false` in the config file. MinSync uses a pre-installed binary (`autoInstall: false`); configure `minSync.embedder` via `autorag init --embedder-*` flags for remote embedding endpoints. AutoRAG never forces TEI or any external embedding service.
+
+### Real directory access
+
+AutoRAG reads configured source directories through delegated explorer tasks. Each explorer is assigned exactly one normalized configured search root as its `cwd`; the top-level `subagent` invocation sets `agentScope: "user"` and `artifacts: false` exactly once for single, `tasks`, `chain`, or `parallel` dispatch, and nested explorer task items omit both fields. Project-local `.pi-subagents` debug artifacts are disabled. Explorers use read-only `read`/`grep`/`find`/`ls`; the parent orchestrator owns retrieval seed tools and must delegate document reading before curating. Curated answers are returned as a structured `SearchDocumentsResponse`; results carry their real source (file path or datasource id) in the internal mapping for feedback and curation. BM25 and MinSync index parsed markdown mirrors under `.autorag`.
+
+Each explorer `task` contains an Assignment V1 block — a sentinel-wrapped JSON body with `originalQuery` (the caller query verbatim), `method` (the selected retrieval path), and `queryVariants` (a nonempty array), followed by canonical role lines requiring `retrievedAt` and temporal metadata:
+
+```text
+<<<AUTORAG_ASSIGNMENT_V1>>>
+{"originalQuery":"<caller query verbatim>","method":"<selected retrieval method>","queryVariants":["<variant 1>","<variant 2>"]}
+<<<END_AUTORAG_ASSIGNMENT_V1>>>
+Required handoff: include retrievedAt.
+Required handoff: include temporal metadata.
+```
+
+A legacy labeled format (`Original query:`, `Selected retrieval method:`, `Query variants:`) is accepted for compatibility. Missing or null top-level `artifacts`, `agentScope`, and leaf `model` fields are safely autofilled before validation; explicit wrong values (`artifacts: true`, `agentScope: "project"`, a non-configured model) remain rejected. There is no single-agent fallback. See [docs/subagent-orchestration.md](docs/subagent-orchestration.md) for the full dispatch contract, templates, anti-examples, and stable coded dispatch errors.
+
+### Optional Jikji discovery and indexing
+
+AutoRAG can opt into [Jikji](https://github.com/NomaDamas/jikji) as a local CLI-backed **find-first discovery and indexing** layer. Jikji is optional: AutoRAG does not vendor it, install it, or register it as a retrieval backend when enabled.
+
+When Jikji is configured, AutoRAG calls `jikji find ROOT "query" --json` via a policy-aware `jikji_find` tool as the first local-discovery action. The tool parses and validates the upstream answer-pack and honors its `handoff_action` (`direct_use` / `jikji_retry` / `raw_fallback_after_retry`), `tool_call_policy` (`stop_after_find`, `forbidden_tools`, `allowed_followups`), and `agent_should_not_rerank`. Explorer `read`/`grep`/`find`/`ls` discovery is the fallback only when the answer-pack permits raw fallback (`raw_fallback_after_retry`, after the required retry) or when Jikji is unavailable/unconfigured. `prepare`/`refresh` remain for indexing only and do not answer queries directly.
+
+Programmatic use:
+
+```typescript
+const agent = new AutoRAGAgent({
+  searchPaths: ["/path/to/documents"],
+  jikji: { binaryPath: "jikji" },
+});
+await agent.prepareJikji();
+```
+
+The same `.autorag/jikji.json` shape configures Jikji when present:
+
+```json
+{
+  "enabled": true,
+  "binaryPath": "jikji",
+  "timeoutMs": 10000,
+  "maxBufferBytes": 1048576,
+  "includeHidden": false,
+  "includeSensitive": false,
+  "maxFiles": 0,
+  "writeAgentRules": false,
+  "enableMediaIndex": false,
+  "exclude": []
+}
+```
+
+Call `agent.prepareJikji()` (or `agent.refresh()`) to prepare configured source roots. Hidden files, sensitive files, and media indexing are disabled by default; AutoRAG does not pass `--include-hidden`, `--include-sensitive`, or `--enable-media-index` unless the corresponding option is `true`. AutoRAG-managed prepare runs with `--no-agent-rules` by default, so it never rewrites the consumer repo's `AGENTS.md`/`CLAUDE.md`/`.cursorrules`; an explicit `writeAgentRules: true` opt-in re-enables upstream routing-block injection. AutoRAG passes `--enable-media-index` only when `enableMediaIndex: true`.
+
+The upstream Rust `PrepareArgs` defines reference defaults that AutoRAG does not override unless explicitly configured: parse timeout `5.0`, max hash bytes `512 MiB`, doc text max chars `2,000,000`, doc text chunk chars `1,000,000`, and media index max MB `25.0`. AutoRAG emits `--parse-timeout`, `--max-hash-bytes`, `--doc-text-max-chars`, `--doc-text-chunk-chars`, and `--media-index-max-mb` only when the matching option is set, so the upstream defaults apply otherwise. AutoRAG answers queries through `jikji find` (find-first) plus the Pi agent loop and its registered retrieval methods; `prepare`/`refresh` are indexing-only.
+
+### Datasource skills
+
+Datasource skills let AutoRAG search external, server-configured data sources through the same retrieval pipeline as local documents. A skill describes what it indexes, how it should be refreshed, what source instances exist, and which permission tags/scopes bound access. Retrieval still flows through `RetrievalMethodRegistry` → `ParallelRetriever` → datasource result filtering → `ResultMerger`; datasource skills do not create a parallel search path.
+
+Security defaults are intentionally strict:
+
+- datasource access is default-deny unless trusted server/API configuration supplies `datasourceAccess.allowedTags` and `datasourceAccess.allowedScopes`;
+- model/tool arguments never grant datasource tags or scopes;
+- `search_datasource_documents` accepts only `{ query, topK?, scope? }`, and `scope` can only narrow trusted access.
+
+KakaoTalk is the first datasource skill. It uses the external [`katok`](https://github.com/NomaDamas/katok) CLI only — AutoRAG never reads KakaoTalk databases directly. `katok` failures return diagnostics instead of throwing, and remote embedding egress configuration is rejected before the CLI is spawned.
+
+```typescript
+import { AutoRAGAgent, KatokSkill } from "@autorag/librarian";
+
+const kakao = new KatokSkill({
+  instanceId: "personal",
+  tags: ["kakaotalk", "personal", "pii"],
+  // Optional: client: new KatokClient({ binaryPath: "katok" })
+});
+
+const agent = new AutoRAGAgent({
+  searchPaths: ["/path/to/documents"],
+  datasourceSkills: [kakao],
+  datasourceAccess: {
+    allowedTags: ["kakaotalk"],
+    allowedScopes: ["/kakao/personal/**"],
+  },
+});
+
+await agent.refresh(); // refreshes parsed mirrors, BM25/MinSync, and datasource indexes
+const results = await agent.searchDatasourceDocuments("meeting with Mina", { topK: 5 });
+```
+
+A datasource skill should provide polling/cron metadata for routine indexing, source descriptions for the agent prompt, slash-hierarchical opaque source paths such as `/kakao/personal/chunks/<chunk-id>`, and permission tags that match your server-side access policy.
+
+### Primary target: document collections
+
+AutoRAG is built for **non-code document retrieval**: manuals, legal docs, internal wikis, meeting notes, research literature, knowledge bases, PDFs.
+
+Code repositories work too (the explorer's `grep` is useful), but AutoRAG's real value shows on unstructured text where simple pattern matching isn't enough.
+
+## Configuration and state
+
+The default home state is kept outside the workspace:
+
+```text
+~/.autorag/
+├── config.json
+├── memory.json
+├── logs/
+│   └── runs.jsonl
+└── pi-agent/
+    ├── auth.json
+    ├── models.json
+    ├── settings.json
+    └── sessions/
+```
+
+`config.json` selects sources, the workspace, memory path, retrieval settings, and the two agent models. Configure the roles independently with `agents.orchestrator` and `agents.explorer`. Provider and model IDs must refer to models available in the user's authenticated runtime:
+
+```json
+{
+  "searchPaths": ["/path/to/documents"],
+  "workspacePath": "/path/to/workspace",
+  "memoryPath": "/Users/you/.autorag/memory.json",
+  "agents": {
+    "orchestrator": { "provider": "provider-name", "id": "reasoning-model" },
+    "explorer": { "provider": "provider-name", "id": "exploration-model" }
+  }
+}
+```
+
+`autorag init` leaves `agents` unset when no role-model flags are supplied. At search time AutoRAG resolves an authenticated local provider when possible; otherwise configure both roles explicitly.
+
+Config path precedence is `--config` > `AUTORAG_CONFIG` > `~/.autorag/config.json`. When the home config is absent and `<cwd>/autorag.config.json` exists, AutoRAG copies the legacy file to `~/.autorag/config.json` without deleting or modifying the legacy file. The legacy cwd file is a migration source, not the default location.
+
+`memory.json` stores retrieval memory, `logs/runs.jsonl` records run events, and durable Pi models, settings, and sessions stay under `~/.autorag/pi-agent`. 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 health` checks model/provider auth and explorer subagent setup before a search — it resolves both role models, verifies credential presence, and optionally probes a completion call per role. Use it to diagnose model, provider, auth, timeout, or subagent dispatch failures. `autorag status` remains the model-free index-health command (corpus freshness and BM25/MinSync readiness); it does not check models or subagent dispatch. When `autorag search` fails for a model/provider/subagent reason, the error output includes a hint pointing to `autorag health`.
+
+## Installation
+
+Published as `@autorag/librarian` (dist bundled with Bun, runtime Node ≥ 24 or Bun):
+
+```bash
+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
+```
+
+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** downloads a verified GitHub release asset (on by default; `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`) stays a manual, optional install. All of them degrade gracefully when missing — core BM25 search works without any of them.
+
+## Quick Start
+
+```typescript
+import { AutoRAGAgent } from "@autorag/librarian";
+
+const agent = new AutoRAGAgent({
+  searchPaths: ["/path/to/documents"],
+});
+
+const response = await agent.searchDocuments("summarize the compliance requirements");
+console.log(response.answer);
+for (const result of response.results) {
+  console.log(`[${result.number}] ${result.title} — ${result.summary}`);
+}
+
+// Mark which results were useful — AutoRAG remembers for next time
+agent.recordFeedbackByNumbers(response.sessionId, [1, 3], [2]);
+```
+
+`searchDocuments()` runs the Pi agent loop — it searches, reads, consults memory, curates, and finalizes through the `emit_autorag_results` structured tool — then returns a typed `SearchDocumentsResponse`. The caller consumes the structured payload directly; no assistant text parsing.
+
+## How It Works
+
+```
+    You ask a question
+           │
+           ▼
+    ┌──────────────┐
+    │ Plan + seed  │ ← parent check_memory, Jikji, and retrieval tools
+    └──────┬───────┘
+           ▼
+    ┌──────────────┐
+    │ Delegate     │ ← pi-subagents → gpt-5.6-luna explorer
+    └──────┬───────┘
+           ▼
+    ┌──────────────┐
+    │ Search + read│ ← explorer read/grep/find/ls
+    └──────┬──────┘
+           ▼
+    ┌─────────────┐
+    │   Curate     │ ← Extract key insights, not raw lines
+    └──────┬──────┘
+           ▼
+    [1] Finding A — summary (location)
+    [2] Finding B — summary (location)
+
+           │
+    Caller says "1 was useful, 2 wasn't"
+           │
+           ▼
+    ┌─────────────┐
+    │   Memory     │ ← Remembers what worked, adapts next time
+    └─────────────┘
+```
+
+## License
+
+MIT

package/dist/agent/agent.d.ts

@@ -0,0 +1,294 @@
+import { Agent, type AgentTool, type Skill } 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 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 { DefaultParserRegistryOptions } from "../parser/index.js";
+import { type BM25MethodOptions, type BM25SyncResult } from "../retrieval/methods/bm25.js";
+import { RetrievalMethodRegistry } from "../retrieval/registry.js";
+import type { CuratedResult, RetrievalDiagnostic, RetrievalOptions, RetrievalResult } from "../retrieval/types.js";
+import { type MandatorySubagentSessionOptions } from "../subagents/runtime.js";
+import { type JikjiFindProviderResult } from "./jikji-find-tool.js";
+import { type SearchDocumentDiagnostic, type SearchDocumentsResponse } from "./search-documents.js";
+import { type WatcherFactory, type WatchRefreshHandle } from "./watch-refresh.js";
+export interface AutoRefreshOptions {
+    readonly intervalMs: number;
+    readonly immediate?: boolean;
+}
+/** Methods that `refresh` can selectively run. Defaults to all when omitted. */
+export type RefreshMethod = "parsed" | "bm25" | "minsync" | "datasources" | "jikji";
+export interface AutoRAGRefreshOptions {
+    /** Restrict refresh to specific methods. Defaults to all when undefined. */
+    readonly methods?: readonly RefreshMethod[];
+}
+export interface AutoRAGRefreshResult extends ParsedMirrorSyncResult {
+    readonly bm25?: BM25SyncResult;
+    readonly datasources?: readonly DatasourceIndexResult[];
+}
+export interface AutoRAGRefreshComponentStatus {
+    readonly bm25?: string;
+    readonly minsync?: string;
+    readonly jikji?: string;
+    readonly datasources?: string;
+}
+/** Path-opaque snapshot of corpus freshness and the last refresh outcome. */
+export interface AutoRAGRefreshStatus {
+    readonly state: "idle" | "indexing" | "success" | "failed";
+    readonly inFlight: boolean;
+    readonly lastStartedAt?: string;
+    readonly lastFinishedAt?: string;
+    readonly counts?: {
+        readonly scanned: number;
+        readonly written: number;
+        readonly deleted: number;
+        readonly skipped: number;
+    };
+    readonly stale: boolean;
+    readonly diagnostics: readonly SearchDocumentDiagnostic[];
+    readonly components: AutoRAGRefreshComponentStatus;
+    /** Path-free failure summary of the last refresh, if it failed. */
+    readonly lastError?: string;
+}
+export interface AutoRAGWatchRefreshOptions {
+    readonly debounceMs?: number;
+    readonly force?: boolean;
+    readonly maxWatchers?: number;
+    /** Injectable watcher factory (defaults to a recursive fs.watch). Primarily for tests. */
+    readonly watcherFactory?: WatcherFactory;
+}
+export type AutoRAGWatchRefreshHandle = WatchRefreshHandle;
+export interface AutoRAGAgentOptions {
+    model?: Model<Api>;
+    explorerModel?: Model<Api>;
+    apiKey?: string;
+    providerApiKeys?: Readonly<Record<string, string>>;
+    searchPaths: string[];
+    manifestDir?: string;
+    memoryPath?: string;
+    workspacePath?: string;
+    tools?: AgentTool[];
+    minSync?: Omit<MinSyncVectorMethodOptions, "root"> | false;
+    bm25?: Omit<BM25MethodOptions, "root"> | false;
+    jikji?: JikjiOptions;
+    autoRefresh?: AutoRefreshOptions;
+    parserOptions?: DefaultParserRegistryOptions;
+    datasourceSkills?: readonly DatasourceSkill[];
+    datasourceAccess?: DatasourceAccessContextOptions;
+    sessionFactory?: AutoRAGSessionFactory;
+}
+export interface AutoRAGSearchSession {
+    readonly agent: Agent;
+    prompt(text: string): Promise<void>;
+    abort(): Promise<void> | void;
+    dispose(): void;
+}
+export type AutoRAGSessionFactory = (options: MandatorySubagentSessionOptions) => Promise<AutoRAGSearchSession>;
+export type AutoRAGJikjiPrepareResult = {
+    readonly ok: true;
+    readonly code: number;
+    readonly diagnostics: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: JikjiFailureReason;
+    readonly code: number | null;
+    readonly diagnostics: readonly string[];
+};
+export declare class AutoRAGAgent {
+    private readonly innerAgent;
+    private readonly tools;
+    private readonly configuredModel;
+    private readonly configuredExplorerModel;
+    private readonly apiKey;
+    private readonly providerApiKeys;
+    private readonly sessionFactory;
+    private readonly listeners;
+    private activeSession;
+    private readonly pendingSubagentCalls;
+    private readonly dispatchSequenceBySession;
+    private readonly dispatchArgsTracker;
+    private dispatchSyntheticCounter;
+    private successfulExplorerCalls;
+    private readonly memory;
+    private readonly runLogger;
+    private lastQuery;
+    private lastSessionId;
+    private readonly sessions;
+    private activeRun;
+    private resultCapture;
+    private autoRefreshTimer;
+    private refreshing;
+    private refreshState;
+    private readonly searchPaths;
+    private readonly allowedExplorerRoots;
+    private readonly workspaceProjectRoot;
+    private readonly methodRegistry;
+    private readonly retriever;
+    private readonly merger;
+    private readonly datasourceFilter;
+    private readonly minSyncMethod;
+    private readonly bm25Method;
+    private readonly jikjiClient;
+    private readonly datasourceSkills;
+    private readonly datasourceAccessOptions;
+    private readonly datasourceAgentSkills;
+    private readonly parserOptions;
+    private readonly baseSystemPromptConfig;
+    /** Run-scoped merged Jikji policy, set during searchDocuments; cleared after. */
+    private activeJikjiPolicy;
+    private activeExplorerModel;
+    /** Run-scoped jikji_find call count for the two-phase raw-fallback gate. */
+    private jikjiFindCallCount;
+    private readonly droppedCallerToolNames;
+    constructor(options: AutoRAGAgentOptions);
+    private withMemoryContext;
+    private resolveSessionModel;
+    private configureSearchSession;
+    private recordSearchToolEvent;
+    private nextDispatchSequence;
+    private resolveToolCallId;
+    private emitDispatchAutofilled;
+    private emitDispatchRejected;
+    private emitDispatchRejectedFromRejection;
+    private currentSystemPromptConfig;
+    subscribe(listener: Parameters<Agent["subscribe"]>[0]): () => void;
+    abort(): void;
+    /**
+     * Periodically re-runs the incremental {@link refresh} so parsed mirrors and
+     * indexes stay current. Re-parsing is incremental (mtime/size) via the
+     * existing mirror sync; this only schedules it. Opt-in and stoppable.
+     */
+    startAutoRefresh(intervalMs: number, options?: {
+        immediate?: boolean;
+    }): void;
+    stopAutoRefresh(): void;
+    private runAutoRefreshTick;
+    submitFeedback(sessionId: string | undefined, satisfied: boolean): void;
+    recordResultFeedback(feedback: ResultFeedback[]): void;
+    recordFeedbackByNumbers(sessionId: string, usefulNumbers: number[], notUsefulNumbers?: number[]): void;
+    getResultRegistry(sessionId?: string): ReadonlyMap<number, CuratedResult>;
+    searchDocuments(query: string, options?: RetrievalOptions): Promise<SearchDocumentsResponse>;
+    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).
+     */
+    private buildAuthorizedDatasourceSkills;
+    /**
+     * 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.
+     */
+    loadDatasourceSkill(name: string): Skill | undefined;
+    private indexDatasources;
+    /** Path-opaque component diagnostics (e.g. BM25 readiness) for the search response. */
+    private collectComponentDiagnostics;
+    buildSearchPrompt(query: string, options: RetrievalOptions, explorerModel?: 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.
+     */
+    getRefreshStatus(): Promise<AutoRAGRefreshStatus>;
+    private refreshComponentStatus;
+    /**
+     * Opt-in filesystem watch that keeps parsed mirrors and configured indexes
+     * current. Debounced, backpressure-limited (one in-flight refresh plus one
+     * coalesced rerun), stoppable, and safe under rapid change bursts. Excludes
+     * `.autorag`/`.git`/`node_modules` and does not follow symlinks. Coexists with
+     * the polling {@link startAutoRefresh}. Returns a handle whose stop() closes
+     * every watcher and prevents any further scheduled refresh.
+     */
+    startWatchRefresh(options?: AutoRAGWatchRefreshOptions): AutoRAGWatchRefreshHandle;
+    private defaultWatcherFactory;
+    syncParsedMirrors(force?: boolean): Promise<ParsedMirrorSyncResult>;
+    /**
+     * Lightweight stat-only staleness scan used when `refresh` is called with
+     * methods that exclude parsed mirrors (e.g. only `datasources` or `jikji`).
+     * Returns a zero-count `ParsedMirrorSyncResult` carrying fresh diagnostics
+     * so the refresh result and status remain consistent.
+     */
+    private scanMirrorStaleness;
+    syncBM25(): Promise<BM25SyncResult | undefined>;
+    syncMinSync(): Promise<MinSyncSyncResult | undefined>;
+    prepareJikji(): Promise<readonly AutoRAGJikjiPrepareResult[] | undefined>;
+    private executeJikjiPrepare;
+    private sanitizeJikjiPrepareResult;
+    /**
+     * Provider method for the jikji_find tool. Runs JikjiClient.find over all
+     * configured search roots, normalizes answer paths against planned source
+     * roots, merges per-root answer packs using least-privilege (restrictive-
+     * wins) semantics, and sets the run-scoped activeJikjiPolicy. Only mutates
+     * run state (activeJikjiPolicy / jikjiFindCallCount) when a searchDocuments
+     * run is active; direct out-of-run calls compute and return the result
+     * without persisting. When jikji is unavailable or all roots fail, returns
+     * an unavailable result and leaves the policy undefined (bash is allowed).
+     */
+    findJikji(query: string, opts?: {
+        readonly topK?: number;
+        readonly first?: boolean;
+    }): Promise<JikjiFindProviderResult>;
+    /**
+     * 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.
+     */
+    private mergeAnswerPacks;
+    /**
+     * Least-privilege (restrictive-wins) merge of per-root policies.
+     * - forbiddenTools: UNION
+     * - allowedFollowups: INTERSECTION
+     * - stopAfterFind: OR
+     * - agentShouldNotRerank: OR
+     * - handoffAction: MOST RESTRICTIVE (direct_use < jikji_retry < raw_fallback_after_retry)
+     * - rawFallbackAllowed: handoffAction===raw_fallback_after_retry AND callCount>=2
+     */
+    private mergePolicy;
+    /**
+     * Deny-by-default bash gate. When jikji is configured but no jikji_find has
+     * run yet this run (count===0), bash is blocked so the agent discovers local
+     * files via jikji_find first. After a find, the run-scoped activeJikjiPolicy
+     * applies: when no policy is active, bash behaves exactly as before
+     * (allowed). Under an active policy, bash is denied unless handoffAction is
+     * raw_fallback_after_retry AND rawFallbackAllowed is true (after a second
+     * jikji_find). When jikji is not configured, the find-first branch is
+     * skipped entirely (bash unchanged).
+     */
+    private bashGate;
+    /**
+     * Programmatic retrieval across all registered methods, merged via min-max
+     * normalization + source dedup. Activates the RetrievalMethodRegistry /
+     * ParallelRetriever / ResultMerger pipeline. Returns opaque root-relative
+     * sourced results.
+     */
+    retrieve(query: string, options?: RetrievalOptions): Promise<RetrievalResult[]>;
+    /**
+     * Programmatic retrieval that also returns diagnostics for any
+     * retrieval method that failed (e.g. MinSync binary missing). Healthy method
+     * results are preserved. The legacy {@link retrieve} return shape is unchanged.
+     */
+    retrieveWithDiagnostics(query: string, options?: RetrievalOptions): Promise<{
+        results: RetrievalResult[];
+        diagnostics: RetrievalDiagnostic[];
+    }>;
+    searchAllDocuments(query: string, options?: {
+        readonly topK?: number;
+        readonly scope?: string;
+    }): Promise<{
+        results: RetrievalResult[];
+        diagnostics: RetrievalDiagnostic[];
+    }>;
+    searchDatasourceDocuments(query: string, options?: {
+        readonly topK?: number;
+        readonly scope?: string;
+    }): Promise<{
+        results: RetrievalResult[];
+        diagnostics: RetrievalDiagnostic[];
+    }>;
+    /** The retrieval method registry (posix active; vector/bm25/hybrid pluggable). */
+    getMethodRegistry(): RetrievalMethodRegistry;
+    getSystemPrompt(): string;
+}

package/dist/agent/bash-tool.d.ts

@@ -0,0 +1,41 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+export declare const BASH_TOOL_NAME = "bash";
+declare const bashSchema: Type.TObject<{
+    command: Type.TString;
+    cwd: Type.TOptional<Type.TString>;
+    timeoutMs: Type.TOptional<Type.TInteger>;
+}>;
+export interface BashToolOptions {
+    /** Default working directory for spawned commands. */
+    readonly cwd: string;
+    /** Maximum wall-clock time per command before it is killed. */
+    readonly timeoutMs?: number;
+    /** Maximum captured output bytes before truncation. */
+    readonly maxOutputBytes?: number;
+    /**
+     * Optional deny-by-default gate. When present and returns
+     * `{ allowed: false }`, the command is NOT spawned; the tool returns the
+     * gate message with `blockedByJikjiPolicy: true`. Used by the Jikji policy
+     * to enforce stop_after_find / direct_use / forbidden bash restrictions.
+     */
+    readonly gate?: () => {
+        allowed: boolean;
+        message: string;
+    };
+}
+export interface BashToolDetails {
+    readonly method: "bash";
+    readonly command: string;
+    readonly exitCode: number | undefined;
+    readonly timedOut: boolean;
+    readonly truncated: boolean;
+    readonly blockedByJikjiPolicy?: boolean;
+}
+/**
+ * Real shell access for the librarian agent. AutoRAG navigates and reads the
+ * configured collection directly through this tool (ls, find, grep, cat, …).
+ * Output — including real filesystem paths — is returned to the model verbatim.
+ */
+export declare function createBashTool(options: BashToolOptions): AgentTool<typeof bashSchema, BashToolDetails>;
+export {};