@autorag/librarian 2.7.0 → 2.9.0

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

@@ -1,11 +1,12 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
 import type { RetrievalDiagnostic, RetrievalResult } from "../retrieval/types.js";
+import { EvidenceLedger } from "./evidence-ledger.js";
 import { type SearchDocumentRetrievalTraceResult } from "./search-documents.js";
 /**
  * Per-datasource search tools.
  *
- * One tool is generated per authorized datasource connection (e.g.
+ * One tool is generated per configured datasource connection (e.g.
  * `search_datasource_discord`, or `search_datasource_kakao_work` for a
  * `kakao-work` account alias). Its execution registers only that connection's
  * retrieval methods with the retriever, so no other datasource CLI is spawned
@@ -14,13 +15,13 @@ import { type SearchDocumentRetrievalTraceResult } from "./search-documents.js";
  * These generated tools are the only model-facing datasource retrieval
  * surface. Cross-datasource fan-out belongs to `search_all_documents`, which
  * already spans every configured retrieval method — including datasources — so
- * a datasource-only fan-out tool would be redundant. Every authorized
+ * a datasource-only fan-out tool would be redundant. Every configured
  * connection must therefore appear here; a datasource with no generated tool
  * would become unreachable except through the full fan-out.
  *
- * Tools are generated from the configured, access-authorized datasource skills
- * at agent construction, so a datasource that is disabled in config or denied
- * by the trusted access context never appears in the tool list.
+ * Tools are generated from the configured datasource skills at agent
+ * construction; a connection not present in the config never appears in the
+ * tool list.
  */
 export declare const SEARCH_SINGLE_DATASOURCE_TOOL_PREFIX = "search_datasource_";
 /** Model-visible tool name for one datasource connection. */
@@ -31,7 +32,7 @@ export interface SingleDatasourceToolSpec {
     readonly datasourceId: string;
     /** Operator/descriptor-authored context shown in the tool description. */
     readonly description: string;
-    /** Authorized instance roots (e.g. `/kakao/personal`) for the description. */
+    /** Instance roots (e.g. `/kakao/personal`) for the description. */
     readonly instanceScopes: readonly string[];
 }
 export interface SingleDatasourceSearchProvider {
@@ -52,12 +53,12 @@ export interface SearchSingleDatasourceDetails {
     /** Top candidates in traceable shape (additive; used for the run's retrieval trace). */
     readonly results?: readonly SearchDocumentRetrievalTraceResult[];
 }
-export declare function createSingleDatasourceSearchTools(provider: SingleDatasourceSearchProvider, specs: readonly SingleDatasourceToolSpec[]): AgentTool<typeof searchSingleDatasourceSchema, SearchSingleDatasourceDetails>[];
+export declare function createSingleDatasourceSearchTools(provider: SingleDatasourceSearchProvider, specs: readonly SingleDatasourceToolSpec[], ledger?: EvidenceLedger): AgentTool<typeof searchSingleDatasourceSchema, SearchSingleDatasourceDetails>[];
 declare const searchSingleDatasourceSchema: Type.TObject<{
     query: Type.TString;
     topK: Type.TOptional<Type.TInteger>;
     scope: Type.TOptional<Type.TString>;
 }>;
 /** Shared rendering for datasource search tool results (fan-out removed). */
-export declare function formatDatasourceResults(results: readonly RetrievalResult[], diagnostics: readonly RetrievalDiagnostic[]): string;
+export declare function formatDatasourceResults(results: readonly RetrievalResult[], diagnostics: readonly RetrievalDiagnostic[], evidenceIds: readonly string[]): string;
 export {};

package/dist/agent/self-config.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Host opt-in for agent self-configuration: the Jev `config` branch, where the
+ * agent edits its own settings with the full `autorag-setup` skill in hand.
+ */
+export interface SelfConfigOptions {
+    /** The active AutoRAG config file the agent may read and edit. */
+    readonly configPath: string;
+    /** Override for the `autorag-setup` SKILL.md; defaults to the packaged skill. */
+    readonly skillPath?: string;
+    /**
+     * Check the config file after a config turn changed it. Resolves to a
+     * problem description when the file no longer works, or `undefined` when it
+     * is fine. A reported problem restores the pre-turn file.
+     */
+    readonly validate?: (configPath: string) => Promise<string | undefined>;
+}
+/** Full text of the `autorag-setup` skill with its YAML front matter removed. */
+export declare function loadSetupSkill(skillPath?: string): string;
+export interface SelfConfigPromptInput {
+    readonly query: string;
+    readonly configPath: string;
+    readonly agentDir: string;
+    readonly skill: string;
+}
+/** The config file's current text, or `undefined` when it does not exist. */
+export declare function snapshotConfigFile(configPath: string): string | undefined;
+/**
+ * After a config turn: when the model changed the file and the host's
+ * `validate` says the result no longer works, put the pre-turn text back.
+ * Returns the problem that triggered the rollback, or `undefined` when the
+ * file is unchanged, valid, or the host supplied no validator. An unchanged
+ * file is never touched, even if it was already invalid before the turn.
+ */
+export declare function rollbackIfBroken(options: SelfConfigOptions, before: string | undefined): Promise<string | undefined>;
+/**
+ * The turn prompt for the `config` branch: the whole setup skill, where this
+ * run's config lives, the safety rules for editing it, and the user's request.
+ * The turn ends with `emit_autorag_results`; there is no fast answer.
+ */
+export declare function buildSelfConfigPrompt(input: SelfConfigPromptInput): string;

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

@@ -1,13 +1,13 @@
-import type { Skill } from "@earendil-works/pi-agent-core";
 import type { StoreManifest } from "../manifest/types.js";
+import type { DatasourceAgentSkill } from "./datasource-skill.js";
 export interface SystemPromptConfig {
     toolNames: string[];
     modelId?: string;
-    memorySignalCount?: number;
     memoryEntries?: readonly unknown[];
     manifests: StoreManifest[];
     jikjiIndexingEnabled?: boolean;
-    datasourceSkills?: readonly Skill[];
+    datasourceSkills?: readonly DatasourceAgentSkill[];
     retrievedContentGuard?: boolean;
+    remoteSession?: boolean;
 }
 export declare function buildSystemPrompt(config: SystemPromptConfig): string;

package/dist/agent/web-fetch-tool.d.ts

@@ -9,6 +9,7 @@
  */
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
+import { EvidenceLedger } from "./evidence-ledger.js";
 export declare const WEB_FETCH_TOOL_NAME = "web_fetch";
 declare const webFetchSchema: Type.TObject<{
     url: Type.TString;
@@ -28,5 +29,5 @@ export interface WebFetchToolDetails {
     readonly available: boolean;
     readonly error?: string;
 }
-export declare function createWebFetchTool(options?: WebFetchToolOptions): AgentTool<typeof webFetchSchema, WebFetchToolDetails>;
+export declare function createWebFetchTool(options?: WebFetchToolOptions, ledger?: EvidenceLedger): AgentTool<typeof webFetchSchema, WebFetchToolDetails>;
 export {};

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

@@ -13,6 +13,7 @@ import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
 import type { ModelNativeSearchAuth } from "../web/search/model-auth.js";
 import type { SearchProviderId } from "../web/search/types.js";
+import { EvidenceLedger } from "./evidence-ledger.js";
 export declare const WEB_SEARCH_TOOL_NAME = "web_search";
 declare const webSearchSchema: Type.TObject<{
     query: Type.TString;
@@ -44,5 +45,5 @@ export interface WebSearchToolDetails {
     readonly available: boolean;
     readonly error?: string;
 }
-export declare function createWebSearchTool(options?: WebSearchToolOptions): AgentTool<typeof webSearchSchema, WebSearchToolDetails>;
+export declare function createWebSearchTool(options?: WebSearchToolOptions, ledger?: EvidenceLedger): AgentTool<typeof webSearchSchema, WebSearchToolDetails>;
 export {};

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

@@ -1,3 +1,25 @@
+import type { MemorySchema } 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: MemorySchema, 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/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/memory.d.ts

@@ -1,7 +1,7 @@
 import type { CommandContext } from "./types.js";
 /**
  * `autorag memory inspect` — render a path-opaque snapshot of the retrieval
- * memory (curated results, feedback signals, insights, signal defaults).
+ * memory (judged evidence, curated results, evidence chunks, insights).
  * Model-free. The memory file is resolved from config and loaded read-only;
  * only the rendered schema is emitted, never the storage path.
  */

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

@@ -1,6 +1,6 @@
 import { type AutoRAGResultsDetails } from "../../agent/emit-results-tool.js";
 import type { CommandContext } from "./types.js";
-/** Validate a curated report payload against the `emit_autorag_results` contract. */
+/** Validate a curated report payload against the `autorag report` contract (explicit number -> source mapping). */
 export declare function validateReport(value: unknown): AutoRAGResultsDetails;
 /** Persist a structured report submitted by an external curator. */
 export declare function runReport(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,8 +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 { DatasourceAccessContextOptions } from "../datasource/access-context.js";
+import type { DecompositionModel } from "../agent/query-decomposition.js";
 import { type DatasourcesConfig } from "../datasource/skills/factory.js";
 import type { EnsureMinSyncBinaryOptions, MinSyncEmbedderConfig } from "../minsync/index.js";
 export declare const DEFAULT_CONFIG_FILENAME = "config.json";
@@ -17,7 +18,8 @@ export declare class ConfigError extends Error {
  * the MinSync vector embedder settings validated by {@link normalizeEmbedder}.
  */
 export interface MinSyncMethodConfig {
-    enabled?: boolean;
+    /** Accepted as `true` so existing configs load; `false` is rejected, MinSync is required. */
+    enabled?: true;
     autoInstall?: boolean;
     workspacePath?: string;
     maxChunkSize?: number;
@@ -51,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
@@ -68,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;
@@ -121,6 +143,8 @@ export interface AgentModelConfig {
     maxTokens?: number;
 }
 export interface CliConfig {
+    /** Absolute path of the config file this config was resolved from (it may not exist yet). */
+    configPath?: string;
     searchPaths: string[];
     workspacePath: string;
     memoryPath: string;
@@ -145,6 +169,21 @@ export interface CliConfig {
         watch?: boolean;
     } | false;
     webSearch?: WebSearchCliConfig;
+    /**
+     * Jev query routing (direct / local), 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>;
@@ -158,10 +197,8 @@ export interface CliConfig {
     excludePaths?: string[];
     /** Hard caps on retrieval, baseline prefetch, and model-facing candidate lists. */
     limits?: AutoRAGRetrievalLimits;
-    /** Trusted datasource skill configuration (skill name → config). */
+    /** Datasource skill configuration (skill name → config). */
     datasources?: DatasourcesConfig;
-    /** Trusted datasource allow-tags/allow-scopes. Absent ⇒ default-deny. */
-    datasourceAccess?: DatasourceAccessContextOptions;
     /** P2P sharing configuration. Disabled by default. */
     p2p?: P2pConfig;
 }
@@ -189,8 +226,8 @@ export declare function normalizeEmbedder(raw: unknown, path: string): MinSyncEm
  * Normalize raw indexing method config into a fully-populated shape.
  *
  * - `undefined` / missing key => `{ enabled: true, autoInstall: true }`
- * - `false` => `{ enabled: false }` (disabled marker)
  * - object merges with `enabled: true` default and is validated
+ * - `false` and `enabled: false` throw: MinSync is required
  *
  * Unknown fields, invalid embedder settings, and bad numeric values throw
  * {@link ConfigError}.
@@ -205,6 +242,19 @@ 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 the previous default (a 2025 Gemini 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">;
@@ -253,6 +303,21 @@ export interface ResolvedAgentModelDetailed {
     readonly role: ResolvedAgentModelRole;
 }
 export declare function resolveAgentModel(config: CliConfig, options?: ResolveAgentModelOptions): Promise<ResolvedAgentModel>;
+/**
+ * Check that a config file still resolves to a callable model, the way the
+ * next `autorag` launch will read it: invalid JSON, a schema error, or a model
+ * id that neither the pi catalog nor a declared endpoint knows is a problem.
+ * A missing credential is not (that is `autorag health`'s `auth_missing`).
+ * Resolves to a problem description, or `undefined` when the config is fine.
+ */
+export declare function validateAgentConfigFile(configPath: string, options?: ResolveAgentModelOptions): Promise<string | undefined>;
+/**
+ * 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. */
@@ -262,4 +327,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", "evidence", "memory", "index", "watch", "health", "duplicates", "tui", "serve", "p2p", "lite", "models", "gateway", "update-check"];
 type CommandName = (typeof COMMANDS)[number];
 export type { CommandName };
 interface ParsedArgs {