@autorag/librarian 2.0.0

package/dist/agent/datasource-skill.d.ts

@@ -0,0 +1,45 @@
+import type { AgentTool, Skill } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+import type { DatasourceSkillManifest } from "../datasource/types.js";
+export declare const LOAD_DATASOURCE_SKILL_TOOL_NAME = "load_datasource_skill";
+/**
+ * Opaque, path-free location used as the Pi `Skill.filePath` for a datasource
+ * skill. Datasource skills have no real backing file, and AutoRAG must never
+ * expose real filesystem paths, so we use a `datasource://<name>` scheme.
+ */
+export declare function datasourceSkillLocation(name: string): string;
+/**
+ * Map a datasource skill manifest onto the Pi agent-skill layer. The resulting
+ * `Skill` is injected into the system prompt (name/description/location) for
+ * progressive disclosure and its `content` is loaded on demand.
+ */
+export declare function toDatasourceAgentSkill(manifest: DatasourceSkillManifest): Skill;
+/**
+ * Render the Pi `<available_skills>` progressive-disclosure block for the
+ * authorized datasource skills using Pi's own formatter, so datasource skills
+ * sit on the exact same layer as file-backed agent skills.
+ */
+export declare function buildDatasourceSkillsPrompt(skills: readonly Skill[]): string;
+/**
+ * Format the full instructions for a loaded datasource skill, matching Pi's
+ * `<skill …>` invocation shape but with a path-opaque location (no real
+ * filesystem reference, so no "references are relative to …" line).
+ */
+export declare function formatDatasourceSkillInvocation(skill: Skill): string;
+export interface LoadDatasourceSkillDetails {
+    readonly skill: string;
+    readonly loaded: boolean;
+}
+export interface DatasourceSkillProvider {
+    /**
+     * Resolve an authorized datasource skill by model-visible name. Returns
+     * `undefined` when the name is unknown or not authorized by the trusted,
+     * server-bound access context (default-deny).
+     */
+    loadDatasourceSkill(name: string): Skill | undefined;
+}
+declare const loadDatasourceSkillSchema: Type.TObject<{
+    name: Type.TString;
+}>;
+export declare function createLoadDatasourceSkillTool(provider: DatasourceSkillProvider): AgentTool<typeof loadDatasourceSkillSchema, LoadDatasourceSkillDetails>;
+export {};

package/dist/agent/emit-results-tool.d.ts

@@ -0,0 +1,75 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+export declare const EMIT_AUTORAG_RESULTS_TOOL_NAME = "emit_autorag_results";
+declare const emitResultsSchema: Type.TObject<{
+    answer: Type.TString;
+    results: Type.TArray<Type.TObject<{
+        number: Type.TInteger;
+        title: Type.TString;
+        summary: Type.TString;
+        evidence: Type.TArray<Type.TObject<{
+            excerpt: Type.TString;
+            lineNumber: Type.TOptional<Type.TInteger>;
+        }>>;
+        confidence: Type.TNumber;
+    }>>;
+    mapping: Type.TArray<Type.TObject<{
+        number: Type.TInteger;
+        source: Type.TString;
+        method: Type.TString;
+        content: Type.TString;
+        evidenceRefs: Type.TOptional<Type.TArray<Type.TObject<{
+            method: Type.TString;
+            source: Type.TString;
+            excerpt: Type.TOptional<Type.TString>;
+            content: Type.TOptional<Type.TString>;
+            retrievalResultId: Type.TOptional<Type.TString>;
+            chunkIndex: Type.TOptional<Type.TInteger>;
+            lineNumber: Type.TOptional<Type.TInteger>;
+            stableEvidenceId: Type.TOptional<Type.TString>;
+        }>>>;
+    }>>;
+    warnings: Type.TOptional<Type.TArray<Type.TString>>;
+}>;
+export interface AutoRAGEmittedEvidence {
+    readonly excerpt: string;
+    readonly lineNumber?: number;
+}
+export interface AutoRAGEmittedResult {
+    readonly number: number;
+    readonly title: string;
+    readonly summary: string;
+    readonly evidence: readonly AutoRAGEmittedEvidence[];
+    readonly confidence: number;
+}
+export interface AutoRAGEvidenceRef {
+    readonly method: string;
+    readonly source: string;
+    readonly excerpt?: string;
+    readonly content?: string;
+    readonly retrievalResultId?: string;
+    readonly chunkIndex?: number;
+    readonly lineNumber?: number;
+    readonly stableEvidenceId?: string;
+}
+export interface AutoRAGMappingEntry {
+    readonly number: number;
+    readonly source: string;
+    readonly method: string;
+    readonly content: string;
+    readonly evidenceRefs: readonly AutoRAGEvidenceRef[];
+}
+export interface AutoRAGResultsDetails {
+    readonly answer: string;
+    readonly results: readonly AutoRAGEmittedResult[];
+    readonly mapping: readonly AutoRAGMappingEntry[];
+    readonly warnings: readonly string[];
+}
+/**
+ * Builds the terminating structured-result tool. The model calls this exactly
+ * once as its final action; the typed `details` plus `terminate: true` end the
+ * Pi Agent run and hand the curated results back through `capture` — no
+ * assistant-text parsing involved.
+ */
+export declare function createEmitResultsTool(capture: (details: AutoRAGResultsDetails) => void): AgentTool<typeof emitResultsSchema, AutoRAGResultsDetails>;
+export {};

package/dist/agent/index.d.ts

@@ -0,0 +1,11 @@
+export type { AutoRAGAgentOptions, AutoRefreshOptions } from "./agent.js";
+export { AutoRAGAgent } from "./agent.js";
+export { buildDatasourceSkillsPrompt, createLoadDatasourceSkillTool, type DatasourceSkillProvider, datasourceSkillLocation, formatDatasourceSkillInvocation, LOAD_DATASOURCE_SKILL_TOOL_NAME, type LoadDatasourceSkillDetails, toDatasourceAgentSkill, } from "./datasource-skill.js";
+export type { AutoRAGEmittedResult, AutoRAGMappingEntry, AutoRAGResultsDetails, } from "./emit-results-tool.js";
+export { createEmitResultsTool, EMIT_AUTORAG_RESULTS_TOOL_NAME } from "./emit-results-tool.js";
+export { createJikjiFindTool, JIKJI_FIND_TOOL_NAME, type JikjiFindDetails, type JikjiFindPerRootPolicy, type JikjiFindProvider, type JikjiFindProviderResult, type MergedJikjiPolicy, } from "./jikji-find-tool.js";
+export { createSearchAllDocumentsTool, SEARCH_ALL_DOCUMENTS_TOOL_NAME, type SearchAllDocumentsDetails, type SearchAllDocumentsProvider, type SearchAllDocumentsResult, } from "./search-all-tool.js";
+export { createSearchDatasourceDocumentsTool, type DatasourceSearchProvider, SEARCH_DATASOURCE_DOCUMENTS_TOOL_NAME, type SearchDatasourceDocumentsDetails, } from "./search-datasource-tool.js";
+export type { SearchDocumentDiagnostic, SearchDocumentDiagnosticCode, SearchDocumentDiagnosticSeverity, SearchDocumentEvidence, SearchDocumentResult, SearchDocumentsResponse, SearchDocumentWarning, } from "./search-documents.js";
+export { createSearchMinSyncDocumentsTool, SEARCH_MINSYNC_DOCUMENTS_TOOL_NAME, type SearchMinSyncDocumentsDetails, } from "./search-minsync-tool.js";
+export { buildSystemPrompt, type SystemPromptConfig } from "./system-prompt.js";

package/dist/agent/jikji-find-tool.d.ts

@@ -0,0 +1,73 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+import type { JikjiAnswerPack, JikjiCandidate, JikjiDiagnostic, JikjiEvidence, JikjiHandoffAction } from "../jikji/index.js";
+export declare const JIKJI_FIND_TOOL_NAME = "jikji_find";
+/**
+ * Run-scoped merged policy assembled from per-root Jikji answer packs using
+ * least-privilege (restrictive-wins) semantics. Set on the agent after each
+ * `findJikji` call and consumed by the bash gate.
+ */
+export interface MergedJikjiPolicy {
+    readonly handoffAction: JikjiHandoffAction;
+    readonly stopAfterFind: boolean;
+    readonly forbiddenTools: readonly string[];
+    readonly allowedFollowups: readonly string[];
+    readonly agentShouldNotRerank: boolean;
+    readonly rawFallbackAllowed: boolean;
+}
+/**
+ * Per-root policy summary for one successful (ok) root, captured BEFORE the
+ * least-privilege merge. `root` is the configured search path string.
+ */
+export interface JikjiFindPerRootPolicy {
+    readonly root: string;
+    readonly handoffAction: JikjiHandoffAction;
+    readonly stopAfterFind: boolean;
+    readonly forbiddenTools: readonly string[];
+    readonly allowedFollowups: readonly string[];
+    readonly agentShouldNotRerank: boolean;
+}
+/** Result returned by the agent's `findJikji` provider method. */
+export interface JikjiFindProviderResult {
+    /** Merged answer pack with normalized paths, or undefined when unavailable. */
+    readonly answerPack: JikjiAnswerPack | undefined;
+    /** Merged policy, or undefined when jikji is unavailable (bash allowed). */
+    readonly policy: MergedJikjiPolicy | undefined;
+    readonly diagnostics: readonly JikjiDiagnostic[];
+    /** Search roots that were queried. */
+    readonly roots: readonly string[];
+    /** Per-root policy summaries for ok roots, before the merge. */
+    readonly perRoot: readonly JikjiFindPerRootPolicy[];
+}
+export interface JikjiFindProvider {
+    findJikji(query: string, opts?: {
+        readonly topK?: number;
+        readonly first?: boolean;
+    }): Promise<JikjiFindProviderResult>;
+}
+export interface JikjiFindDetails {
+    readonly method: "jikji_find";
+    readonly answerCount: number;
+    readonly handoffAction: JikjiHandoffAction | undefined;
+    readonly stopAfterFind: boolean | undefined;
+    readonly rawFallbackAllowed: boolean | undefined;
+    readonly sources: readonly string[];
+    readonly candidates: readonly JikjiCandidate[];
+    readonly evidencePack: readonly JikjiEvidence[];
+    readonly forbiddenTools: readonly string[];
+    readonly allowedFollowups: readonly string[];
+    readonly perRoot: readonly JikjiFindPerRootPolicy[];
+}
+declare const jikjiFindSchema: Type.TObject<{
+    query: Type.TString;
+    topK: Type.TOptional<Type.TInteger>;
+    first: Type.TOptional<Type.TBoolean>;
+}>;
+/**
+ * LLM-facing tool that calls Jikji `find` for local file discovery. The schema
+ * is model-safe and exposes no root paths: `{ query, topK?, first? }`. When
+ * Jikji is unavailable or all roots failed, the tool returns a short fallback
+ * message so the agent falls back to bash, and no policy is set.
+ */
+export declare function createJikjiFindTool(provider: JikjiFindProvider): AgentTool<typeof jikjiFindSchema, JikjiFindDetails>;
+export {};

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

@@ -0,0 +1,36 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+import type { RetrievalDiagnostic, RetrievalResult } from "../retrieval/types.js";
+export declare const SEARCH_ALL_DOCUMENTS_TOOL_NAME = "search_all_documents";
+declare const searchAllSchema: Type.TObject<{
+    query: Type.TString;
+    topK: Type.TOptional<Type.TInteger>;
+    scope: Type.TOptional<Type.TString>;
+}>;
+export interface SearchAllDocumentsResult {
+    readonly results: readonly RetrievalResult[];
+    readonly diagnostics: readonly RetrievalDiagnostic[];
+    readonly perMethodCounts?: Readonly<Record<string, number>>;
+}
+export interface SearchAllDocumentsProvider {
+    searchAllDocuments(query: string, options?: {
+        readonly topK?: number;
+        readonly scope?: string;
+    }): Promise<SearchAllDocumentsResult>;
+}
+export interface SearchAllDocumentsDetails {
+    readonly method: "search_all_documents";
+    readonly resultCount: number;
+    readonly sources: readonly string[];
+    readonly diagnostics: readonly RetrievalDiagnostic[];
+    readonly perMethodCounts?: Readonly<Record<string, number>>;
+}
+/**
+ * LLM-facing wrapper around multi-method merged retrieval. The
+ * schema accepts only `{ query, topK?, scope? }`; datasource trust fields such
+ * as `allowedTags`/`allowedScopes` are not part of the schema and are never
+ * forwarded to the provider — only `query`, `topK`, and `scope` are passed
+ * through, so model-provided extra properties cannot widen datasource access.
+ */
+export declare function createSearchAllDocumentsTool(provider: SearchAllDocumentsProvider): AgentTool<typeof searchAllSchema, SearchAllDocumentsDetails>;
+export {};

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

@@ -0,0 +1,18 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+import type { BM25Method, BM25Status } from "../retrieval/methods/bm25.js";
+export declare const SEARCH_BM25_DOCUMENTS_TOOL_NAME = "search_bm25_documents";
+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 declare function createSearchBM25DocumentsTool(getMethod: () => BM25Method | undefined): AgentTool<typeof searchBM25Schema, SearchBM25DocumentsDetails>;
+export {};

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

@@ -0,0 +1,26 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+import type { RetrievalDiagnostic, RetrievalResult } from "../retrieval/types.js";
+export declare const SEARCH_DATASOURCE_DOCUMENTS_TOOL_NAME = "search_datasource_documents";
+declare const searchDatasourceSchema: Type.TObject<{
+    query: Type.TString;
+    topK: Type.TOptional<Type.TInteger>;
+    scope: Type.TOptional<Type.TString>;
+}>;
+export interface SearchDatasourceDocumentsDetails {
+    readonly method: "datasource";
+    readonly resultCount: number;
+    readonly sources: readonly string[];
+    readonly diagnostics: readonly RetrievalDiagnostic[];
+}
+export interface DatasourceSearchProvider {
+    searchDatasourceDocuments(query: string, options?: {
+        readonly topK?: number;
+        readonly scope?: string;
+    }): Promise<{
+        readonly results: readonly RetrievalResult[];
+        readonly diagnostics: readonly RetrievalDiagnostic[];
+    }>;
+}
+export declare function createSearchDatasourceDocumentsTool(provider: DatasourceSearchProvider): AgentTool<typeof searchDatasourceSchema, SearchDatasourceDocumentsDetails>;
+export {};

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

@@ -0,0 +1,56 @@
+import { type RetrievalMemory } from "../memory/memory.js";
+import type { CuratedResult } from "../retrieval/types.js";
+import type { AutoRAGResultsDetails } from "./emit-results-tool.js";
+export type SearchDocumentWarning = "empty-query";
+export type SearchDocumentDiagnosticSeverity = "info" | "warning" | "error";
+/**
+ * Stable diagnostic codes surfaced through the public search
+ * response. The union is intentionally broad so later degraded-mode wiring
+ * (#21/#22) does not require another source-breaking type change; codes not yet
+ * emitted are still valid members.
+ */
+export type SearchDocumentDiagnosticCode = "empty-query" | "unknown-warning" | "caller-tool-dropped" | "bm25-unavailable" | "bm25-degraded-fallback" | "minsync-unavailable" | "parser-skipped" | "parser-failed" | "unsupported-file" | "stale-index" | "deleted-mirror" | "retrieval-method-failed" | "jikji-unavailable" | "jikji-prepare-failed" | "jikji-find-failed" | "refresh-failed" | "watch-failed" | "watch-limited";
+export interface SearchDocumentDiagnostic {
+    readonly code: SearchDocumentDiagnosticCode;
+    readonly severity: SearchDocumentDiagnosticSeverity;
+    readonly message: string;
+    /** Component label (e.g. "sanitizer", "bm25") or opaque virtual path — never a real filesystem path. */
+    readonly source?: string;
+}
+export interface SearchDocumentEvidence {
+    readonly excerpt: string;
+    readonly lineNumber?: number;
+}
+export interface SearchDocumentResult {
+    readonly number: number;
+    readonly title: string;
+    readonly summary: string;
+    readonly evidence: readonly SearchDocumentEvidence[];
+    readonly confidence: number;
+    readonly feedbackId: string;
+}
+export interface SearchDocumentsResponse {
+    readonly sessionId: string;
+    readonly query: string;
+    readonly results: readonly SearchDocumentResult[];
+    readonly answer: string;
+    readonly searched: number;
+    readonly warnings: readonly SearchDocumentWarning[];
+    /**
+     * Structured degraded-mode diagnostics. Typed optional for the compatibility
+     * window, but ALWAYS populated at runtime (defaults to an empty array).
+     */
+    readonly diagnostics?: readonly SearchDocumentDiagnostic[];
+}
+type SearchSessions = Map<string, {
+    query: string;
+    registry: Map<number, CuratedResult>;
+}>;
+type ReadonlySearchSessions = ReadonlyMap<string, {
+    query: string;
+    registry: ReadonlyMap<number, CuratedResult>;
+}>;
+export declare function createEmptySearchDocumentsResponse(sessionId: string, query: string, sessions: SearchSessions): SearchDocumentsResponse;
+export declare function recordStructuredResultsSession(sessionId: string, query: string, details: AutoRAGResultsDetails, sessions: SearchSessions, memory: RetrievalMemory, componentDiagnostics?: readonly SearchDocumentDiagnostic[]): SearchDocumentsResponse;
+export declare function recordNumberedFeedback(sessions: ReadonlySearchSessions, memory: RetrievalMemory, sessionId: string, usefulNumbers: readonly number[], notUsefulNumbers: readonly number[]): void;
+export {};

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

@@ -0,0 +1,24 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+import type { MinSyncVectorMethod } from "../minsync/method.js";
+export declare const SEARCH_MINSYNC_DOCUMENTS_TOOL_NAME = "search_minsync_documents";
+declare const searchMinSyncSchema: Type.TObject<{
+    query: Type.TString;
+    topK: Type.TOptional<Type.TInteger>;
+    scope: Type.TOptional<Type.TString>;
+}>;
+export interface SearchMinSyncDocumentsDetails {
+    readonly method: "search_minsync_documents";
+    readonly resultCount: number;
+    readonly sources: readonly string[];
+    readonly available: boolean;
+}
+/**
+ * LLM-facing wrapper around the {@link MinSyncVectorMethod} vector
+ * retrieval. The model can only supply `query`, `topK`, and an opaque `scope`.
+ * When the method is missing, the binary is missing, or retrieval errors, the
+ * tool returns a path-free unavailable message with `available: false` and a
+ * zero result count — never a real binary or workspace path.
+ */
+export declare function createSearchMinSyncDocumentsTool(getMethod: () => MinSyncVectorMethod | undefined): AgentTool<typeof searchMinSyncSchema, SearchMinSyncDocumentsDetails>;
+export {};

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

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

package/dist/agent/watch-refresh.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Filesystem watch scheduler for incremental refresh. Deliberately dependency-
+ * injected (via {@link WatcherFactory}) so it is unit-testable without real
+ * filesystem timing, and so the agent can pass a real `fs.watch`-backed factory.
+ *
+ * Invariants:
+ *  - Debounced: a burst of change events collapses into one refresh.
+ *  - Backpressure: at most one refresh in flight plus at most one pending rerun.
+ *  - Stoppable: after stop() no further refresh is scheduled and every watcher
+ *    is closed; late events are ignored.
+ *  - Bounded: never creates more than `maxWatchers` watchers.
+ */
+export interface WatchWatcher {
+    close(): void;
+}
+export type WatcherFactory = (dir: string, onChange: (filename: string | null) => void) => WatchWatcher;
+export interface WatchRefreshDeps {
+    readonly dirs: readonly string[];
+    readonly debounceMs: number;
+    readonly maxWatchers: number;
+    readonly watcherFactory: WatcherFactory;
+    readonly runRefresh: () => Promise<void>;
+    /** Called once when the number of directories exceeds `maxWatchers`. */
+    readonly onLimit?: () => void;
+}
+export interface WatchRefreshHandle {
+    stop(): void;
+}
+export declare function createWatchRefresh(deps: WatchRefreshDeps): WatchRefreshHandle;

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

@@ -0,0 +1,8 @@
+import type { CommandContext } from "./types.js";
+/**
+ * Run the `autorag feedback` command. Records per-result useful/not-useful
+ * signals against an existing curated-results session. Returns 0 when at least
+ * one feedback signal was applied, 2 for usage errors or an unknown session,
+ * 1 for runtime/IO errors.
+ */
+export declare function runFeedback(ctx: CommandContext): Promise<number>;

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

@@ -0,0 +1,146 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { LoadLocalAutoRAGModelsOptions } from "../../subagents/local-models.js";
+import { type CliConfig } from "../config.js";
+import type { CommandContext } from "./types.js";
+export type HealthCategory = "config" | "model_resolution" | "auth_missing" | "provider_unreachable" | "completion_failed" | "subagent_failed" | "timeout" | "ok";
+export type HealthRole = "orchestrator" | "explorer";
+export interface HealthCoverage {
+    modelProvider: boolean;
+    subagentDispatch: boolean;
+    retrievalTools: false;
+    searchCuration: false;
+    indexHealth: false;
+}
+export interface HealthRoleAuth {
+    present: boolean;
+    source: "env" | "local_runtime" | "pi_auth" | "catalog" | "none" | "unknown";
+    envName?: string;
+}
+export interface HealthRoleReport {
+    role: HealthRole;
+    provider: string;
+    modelId: string;
+    displayName?: string;
+    api: string;
+    routeFamily?: string;
+    baseUrl?: string;
+    contextWindow?: number;
+    maxTokens?: number;
+    capabilities: {
+        text: boolean;
+        image: boolean;
+        reasoning?: boolean;
+    };
+    auth: HealthRoleAuth;
+    resolutionSource: "config" | "flags" | "env" | "local_runtime" | "catalog" | "configured_alias" | "mixed";
+}
+export interface HealthProbeReport {
+    role: HealthRole;
+    skipped: boolean;
+    ok: boolean;
+    category: HealthCategory;
+    durationMs?: number;
+    message?: string;
+}
+export interface HealthConfigReport {
+    ok: boolean;
+    source: "explicit" | "home" | "legacy" | "defaults";
+    message?: string;
+}
+export interface HealthReportV1 {
+    healthSchemaVersion: 1;
+    ok: boolean;
+    category: HealthCategory;
+    command: "health";
+    probesSkipped: boolean;
+    coverage: HealthCoverage;
+    config: HealthConfigReport;
+    models: {
+        orchestrator?: HealthRoleReport;
+        explorer?: HealthRoleReport;
+    };
+    probes: {
+        orchestrator?: HealthProbeReport;
+        explorer?: HealthProbeReport;
+    };
+    indexHealth: {
+        separate: true;
+        command: "autorag status";
+        included: false;
+    };
+}
+/**
+ * Probe input passed to injected orchestrator/explorer probes. Credential
+ * values are present for the probe to use but must never be surfaced in
+ * rendered output.
+ */
+export interface ProbeInput {
+    role: HealthRole;
+    model: Model<Api>;
+    apiKey?: string;
+    providerApiKeys?: Readonly<Record<string, string>>;
+    timeoutMs: number;
+    cwd: string;
+}
+/**
+ * Probe outcome returned by injected probes. `category` is the per-role
+ * health category; `message` is already sanitized (no secrets/paths/stacks).
+ */
+export interface ProbeOutput {
+    ok: boolean;
+    category: HealthCategory;
+    message?: string;
+}
+/**
+ * Detailed role metadata produced by the model resolver. The default
+ * adapter derives this from {@link resolveAgentModel}; when config exports a
+ * dedicated `resolveAgentModelDetailed`, the health command prefers it.
+ */
+export interface ResolvedHealthRole {
+    readonly provider: string;
+    readonly modelId: string;
+    readonly displayName?: string;
+    readonly api: Api;
+    readonly baseUrl?: string;
+    readonly contextWindow?: number;
+    readonly maxTokens?: number;
+    readonly capabilities: {
+        input: readonly string[];
+        reasoning: boolean;
+    };
+    readonly auth: {
+        present: boolean;
+        source: "env" | "local_runtime" | "pi_auth" | "catalog" | "none" | "unknown";
+        envName?: string;
+    };
+    readonly resolutionSource: "config" | "flags" | "env" | "local_runtime" | "catalog" | "configured_alias" | "mixed";
+}
+export interface ResolvedHealthModel {
+    readonly model: Model<Api>;
+    readonly explorerModel: Model<Api>;
+    readonly apiKey?: string;
+    readonly providerApiKeys?: Readonly<Record<string, string>>;
+    readonly roles: {
+        orchestrator: ResolvedHealthRole;
+        explorer: ResolvedHealthRole;
+    };
+}
+export interface HealthDeps {
+    configResolver?: (input: {
+        flags: Record<string, string | boolean | undefined>;
+        cwd?: string;
+        env?: NodeJS.ProcessEnv;
+    }) => CliConfig;
+    modelResolver?: (config: CliConfig, localOptions?: LoadLocalAutoRAGModelsOptions) => ResolvedHealthModel;
+    orchestratorProbe?: (input: ProbeInput, signal: AbortSignal) => Promise<ProbeOutput>;
+    explorerProbe?: (input: ProbeInput, signal: AbortSignal) => Promise<ProbeOutput>;
+    now?: () => number;
+}
+/**
+ * Run the `autorag health` command. Returns an exit code and writes the
+ * rendered health report to `ctx.stdout` (or an error to `ctx.stderr`).
+ *
+ * All network/runtime behavior is injectable via `deps`; unit tests inject
+ * fake resolvers/probes and never touch live networks.
+ */
+export declare function runHealth(ctx: CommandContext, deps?: HealthDeps): Promise<number>;

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

@@ -0,0 +1,9 @@
+import type { CommandContext } from "./types.js";
+/**
+ * Run the `autorag index` command. `reset` removes the parsed mirror, BM25,
+ * and MinSync index directories under `.autorag` (preserving `bin`,
+ * `datasources`, and the memory file). `rebuild` resets then re-runs a forced
+ * refresh. Returns 0 on success, 2 for usage/decline errors, 1 for runtime
+ * errors including path-escape guard violations.
+ */
+export declare function runIndex(ctx: CommandContext): Promise<number>;

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

@@ -0,0 +1,9 @@
+import type { CommandContext } from "./types.js";
+/**
+ * `autorag init` writes the default config to `~/.autorag/config.json`.
+ * Role-specific 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`.
+ */
+export declare function runInit(ctx: CommandContext): Promise<number>;

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

@@ -0,0 +1,8 @@
+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).
+ * Model-free. The memory file is resolved from config and loaded read-only;
+ * only the rendered schema is emitted, never the storage path.
+ */
+export declare function runMemory(ctx: CommandContext): Promise<number>;

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

@@ -0,0 +1,19 @@
+import { type RefreshMethod } from "../../agent/agent.js";
+import type { CommandContext } from "./types.js";
+/**
+ * `autorag refresh` — parse configured search paths and resync every active
+ * index (parsed mirror, BM25, MinSync, datasources, jikji). Model-free: no LLM
+ * is constructed. Output is rendered through the path-opaque refresh renderer;
+ * the raw result (which carries absolute `indexPath`) is never printed.
+ *
+ * `--method bm25,minsync,parsed` restricts which methods run. When omitted, all
+ * methods run. Parsed mirrors are always synced when BM25 or MinSync is selected
+ * (they index over the parsed mirrors).
+ */
+export declare function runRefresh(ctx: CommandContext): Promise<number>;
+/**
+ * Parse a `--method` CSV flag into a sorted set of `RefreshMethod` values.
+ * Returns `undefined` when the flag is missing (meaning "all methods").
+ * `all` expands to every method. Unknown values throw.
+ */
+export declare function parseMethodFlag(flag: string | boolean | undefined): readonly RefreshMethod[] | undefined;

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

@@ -0,0 +1,34 @@
+import { AutoRAGAgent, type AutoRAGAgentOptions } from "../../agent/agent.js";
+import { type CliConfig, type ResolvedAgentModel } from "../config.js";
+import type { CommandContext } from "./types.js";
+/**
+ * A recoverable health hint surfaced when `autorag search` fails for a reason
+ * that `autorag health` can diagnose. The classifier only produces hints for
+ * model/provider/subagent failures — never for retrieval, index, datasource,
+ * or empty-query errors.
+ */
+export interface SearchHealthHint {
+    command: "autorag health";
+    reason: "model_resolution" | "subagent_failed" | "auth_missing" | "provider_unreachable" | "timeout";
+    message: string;
+}
+/**
+ * Classify a search error into an optional {@link SearchHealthHint}.
+ * Returns `undefined` for errors outside the allowlist (empty query,
+ * retrieval/index/datasource failures, generic errors).
+ */
+export declare function classifySearchHealthHint(error: unknown): SearchHealthHint | undefined;
+/**
+ * Search-command dependencies. Tests inject `agentFactory` to bypass real
+ * model construction and AutoRAGAgent instantiation, returning a stub whose
+ * `searchDocuments` resolves a canned {@link SearchDocumentsResponse}.
+ */
+export interface SearchDeps {
+    agentFactory?: (opts: AutoRAGAgentOptions) => Pick<AutoRAGAgent, "searchDocuments">;
+    modelResolver?: (config: CliConfig) => ResolvedAgentModel;
+}
+/**
+ * Run the `autorag search` command. Returns exit code 0 on success, 2 for
+ * usage/config errors (empty query, missing model), 1 for runtime errors.
+ */
+export declare function runSearch(ctx: CommandContext, deps?: SearchDeps): Promise<number>;