@autorag/librarian 2.6.3 → 2.7.0

package/README.md

@@ -74,6 +74,13 @@ AutoRAG Agent orchestrates five integrated subsystems:
 4. **Direct Evidence Reading (`bash`):** The agent directly opens and inspects promising files with `cat`, `grep`, or `find` to verify facts against ground truth.
 5. **Curation & Active Feedback:** Structured findings are returned via `emit_autorag_results`. When callers provide feedback on which items were useful, AutoRAG records this to optimize future queries.
 
+### Pi host boundary
+
+AutoRAG uses `@earendil-works/pi-coding-agent` as the runtime host for model sessions. Pi owns provider credentials and OAuth storage, model-runtime dispatch, session JSONL persistence/resume, extension loading, lifecycle events, and the built-in `read`/`bash`/`edit`/`write`/`grep`/`find`/`ls` tools. AutoRAG registers only its domain tools and keeps orchestration outside the host: datasource authorization, MinSync/Jikji preparation, memory hints, fast-to-verification two-phase search, structured result emission, and remote-session filtering.
+
+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.
+
+
 ---
 
 ## 🤖 For AI Agents & LLMs: Setup & Skills
@@ -249,7 +256,7 @@ PDF pages.
 # Perform a curated search (uses your configured reasoning model)
 autorag search "What are our primary Q3 deliverables?"
 
-# Launch the interactive Terminal UI (beta)
+# Launch the interactive Terminal UI (Pi host: /login, /model, /resume, …)
 autorag tui
 ```
 
@@ -287,7 +294,8 @@ agent.recordFeedbackByNumbers(response.sessionId, [1], [2]);
 | `autorag search "<query>"` | Run the librarian agent to curate structured answers |
 | `autorag status` | Inspect corpus freshness, indexing status, and vector readiness |
 | `autorag health` | Check model provider authentication, token validity, and API reachability |
-| `autorag tui` | Open the interactive librarian terminal UI |
+| `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 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 |

package/dist/agent/agent.d.ts

@@ -1,4 +1,4 @@
-import { Agent, type AgentTool, type Skill } from "@earendil-works/pi-agent-core";
+import type { Agent, AgentTool, 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";
@@ -21,6 +21,7 @@ import type { CuratedResult, RetrievalDiagnostic, RetrievalOptions, RetrievalRes
 import { type ScanDuplicateDocumentsDetails } from "./dupey-tool.js";
 import { type AutoRAGFastAnswerDetails } from "./fast-answer-tool.js";
 import { type JikjiFindProviderResult } from "./jikji-find-tool.js";
+import { type AutoRAGPiInteractiveRuntime, type AutoRAGPiSession } from "./pi-session.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";
@@ -257,6 +258,12 @@ export interface AutoRAGAgentOptions {
     remoteSession?: boolean;
     /** Two-phase progressive answers with per-phase thinking control. Default enabled. */
     thinking?: AutoRAGThinkingOptions | false;
+    /** 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;
 }
 /** Post-merge reranking options. Mirrors the CLI `RerankConfig` (secrets via env). */
 export interface RerankAgentOptions {
@@ -277,6 +284,7 @@ export interface RerankAgentOptions {
 }
 export interface AutoRAGSearchSession {
     readonly agent: Agent;
+    readonly piSession?: AutoRAGPiSession["session"];
     prompt(text: string): Promise<void>;
     abort(): Promise<void> | void;
     dispose(): void;
@@ -308,7 +316,7 @@ export declare class AutoRAGAgent {
     private readonly sessions;
     private activeRun;
     private resultCapture;
-    /** This agent's model credential for model-native web search (per instance, never shared). */
+    private interactiveFastAnswerCallback;
     private modelNativeSearchAuth;
     private retrievalTrace;
     private preliminaryCallback;
@@ -350,6 +358,10 @@ export declare class AutoRAGAgent {
     private readonly droppedCallerToolNames;
     private readonly searchTimeoutMs;
     private readonly maxSearchToolCalls;
+    private readonly piAgentDir;
+    private readonly piSessionDir;
+    private readonly persistPiSessions;
+    private boundPiRuntime;
     /** True when this agent was constructed for an untrusted remote peer. */
     readonly remoteSession: boolean;
     private activeRetrievalOptions;
@@ -364,6 +376,8 @@ export declare class AutoRAGAgent {
     private recordSearchToolEvent;
     private currentSystemPromptConfig;
     subscribe(listener: Parameters<Agent["subscribe"]>[0]): () => void;
+    createPiInteractiveRuntime(): Promise<AutoRAGPiInteractiveRuntime>;
+    private runInteractivePiQuery;
     abort(): void;
     /**
      * Periodically re-runs the incremental {@link refresh} so parsed mirrors and

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

@@ -0,0 +1,35 @@
+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";
+export declare const PI_BUILTIN_TOOL_NAMES: readonly ["read", "bash", "edit", "write", "grep", "find", "ls"];
+export interface AutoRAGPiSessionOptions {
+    readonly cwd: string;
+    readonly agentDir?: string;
+    readonly sessionDir?: string;
+    readonly sessionPath?: string;
+    readonly persistSession?: boolean;
+    readonly model: Model<Api>;
+    readonly apiKey?: string;
+    readonly providerApiKeys?: Readonly<Record<string, string>>;
+    readonly getSystemPrompt: () => string;
+    readonly customTools: readonly AgentTool[];
+    readonly remoteSession?: boolean;
+    readonly contextTransform?: (messages: AgentMessage[]) => Promise<AgentMessage[]>;
+}
+export interface AutoRAGPiInteractiveRuntimeOptions extends Omit<AutoRAGPiSessionOptions, "model"> {
+    readonly model?: Model<Api>;
+    readonly inactiveToolNames?: readonly string[];
+    readonly onQuery: (query: string, pi: ExtensionAPI) => void | Promise<void>;
+}
+export interface AutoRAGPiSession {
+    readonly session: AgentSession;
+    readonly baseToolNames: readonly string[];
+    readonly sessionFile: string | undefined;
+}
+/** Creates a pi session with AutoRAG's tools and prompt. */
+export declare function createAutoRAGPiSession(options: AutoRAGPiSessionOptions): Promise<AutoRAGPiSession>;
+export interface AutoRAGPiInteractiveRuntime {
+    readonly runtime: AgentSessionRuntime;
+    readonly dispose: () => Promise<void>;
+}
+export declare function createAutoRAGPiInteractiveRuntime(options: AutoRAGPiInteractiveRuntimeOptions): Promise<AutoRAGPiInteractiveRuntime>;

package/dist/cli/commands/health.d.ts

@@ -1,6 +1,5 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
-import type { LoadLocalAutoRAGModelOptions } from "../../agent/local-model.js";
-import { type CliConfig, type ResolvedAgentModelDetailed } from "../config.js";
+import { type CliConfig, type ResolveAgentModelOptions, type ResolvedAgentModelDetailed } from "../config.js";
 import type { CommandContext } from "./types.js";
 export type HealthCategory = "config" | "model_resolution" | "auth_missing" | "provider_unreachable" | "completion_failed" | "timeout" | "ok";
 export interface HealthCoverage {
@@ -83,7 +82,7 @@ export interface HealthDeps {
         cwd?: string;
         env?: NodeJS.ProcessEnv;
     }) => CliConfig;
-    modelResolver?: (config: CliConfig, localOptions?: LoadLocalAutoRAGModelOptions) => ResolvedHealthModel;
+    modelResolver?: (config: CliConfig, options?: ResolveAgentModelOptions) => ResolvedHealthModel | Promise<ResolvedHealthModel>;
     probe?: (input: ProbeInput, signal: AbortSignal) => Promise<ProbeOutput>;
     now?: () => number;
 }

package/dist/cli/commands/models.d.ts

@@ -1,5 +1,24 @@
 import type { ProfileId } from "../../embedding-runtime/types.js";
 import type { CommandContext } from "./types.js";
+/**
+ * One chat model discovered through the pi model runtime (built-in catalog plus
+ * `models.json`, custom, and extension providers). `available` reports whether
+ * the provider has complete auth configuration, including stored `auth.json`
+ * credentials (api-key or OAuth).
+ */
+export interface ModelCatalogEntry {
+    readonly provider: string;
+    readonly id: string;
+    readonly name: string;
+    readonly api: string;
+    readonly available: boolean;
+}
+export interface ModelCatalogOptions {
+    readonly provider?: string;
+    /** Only list models whose provider has complete auth configuration. */
+    readonly available?: boolean;
+    readonly agentDir?: string;
+}
 export interface ModelsCommandDeps {
     prefetchModel?: (profileId?: ProfileId) => Promise<{
         profileId: ProfileId;
@@ -14,5 +33,6 @@ export interface ModelsCommandDeps {
         path: string;
         hash: string;
     }>;
+    listModels?: (options: ModelCatalogOptions) => Promise<readonly ModelCatalogEntry[]>;
 }
 export declare function runModels(ctx: CommandContext, deps?: ModelsCommandDeps): Promise<number>;

package/dist/cli/commands/search.d.ts

@@ -1,5 +1,5 @@
 import { AutoRAGAgent, type AutoRAGAgentOptions } from "../../agent/agent.js";
-import { type CliConfig, type ResolvedAgentModel } from "../config.js";
+import { type CliConfig, type ResolveAgentModelOptions, type ResolvedAgentModel } from "../config.js";
 import type { CommandContext } from "./types.js";
 /**
  * A recoverable health hint surfaced when `autorag search` fails for a reason
@@ -25,7 +25,7 @@ export declare function classifySearchHealthHint(error: unknown): SearchHealthHi
  */
 export interface SearchDeps {
     agentFactory?: (opts: AutoRAGAgentOptions) => Pick<AutoRAGAgent, "searchDocumentsStream">;
-    modelResolver?: (config: CliConfig) => ResolvedAgentModel;
+    modelResolver?: (config: CliConfig, options?: ResolveAgentModelOptions) => ResolvedAgentModel | Promise<ResolvedAgentModel>;
     /**
      * Stops the on-demand embedding gateway so the process can exit. Without
      * this the semantic MinSync path's loopback gateway keeps the event loop

package/dist/cli/commands/serve.d.ts

@@ -1,14 +1,14 @@
 import type { InjectionClassifierModel } from "../../p2p/injection-classifier.js";
 import { type SimplexPeerServer, startSimplexPeerServer, syncSimplexPeers } from "../../p2p/simplex-server.js";
 import { type SimplexTransport, type StartSimplexOptions } from "../../p2p/simplex-transport.js";
-import { type ResolvedAgentModel, resolveAgentModel } from "../config.js";
+import { type CliConfig, type ResolveAgentModelOptions, type ResolvedAgentModel } from "../config.js";
 import type { CommandContext } from "./types.js";
 export interface ServeCommandDeps {
     readonly startSimplexPeerServer?: typeof startSimplexPeerServer;
     readonly startSimplexChat?: (options: StartSimplexOptions) => Promise<SimplexTransport>;
     readonly syncSimplexPeers?: typeof syncSimplexPeers;
     readonly waitUntilStopped?: (server: SimplexPeerServer) => Promise<void>;
-    readonly modelResolver?: typeof resolveAgentModel;
+    readonly modelResolver?: (config: CliConfig, options?: ResolveAgentModelOptions) => ResolvedAgentModel | Promise<ResolvedAgentModel>;
 }
 export declare function createInjectionClassifierModel(resolved: ResolvedAgentModel): InjectionClassifierModel;
 /**

package/dist/cli/commands/tui.d.ts

@@ -1,36 +1,13 @@
-import type { AgentEvent } from "@earendil-works/pi-agent-core";
-import { AutoRAGAgent, type AutoRAGAgentOptions } from "../../agent/agent.js";
-import { type CliConfig, type ResolvedAgentModel } from "../config.js";
-import { type TuiSessionRecord, type TuiSessionStore } from "../tui-session-store.js";
 import type { CommandContext } from "./types.js";
-export { parseSlashCommand } from "../tui-commands.js";
-export interface TuiDriver {
-    submissions: string[];
-    rendered: string[];
-    started: boolean;
-    stopped: boolean;
-    onSubmit?: (text: string) => void | Promise<void>;
-    onExit?: () => void;
-    onEvent?: (event: AgentEvent) => void;
-    onInput?: (data: string) => void;
-}
-export interface TuiPresenter {
-    handle(event: AgentEvent): void;
-    lines(): readonly string[];
-    working(): boolean;
-    setWorking(active: boolean): void;
-    beginRun(): void;
-    interrupt(): void;
-    status(): string;
-    reset(): void;
-}
-type TuiAgent = Pick<AutoRAGAgent, "searchDocumentsStream"> & Partial<Pick<AutoRAGAgent, "subscribe" | "abort">>;
-export interface TuiDeps {
-    agentFactory?: (opts?: Partial<AutoRAGAgentOptions>) => TuiAgent;
-    modelResolver?: (config: CliConfig) => ResolvedAgentModel;
-    tuiFactory?: (ctx: CommandContext) => TuiDriver;
-    sessionStore?: TuiSessionStore;
-}
-export declare function createTuiPresenter(): TuiPresenter;
-export declare function renderTuiSessionView(session: TuiSessionRecord | undefined, input: string): string;
-export declare function runTui(ctx: CommandContext, deps?: TuiDeps): Promise<number>;
+/**
+ * Run `autorag tui`: Pi's interactive mode over the AutoRAG librarian.
+ *
+ * Pi owns the terminal UI, `read`/`bash`/`edit`/`write`/`grep`/`find`/`ls`
+ * tools, provider credentials/OAuth, model selection, session persistence and
+ * resume/fork/compaction, settings, and extension loading. AutoRAG registers
+ * its domain tools and streams progress, preliminary answers, and final results
+ * into the same session through the agent's interactive runtime. The native
+ * `/login`, `/model`, `/resume`, `/new`, `/tree`, `/compact`, and `/settings`
+ * commands are therefore always available.
+ */
+export declare function runTui(ctx: CommandContext): Promise<number>;

package/dist/cli/config.d.ts

@@ -1,4 +1,5 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import type { AutoRAGAgentOptions, AutoRAGRetrievalLimits } from "../agent/agent.js";
 import { type LoadLocalAutoRAGModelOptions } from "../agent/local-model.js";
 import type { DatasourceAccessContextOptions } from "../datasource/access-context.js";
@@ -207,7 +208,18 @@ export declare function resolveConfigReadOnly(input: ResolveConfigInput): CliCon
 /** Normalize and validate the `rerank` config section, filling in defaults. */
 export declare function normalizeRerankConfig(raw: unknown, path: string): RerankConfig | false;
 export declare function buildAgentOptions(config: CliConfig): Omit<AutoRAGAgentOptions, "model">;
-export declare function resolveModel(config: CliConfig): Model<Api>;
+/**
+ * Extra resolution inputs beyond the local codex-runtime options. `agentDir`
+ * points at the pi agent home (`~/.pi/agent` by default) that owns
+ * `auth.json`, `models.json`, and `settings.json`.
+ */
+export interface ResolveAgentModelOptions extends LoadLocalAutoRAGModelOptions {
+    readonly agentDir?: string;
+    readonly cwd?: string;
+    /** Pre-built pi model runtime, for callers that already own one (and tests). */
+    readonly runtime?: ModelRuntime;
+}
+export declare function resolveModel(config: CliConfig, options?: ResolveAgentModelOptions): Promise<Model<Api>>;
 export interface ResolvedAgentModel {
     readonly model: Model<Api>;
     readonly apiKey?: string;
@@ -216,7 +228,7 @@ export interface ResolvedAgentModel {
 export type AgentModelResolutionSource = "config" | "flags" | "env" | "local_runtime" | "catalog" | "configured_alias" | "mixed";
 export interface AgentModelAuth {
     readonly present: boolean;
-    readonly source: "env" | "local_runtime" | "catalog" | "none" | "unknown";
+    readonly source: "env" | "local_runtime" | "pi_auth" | "catalog" | "none" | "unknown";
     readonly envName?: string;
 }
 export interface ResolvedAgentModelRole {
@@ -240,8 +252,8 @@ export interface ResolvedAgentModelDetailed {
     readonly providerApiKeys?: Readonly<Record<string, string>>;
     readonly role: ResolvedAgentModelRole;
 }
-export declare function resolveAgentModel(config: CliConfig, localOptions?: LoadLocalAutoRAGModelOptions): ResolvedAgentModel;
-export declare function resolveAgentModelDetailed(config: CliConfig, localOptions?: LoadLocalAutoRAGModelOptions): ResolvedAgentModelDetailed;
+export declare function resolveAgentModel(config: CliConfig, options?: ResolveAgentModelOptions): Promise<ResolvedAgentModel>;
+export declare function resolveAgentModelDetailed(config: CliConfig, options?: ResolveAgentModelOptions): Promise<ResolvedAgentModelDetailed>;
 export declare function readRawConfigObject(path: string): Record<string, unknown>;
 /** Atomically replace a config file, preserving the caller's JSON object. */
 export declare function writeConfigObject(path: string, config: unknown): void;