@autorag/librarian 2.4.0 → 2.4.1

package/dist/jikji/client.d.ts

@@ -3,6 +3,8 @@ export declare class JikjiClient {
     private readonly options;
     private resolvedCommand;
     constructor(options?: JikjiOptions);
+    /** Jikji stores prepared corpus metadata under a hidden directory in each root. */
+    isPrepared(root: string): boolean;
     /**
      * Resolve the jikji command following the priority chain:
      * 1. explicit binaryPath

package/dist/minsync/index.d.ts

@@ -1,7 +1,7 @@
 export { MinSyncClient, type MinSyncClientOptions, type MinSyncQueryMode } from "./client.js";
 export { MINSYNC_CONFIG_DIR, MINSYNC_CONFIG_FILE, minSyncConfigPath, rewriteEmbedderConfig, } from "./embedder-config.js";
 export { type EnsureMinSyncBinaryOptions, ensureMinSyncBinary, executableName, fetchLatestMinSyncRelease, type InstalledMinSyncBinary, MINSYNC_VERSION, type MinSyncRelease, type MinSyncReleaseAsset, MinSyncReleaseError, selectReleaseAsset, } from "./installer.js";
-export { MinSyncBM25Method, type MinSyncBM25MethodOptions, MinSyncHybridMethod, type MinSyncHybridMethodOptions, MinSyncVectorMethod, type MinSyncVectorMethodOptions, } from "./method.js";
+export { MinSyncHybridMethod, type MinSyncHybridMethodOptions, MinSyncVectorMethod, type MinSyncVectorMethodOptions, } from "./method.js";
 export { MINSYNC_FILES_SUBDIR, MINSYNC_SUBDIR, minSyncDocumentPath, minSyncWorkspaceRoot } from "./paths.js";
 export type { MinSyncChunkerConfig, MinSyncEmbedderConfig, MinSyncOptions, MinSyncQueryHit, MinSyncSyncResult, } from "./types.js";
 export { buildMinSyncPathMap, type MinSyncWorkspaceEntry, type MinSyncWorkspaceSyncResult, syncMinSyncWorkspace, } from "./workspace.js";

package/dist/minsync/method.d.ts

@@ -1,10 +1,10 @@
-import { type BM25Status, type BM25SyncResult } from "../retrieval/methods/bm25.js";
 import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../retrieval/types.js";
 import type { MinSyncQueryMode } from "./client.js";
 import { type EnsureMinSyncBinaryOptions } from "./installer.js";
 import type { MinSyncEmbedderConfig, MinSyncSyncResult } from "./types.js";
 export interface MinSyncVectorMethodOptions {
     readonly root: string;
+    /** Test/embedded override; CLI config intentionally does not persist this. */
     readonly binaryPath?: string;
     readonly workspacePath?: string;
     readonly installer?: Omit<EnsureMinSyncBinaryOptions, "root">;
@@ -13,7 +13,6 @@ export interface MinSyncVectorMethodOptions {
     readonly maxChunkSize?: number;
     readonly mode?: MinSyncQueryMode;
 }
-export type MinSyncBM25MethodOptions = Omit<MinSyncVectorMethodOptions, "mode">;
 export type MinSyncHybridMethodOptions = Omit<MinSyncVectorMethodOptions, "mode">;
 export declare class MinSyncVectorMethod implements RetrievalMethod {
     private readonly root;
@@ -27,31 +26,20 @@ export declare class MinSyncVectorMethod implements RetrievalMethod {
     constructor(options: MinSyncVectorMethodOptions);
     describe(): RetrievalMethodDescriptor;
     sync(): Promise<MinSyncSyncResult>;
-    /** True when a configured binary path is missing (an explicit degraded state). */
+    /** MinSync is resolved from PATH, then the workspace cache. */
     isBinaryMissing(): boolean;
+    /** A vector index is ready only after MinSync has written its cursor. */
+    isReady(): boolean;
     retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
     /**
-     * Resolve the minsync binary path following the priority chain:
-     * 1. explicit binaryPath if set and exists
-     * 2. PATH lookup for `minsync`
-     * 3. cached join(root, '.autorag', 'bin', execName) if exists
-     * 4. if autoInstall===true, try ensureMinSyncBinary in try/catch => install-failed degrade
-     * 5. else return undefined (missing-binary degrade)
+     * Resolve the MinSync CLI from the user's global PATH first, then the
+     * workspace cache, and finally the verified auto-install fallback.
      *
      * Returns: string path on success, undefined for missing-binary, or a MinSyncSyncResult
      * for install-failed.
      */
     protected resolveBinary(): Promise<string | undefined | MinSyncSyncResult>;
 }
-export declare class MinSyncBM25Method extends MinSyncVectorMethod {
-    private status;
-    constructor(options: MinSyncBM25MethodOptions);
-    describe(): RetrievalMethodDescriptor;
-    retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
-    syncFromMinSync(result: MinSyncSyncResult): BM25SyncResult;
-    getStatus(): BM25Status;
-    private resolveBinaryForRetrieve;
-}
 export declare class MinSyncHybridMethod extends MinSyncVectorMethod {
     constructor(options: MinSyncHybridMethodOptions);
     describe(): RetrievalMethodDescriptor;

package/dist/retrieval/index.d.ts

@@ -1,7 +1,5 @@
 export type { MergeOptions } from "./merger.js";
 export { ParallelRetriever, ResultMerger } from "./merger.js";
-export type { BM25Engine, BM25ReadinessState, BM25Status, BM25SyncResult } from "./methods/bm25.js";
-export { BM25_SUBDIR, BM25UnavailableError, hasLegacyBm25Artifacts, removeLegacyBm25Artifacts, } from "./methods/bm25.js";
 export { RetrievalMethodRegistry } from "./registry.js";
 export { matchesVirtualPathScope, normalizeVirtualPath, normalizeVirtualPathScope, virtualPathScopeToRegExp, } from "./scope.js";
 export type { CuratedResult, NumberedResult, RetrievalDiagnostic, RetrievalDiagnosticCode, RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult, RetrievalWithDiagnostics, } from "./types.js";

package/dist/retrieval/registry.d.ts

@@ -1,8 +1,8 @@
-import type { RetrievalMethod } from "./types.js";
+import type { RetrievalMethod, RetrievalMethodDescriptor } from "./types.js";
 export declare class RetrievalMethodRegistry {
     private readonly methods;
     register(method: RetrievalMethod): void;
     get(name: string): RetrievalMethod | undefined;
     list(): RetrievalMethod[];
-    getByType(type: "posix" | "vector" | "bm25" | "hybrid" | "visual"): RetrievalMethod[];
+    getByType(type: RetrievalMethodDescriptor["type"]): RetrievalMethod[];
 }

package/dist/retrieval/types.d.ts

@@ -26,7 +26,7 @@ export interface RetrievalMethod {
     describe(): RetrievalMethodDescriptor;
     retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
 }
-export type RetrievalDiagnosticCode = "retrieval-method-failed" | "minsync-unavailable" | "bm25-unavailable" | "bm25-degraded-fallback";
+export type RetrievalDiagnosticCode = "retrieval-method-failed" | "minsync-unavailable";
 /** Path-opaque diagnostic emitted by the multi-method retrieval pipeline. */
 export interface RetrievalDiagnostic {
     code: RetrievalDiagnosticCode;

package/dist/ui/discover.d.ts

@@ -11,8 +11,6 @@ export type DiscoverRun = (binary: string, args: readonly string[]) => Promise<{
     stdout: string;
 }>;
 export declare function listRcloneRemotes(run?: DiscoverRun): Promise<readonly Choice[]>;
-export declare function listMailAccounts(run?: DiscoverRun): Promise<readonly Choice[]>;
-export declare function listHimalayaAccounts(run?: DiscoverRun): Promise<readonly Choice[]>;
 export declare function choicesForType(type: string, run?: DiscoverRun): Promise<{
     rcloneRemotes: readonly Choice[];
     mailAccounts: readonly Choice[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autorag/librarian",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Self-evolving librarian agent on Pi framework with pluggable retrieval methods",
   "license": "MIT",
   "repository": {

package/skills/autorag/SKILL.md

@@ -11,7 +11,7 @@ summarize, compare, or answer questions from local PDFs, wikis, notes, research
 papers, knowledge bases, or authorized datasources.
 
 AutoRAG is the specialized librarian agent. One configured model plans the
-search, calls BM25, MinSync, Jikji, datasource, and filesystem tools, reads
+search, calls MinSync, Jikji, datasource, and filesystem tools, reads
 sources, judges evidence, and curates the final answer. There is no subagent or
 separate model role.
 
@@ -46,7 +46,7 @@ checks credential presence, and normally probes one live completion. If the
 model, authentication, configuration, or indexes are unhealthy, use
 `autorag-setup` rather than guessing private provider details.
 
-BM25, MinSync, and Jikji should normally be healthy. MinSync and Jikji
+MinSync and Jikji should normally be healthy. MinSync and Jikji
 auto-install on first use by default. If they are missing or stale, run a full
 `autorag refresh` or return to setup rather than silently degrading to
 lexical-only search.
@@ -65,15 +65,28 @@ autorag search "what were the key findings in the Q3 report" --top-k 5 --json --
 `summary`, optional `source`), and `sessionId`. Use that `sessionId` for
 feedback. `--json` without `--debug` is only `answer` plus `results`.
 
+To inspect the exact persisted evidence behind numbered results, use:
+
+```bash
+autorag evidence <sessionId> --result 1 --json
+```
+
+The response includes the original source, retrieval method, stable evidence
+ID, raw excerpt/content, and any available `chunkIndex`, `lineNumber`,
+`retrievalResultId`, and metadata. Omit `--result` to inspect every result in
+the session. Prefer this command whenever the caller wants detailed chunk text
+rather than only the curated summary.
+
 - `--scope` narrows datasource retrieval to a requested sub-path; it cannot
   grant access.
 - `--tags` further narrows already-authorized datasource results and never
   grants new access.
 - `--json` is required for programmatic consumption.
-- `--debug` is required for `sessionId`, evidence, and diagnostics.
+- `--debug` is required for `sessionId` and diagnostics in search output.
+- `autorag evidence` is the detailed source/chunk inspection path.
 
 Do not bypass the librarian with ad hoc raw search when the user requested
-AutoRAG. The search loop can use Jikji, BM25, MinSync, datasource retrieval, and
+AutoRAG. The search loop can use Jikji, MinSync lexical/vector/hybrid retrieval, datasource retrieval, and
 direct source reading as appropriate. If search fails because of model,
 provider, auth, or timeout problems, diagnose with `autorag health --json`.
 
@@ -99,9 +112,9 @@ autorag index reset --method bm25 --yes --json
 autorag memory inspect --json
 ```
 
-Prefer a full refresh so parsed mirrors, BM25, MinSync, Jikji, and configured
+Prefer a full refresh so parsed mirrors, MinSync, Jikji, and configured
 datasources stay aligned. `--method` accepts
-`parsed,bm25,minsync,datasources,jikji,all`. Use it only for deliberate
+`parsed,minsync,datasources,jikji,all`. Use it only for deliberate
 narrowing. Scheduled maintenance should use non-daemon `autorag watch --once`,
 typically every 15–30 minutes, with the same config used by search and no
 overlapping runs.

package/skills/autorag-setup/SKILL.md

@@ -127,7 +127,7 @@ Use `--force` only when intentionally replacing an existing config. Legacy cwd
 
 ### Retrieval defaults
 
-BM25, MinSync, and Jikji are enabled by default. Leave them enabled unless the
+MinSync and Jikji are enabled by default. Leave them enabled unless the
 user explicitly asks otherwise. MinSync auto-installs a verified GitHub release
 into `<workspace>/.autorag/bin` on first use (`minSync.autoInstall` defaults to
 true). Set `"autoInstall": false` only when managing the binary yourself. Jikji
@@ -175,7 +175,7 @@ aliases with `"type": "<template>"`. Unknown names are skipped with an
     "github": { "connector": { "repos": ["owner/repo"], "tokenEnv": "GITHUB_TOKEN" } },
     "google-drive": { "type": "cloud-drive", "connector": { "provider": "google-drive", "remote": "gdrive:" } },
     "archive-drive": { "type": "cloud-drive", "connector": { "remote": "archive:" } },
-    "gmail": { "connector": { "backend": "himalaya", "account": "gmail", "folder": "INBOX" } },
+    "gmail": { "connector": { "tokenEnv": "GMAIL_ACCESS_TOKEN", "labelIds": ["INBOX"] } },
     "mailcrawl": { "instanceId": "personal", "connector": { "account": "personal", "mailbox": "INBOX", "binaryPath": "mailcrawl" } },
     "obsidian": { "connector": { "vaultPath": "/path/to/vault" } },
     "rss": { "connector": { "feeds": [{ "url": "https://example.com/feed.xml" }] } }
@@ -195,6 +195,9 @@ and configured through its own Himalaya account. AutoRAG runs its local `sync`
 and `index` lifecycle, then uses the mailcrawl CLI for BM25, semantic, or
 hybrid search. Do not use 0.1.3 or earlier: a no-op sync followed by `index`
 fails with `text array must be non-empty`.
+Use mailcrawl for Himalaya-backed IMAP/Maildir retrieval. The legacy
+`gmail` connector option `backend: "himalaya"` is no longer registered; migrate
+that configuration to an explicit `mailcrawl` datasource.
 
 ## Verify and build indexes
 
@@ -212,12 +215,15 @@ autorag search "summarize the collection" --top-k 3 --json --debug
   performs one live completion probe.
 - `health --skip-probes` is only for intentionally offline validation and does
   not prove live provider access.
-- `refresh` syncs parsed mirrors, BM25, MinSync, Jikji, and authorized
+- `refresh` syncs parsed mirrors, MinSync, Jikji, and authorized
   datasources. `--method <csv>` may deliberately narrow it
-  (`parsed,bm25,minsync,datasources,jikji,all`).
+  (`parsed,minsync,datasources,jikji,all`).
 - Use `refresh --force` for a full resync only when incremental refresh is not
   enough. Keep destructive reset/rebuild operations scoped to workspace
   `.autorag` indexes, never source documents.
+- After a search, use `autorag evidence <sessionId> --json` to inspect the
+  exact source chunks behind numbered results, including source, method,
+  stable evidence ID, excerpt/content, chunk index, and line number.
 
 ## Keep indexes fresh
 

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

@@ -1,26 +0,0 @@
-import type { AgentTool } from "@earendil-works/pi-agent-core";
-import { Type } from "typebox";
-import type { BM25Status } from "../retrieval/methods/bm25.js";
-import type { RetrievalResult } from "../retrieval/types.js";
-export declare const SEARCH_BM25_DOCUMENTS_TOOL_NAME = "lexical_search_local_docs";
-declare const searchBM25Schema: Type.TObject<{
-    query: Type.TString;
-    topK: Type.TOptional<Type.TInteger>;
-    scope: Type.TOptional<Type.TString>;
-}>;
-export interface SearchBM25DocumentsDetails {
-    readonly method: "bm25";
-    readonly resultCount: number;
-    readonly sources: readonly string[];
-    readonly readiness: BM25Status["readiness"];
-    readonly engine: BM25Status["engine"];
-}
-export interface BM25SearchMethod {
-    getStatus(): BM25Status;
-    retrieve(query: string, options: {
-        topK?: number;
-        scope?: string;
-    }): Promise<RetrievalResult[]>;
-}
-export declare function createSearchBM25DocumentsTool(getMethod: () => BM25SearchMethod | undefined, resolveScope?: (scope: string | undefined) => string | undefined): AgentTool<typeof searchBM25Schema, SearchBM25DocumentsDetails>;
-export {};

package/dist/datasource/skills/gmail/himalaya-connector.d.ts

@@ -1,51 +0,0 @@
-/**
- * Himalaya-backed mail connector (issue #1304, IMAP path).
- *
- * Uses the external `himalaya` CLI (https://pimalaya.org) as the trusted
- * bridge to any IMAP/Maildir account it has configured — Gmail included —
- * so no OAuth token plumbing is needed here. Mirrors the katok pattern:
- * AutoRAG never opens the mailbox itself; it spawns the CLI, parses JSON
- * envelopes, and reads message bodies. Never throws; failures map onto the
- * coarse connector failure union with path/PII-opaque messages.
- */
-import { type ConnectorFetchResult, type DatasourceConnector } from "../../connector.js";
-export interface HimalayaRunResult {
-    readonly ok: boolean;
-    readonly stdout: string;
-    readonly stderr: string;
-    readonly code: number | null;
-}
-export type HimalayaRunner = (args: readonly string[], timeoutMs: number) => Promise<HimalayaRunResult>;
-export interface HimalayaConnectorOptions {
-    /** Path to the himalaya binary. Default bare `himalaya` PATH lookup. */
-    readonly binaryPath?: string;
-    /** Himalaya account name (`himalaya account list`). Default account when omitted. */
-    readonly account?: string;
-    /** Mail folder, e.g. `INBOX`. Himalaya's default folder when omitted. */
-    readonly folder?: string;
-    /** Envelopes per listing page. Default 100. */
-    readonly pageSize?: number;
-    /** Max messages whose bodies are fetched per run. Default 50. */
-    readonly maxDocuments?: number;
-    /**
-     * Workspace root for the connector's envelope fingerprint state. When set,
-     * subsequent refreshes fetch only new or changed envelopes and update the
-     * shared chunk store incrementally.
-     */
-    readonly workspaceRoot?: string;
-    /** Per-spawn timeout. Default 30s (IMAP fetches can be slow). */
-    readonly timeoutMs?: number;
-    /** Injectable process runner for tests. */
-    readonly runner?: HimalayaRunner;
-    /** Explicit operator-owned config path, passed read-only to Himalaya. */
-    readonly configPath?: string;
-}
-export declare class HimalayaConnector implements DatasourceConnector {
-    private readonly options;
-    private readonly runner;
-    constructor(options?: HimalayaConnectorOptions);
-    fetch(): Promise<ConnectorFetchResult>;
-    private loadState;
-    private saveState;
-    private statePath;
-}

package/dist/retrieval/methods/bm25.d.ts

@@ -1,23 +0,0 @@
-export type BM25ReadinessState = "disabled" | "dependency_unavailable" | "index_missing" | "indexing" | "ready" | "error";
-/** Local BM25 is always MinSync-backed when enabled. */
-export type BM25Engine = "minsync" | "none";
-export interface BM25SyncResult {
-    readonly indexPath: string;
-    readonly indexedChunks: number;
-    readonly readiness: BM25ReadinessState;
-    readonly engine: BM25Engine;
-}
-export interface BM25Status {
-    readonly readiness: BM25ReadinessState;
-    readonly engine: BM25Engine;
-    readonly message?: string;
-}
-/** Legacy AutoRAG-local BM25 artifact directory. Never an active index. */
-export declare const BM25_SUBDIR: string;
-export declare class BM25UnavailableError extends Error {
-    readonly readiness: BM25ReadinessState;
-    constructor(readiness: BM25ReadinessState, message: string);
-}
-/** Remove leftover `.autorag/bm25` artifacts from the pre-MinSync BM25 path. */
-export declare function removeLegacyBm25Artifacts(root: string): void;
-export declare function hasLegacyBm25Artifacts(root: string): boolean;