@autorag/librarian 2.6.3 → 2.8.0

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

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

package/dist/agent/query-decomposition.d.ts

@@ -0,0 +1,25 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+/** Hard cap on search queries one question may decompose into. */
+export declare const MAX_DECOMPOSED_QUERIES = 5;
+/** Prompt in, raw completion text out. The seam the decomposer calls. */
+export type DecompositionCompleter = (prompt: string) => Promise<string>;
+/** A pi-ai model plus the credential used only for decomposition calls. */
+export interface DecompositionModel {
+    readonly model: Model<Api>;
+    readonly apiKey?: string;
+}
+export declare function buildDecompositionPrompt(query: string): string;
+/**
+ * Parse the model's reply into at most {@link MAX_DECOMPOSED_QUERIES} unique,
+ * non-empty queries. Accepts `{"queries": [...]}`, a bare array (optionally
+ * fenced or wrapped in prose), or one query per line as a last resort.
+ */
+export declare function parseDecomposedQueries(text: string): string[];
+/**
+ * Decompose one question into up to {@link MAX_DECOMPOSED_QUERIES} search
+ * queries. A reply with no usable query falls back to the original question,
+ * so the caller always has something to search.
+ */
+export declare function decomposeQuery(complete: DecompositionCompleter, query: string): Promise<string[]>;
+/** Completer over a pi-ai model: one user turn, thinking off, short output. */
+export declare function createModelDecompositionCompleter(target: DecompositionModel, signal?: AbortSignal): DecompositionCompleter;

package/dist/agent/query-routing.d.ts

@@ -0,0 +1,54 @@
+import type { JevJudge } from "./jev-extension.js";
+/**
+ * Where a user question is answered from:
+ * - `local`: information only the user can reach (their files, chats, mail).
+ * - `web`: public information one internet search would answer.
+ * - `direct`: general knowledge or small talk the model answers on its own.
+ */
+export type QueryRoute = "local" | "web" | "direct";
+/** Jev question id of the three-way branch. */
+export declare const QUERY_ROUTE_QUESTION_ID = "route";
+/** Jev question id of the "does this need decomposition?" check. */
+export declare const DECOMPOSE_QUESTION_ID = "decompose";
+/** Jev question id of the post-fast-answer "needs follow-up?" check. */
+export declare const FOLLOW_UP_QUESTION_ID = "follow_up";
+/** Route used whenever Jev gives no usable branch: today's local search. */
+export declare const FALLBACK_QUERY_ROUTE: QueryRoute;
+/** A `noul` probability at or above this asks for question decomposition. */
+export declare const DECOMPOSE_PROBABILITY_THRESHOLD = 0.5;
+/** A `noul` probability at or above this sends the fast answer on to verification. */
+export declare const FOLLOW_UP_PROBABILITY_THRESHOLD = 0.5;
+export interface FollowUpDecision {
+    /** True when the run continues into the verification phase. */
+    readonly followUp: boolean;
+    /** Jev's P(follow-up needed), when it answered. */
+    readonly probability?: number;
+    /** Why the check fell back to verifying instead of following Jev; absent when Jev decided. */
+    readonly fallbackReason?: string;
+}
+/**
+ * Ask Jev whether the fast answer needs correction, clarification, or further
+ * research. Never throws: a missing credential, an unreachable backend, or a
+ * verdict with no probability keeps verifying, because ending early on an
+ * unchecked answer is the costlier mistake.
+ */
+export declare function needsFollowUp(judge: JevJudge, query: string, answer: string): Promise<FollowUpDecision>;
+export interface QueryRouteDecision {
+    /** Most probable branch; {@link FALLBACK_QUERY_ROUTE} when Jev gave none. */
+    readonly route: QueryRoute;
+    /** True when Jev judged the question needs decomposition (never for `direct`). */
+    readonly decompose: boolean;
+    /** Probability Jev gave the chosen branch, when it reported a distribution. */
+    readonly routeProbability?: number;
+    /** Jev's P(decomposition needed), when it answered. */
+    readonly decomposeProbability?: number;
+    /** Why the decision fell back instead of following Jev; absent when Jev decided. */
+    readonly fallbackReason?: string;
+}
+/**
+ * Ask Jev, in one batched call about the user question, which branch answers
+ * it and whether it needs decomposition. Never throws: a missing credential,
+ * an unreachable backend, or an unusable verdict falls back to a single local
+ * search, with the reason recorded.
+ */
+export declare function routeQuery(judge: JevJudge, query: string): Promise<QueryRouteDecision>;

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

@@ -10,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" | "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" | "parser-warning" | "duplicate-excluded" | "unsupported-file" | "stale-index" | "deleted-mirror" | "pdf-extract-thin" | "retrieval-method-failed" | "rerank-failed" | "jikji-unavailable" | "jikji-prepare-failed" | "jikji-find-failed" | "everything-index-failed" | "fsearch-index-failed" | "fsearch-binary-missing" | "refresh-failed" | "refresh-interrupted" | "watch-failed" | "watch-limited" | "unknown-datasource-skill" | "missing-final-emit" | "model-request-failed";
+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" | "parser-warning" | "duplicate-excluded" | "unsupported-file" | "stale-index" | "deleted-mirror" | "pdf-extract-thin" | "retrieval-method-failed" | "rerank-failed" | "jikji-unavailable" | "jikji-prepare-failed" | "jikji-find-failed" | "everything-index-failed" | "fsearch-index-failed" | "fsearch-binary-missing" | "refresh-failed" | "refresh-interrupted" | "watch-failed" | "watch-limited" | "unknown-datasource-skill" | "missing-final-emit" | "model-request-failed" | "query-routed" | "query-route-fallback" | "query-decomposition-failed" | "follow-up-skipped" | "follow-up-check-fallback" | "citation-without-result";
 export interface SearchDocumentDiagnostic {
     readonly code: SearchDocumentDiagnosticCode;
     readonly severity: SearchDocumentDiagnosticSeverity;
@@ -107,5 +107,5 @@ export declare function createEmptySearchDocumentsResponse(sessionId: string, qu
 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 declare function recordNumberedFeedback(sessions: ReadonlySearchSessions, memory: RetrievalMemory, sessionId: string, usefulNumbers: readonly number[], notUsefulNumbers: readonly number[]): boolean;
 export {};

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

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

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

@@ -1,3 +1,25 @@
+import type { MemorySchemaV4 } from "../../memory/memory.js";
 import type { CommandContext } from "./types.js";
+interface EvidenceView {
+    readonly stableEvidenceId: string;
+    readonly method: string;
+    readonly source: string;
+    readonly excerpt?: string;
+    readonly content?: string;
+    readonly retrievalResultId?: string;
+    readonly chunkIndex?: number;
+    readonly lineNumber?: number;
+    readonly metadata?: Record<string, unknown>;
+}
+export declare function evidenceFor(schema: MemorySchemaV4, sessionId: string, resultNumber?: number): {
+    sessionId: string;
+    results: {
+        number: number;
+        title: string;
+        summary: string;
+        chunks: EvidenceView[];
+    }[];
+};
 /** Show the persisted source/chunk evidence attached to a search session. */
 export declare function runEvidence(ctx: CommandContext): Promise<number>;
+export {};

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/init.d.ts

@@ -4,6 +4,7 @@ import type { CommandContext } from "./types.js";
  * Model flags are folded into the generated config. A legacy
  * `autorag.config.json` in the current working directory may be migrated
  * non-destructively. An existing home config is not overwritten without
- * `--force`.
+ * `--force`, and `--force` only replaces an existing config when the caller
+ * selected the path explicitly (`--config` or `AUTORAG_CONFIG`).
  */
 export declare function runInit(ctx: CommandContext): Promise<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/commands/update-check.d.ts

@@ -0,0 +1,8 @@
+import { type AutoRAGUpdateResult } from "../update-check.js";
+import type { CommandContext } from "./types.js";
+export interface UpdateCheckDeps {
+    readonly currentVersion?: string;
+    readonly check?: (currentVersion: string) => Promise<AutoRAGUpdateResult>;
+}
+/** `autorag update-check`: compare the running package against the npm registry. */
+export declare function runUpdateCheck(ctx: CommandContext, deps?: UpdateCheckDeps): Promise<number>;

package/dist/cli/config.d.ts

@@ -1,6 +1,9 @@
 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 { JevBackendName } from "../agent/jev-extension.js";
 import { type LoadLocalAutoRAGModelOptions } from "../agent/local-model.js";
+import type { DecompositionModel } from "../agent/query-decomposition.js";
 import type { DatasourceAccessContextOptions } from "../datasource/access-context.js";
 import { type DatasourcesConfig } from "../datasource/skills/factory.js";
 import type { EnsureMinSyncBinaryOptions, MinSyncEmbedderConfig } from "../minsync/index.js";
@@ -50,6 +53,26 @@ export interface WebSearchCliConfig {
         timeoutSeconds?: number;
     } | false;
 }
+/**
+ * Jev decision-tool config. Absent disables the tool; `enabled: false` disables
+ * it explicitly. Secrets never appear here: the `jev-use` engine reads the
+ * backend credential from its own environment variable (`TYPESAFE_API_KEY`,
+ * `OPENROUTER_API_KEY`, or `AI_GATEWAY_API_KEY`).
+ */
+export interface JevCliConfig {
+    enabled?: boolean;
+    /** Force one backend; omit to let the first credential present win. */
+    backend?: JevBackendName;
+    /** Model id sent with every call, e.g. `jev-latest`. */
+    model?: string;
+    /** Escalate verdicts below this confidence (0-1). Default: per-source thresholds. */
+    confidenceThreshold?: number;
+}
+/** Question-decomposition config. Secrets stay in env/pi auth like the main model. */
+export interface QueryDecompositionConfig {
+    /** Dedicated decomposition model; same shape and auth rules as the top-level `model`. */
+    model?: AgentModelConfig;
+}
 /**
  * Post-merge reranking config. Routes merged evidence through a dedicated
  * rerank model. `provider` is `openrouter` today; `model` is the OpenRouter
@@ -67,7 +90,7 @@ export interface RerankConfig {
     apiKeyEnv?: string;
     /** Override the provider base URL (e.g. a gateway). */
     baseUrl?: string;
-    /** Return only the top N merged results. Omitted ⇒ all distinct results are reordered. */
+    /** Return only the top N merged results. @default 25 (DEFAULT_RERANK_TOP_N) */
     topN?: number;
     /** Per-request timeout in milliseconds. */
     timeoutMs?: number;
@@ -144,6 +167,21 @@ export interface CliConfig {
         watch?: boolean;
     } | false;
     webSearch?: WebSearchCliConfig;
+    /**
+     * Jev query routing (local / web / direct), the decomposition check, the
+     * post-fast-answer follow-up check, and the `jev` tool. On by default with
+     * the OpenRouter backend; `false` or `enabled: false` disables it. Secrets
+     * never appear here: `jev-use` reads the backend key from its own
+     * environment variable.
+     */
+    jev?: JevCliConfig | false;
+    /**
+     * Question decomposition for the Jev query pipeline. `model` names the LLM
+     * that splits one question into at most five search queries; absent or `{}`
+     * uses {@link DEFAULT_QUERY_DECOMPOSITION_MODEL}, and `false` lets the
+     * agent's own model decompose.
+     */
+    queryDecomposition?: QueryDecompositionConfig | false;
     /** Post-merge reranking. Absent ⇒ reranking disabled. `false` disables it. */
     rerank?: RerankConfig | false;
     parserOptions?: Record<string, unknown>;
@@ -204,10 +242,34 @@ export declare function resolveConfig(input: ResolveConfigInput): CliConfig;
  * would resolve them but never copied into `~/.autorag/config.json`.
  */
 export declare function resolveConfigReadOnly(input: ResolveConfigInput): CliConfig;
+/** Validate and normalize the `jev` config section. */
+export declare function normalizeJevConfig(raw: unknown): JevCliConfig;
+/** Jev backend used when the config names none (absent section or `{}`). */
+export declare const DEFAULT_JEV_BACKEND: JevBackendName;
+/**
+ * Question-decomposition model used when the config names none. Picked from a
+ * live OpenRouter bench (6 questions incl. Korean, 2 runs each): 12/12 valid,
+ * covering, language-preserving decompositions at ~0.9s p50, about 3.5x
+ * cheaper per call than google/gemini-2.5-flash-lite at equal quality.
+ */
+export declare const DEFAULT_QUERY_DECOMPOSITION_MODEL: AgentModelConfig;
+/** Validate the `queryDecomposition` config section (`false` = decompose with the session model). */
+export declare function normalizeQueryDecompositionConfig(raw: unknown): QueryDecompositionConfig | false;
 /** 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 +278,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 +302,15 @@ 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>;
+/**
+ * Resolve the question-decomposition model and its credential through the same
+ * chain as the agent model. An absent section or `{}` uses
+ * {@link DEFAULT_QUERY_DECOMPOSITION_MODEL}; `queryDecomposition: false`
+ * returns undefined so the agent's own model decomposes.
+ */
+export declare function resolveQueryDecompositionModel(config: CliConfig, options?: ResolveAgentModelOptions): Promise<DecompositionModel | undefined>;
+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;
@@ -250,4 +319,12 @@ export declare function writeDefaultConfig(path: string, partial: Partial<CliCon
     atomicCreate?: boolean;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+    /**
+     * Whether the target path was selected explicitly by the caller
+     * (`--config` / `AUTORAG_CONFIG`). When `false`, `force` refuses to
+     * replace an existing file: an implicit home config may only be
+     * replaced through an explicit config path. `undefined` (callers that
+     * do not distinguish) keeps the historical force semantics.
+     */
+    explicit?: boolean;
 }): void;

package/dist/cli/index.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-declare const COMMANDS: readonly ["init", "setup", "refresh", "status", "search", "feedback", "evidence", "memory", "index", "watch", "health", "duplicates", "tui", "serve", "p2p", "lite", "models", "gateway"];
+declare const COMMANDS: readonly ["init", "setup", "refresh", "status", "search", "feedback", "evidence", "memory", "index", "watch", "health", "duplicates", "tui", "serve", "p2p", "lite", "models", "gateway", "update-check"];
 type CommandName = (typeof COMMANDS)[number];
 export type { CommandName };
 interface ParsedArgs {