@autorag/librarian 2.10.6 → 2.12.0

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

@@ -0,0 +1,96 @@
+import type { ExtensionFactory, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+/** Where pi shows the progress widget: its own slot above the editor, where the submitted question lands. */
+export declare const SEARCH_PROGRESS_WIDGET_KEY = "autorag-search-progress";
+export type SearchProgressStatus = "running" | "done" | "failed";
+/** One unit of work the search is doing (routing, one retrieval source, a model phase, …). */
+export interface SearchProgressStep {
+    readonly id: string;
+    readonly label: string;
+    readonly status: SearchProgressStatus;
+    /** Outcome text: the result count, the route, or the failure's own message. */
+    readonly detail?: string;
+    readonly startedAt: number;
+    readonly endedAt?: number;
+}
+/** An immutable view of the running search, handed to subscribers on every change. */
+export interface SearchProgressSnapshot {
+    readonly active: boolean;
+    readonly query: string;
+    readonly startedAt: number;
+    /** A model turn streams: pi's own working loader is on screen then. */
+    readonly modelStreaming: boolean;
+    readonly steps: readonly SearchProgressStep[];
+}
+/** Options of {@link SearchProgressTracker.track}. */
+export interface TrackOptions<T> {
+    /** How many hits a settled job returned; the step reports the sum. */
+    readonly count?: (value: T) => number;
+}
+/**
+ * What the running search is doing right now, in the user's terms. The agent
+ * reports into it; the TUI renders it so a silent first retrieval is visibly
+ * alive. Reports outside a begun search are ignored, so the library path
+ * (`searchDocuments()` with no UI) pays nothing.
+ */
+export declare class SearchProgressTracker {
+    private active;
+    private query;
+    private startedAt;
+    private modelStreaming;
+    /** Bumped by every {@link begin}: a job that settles after its search ended must not touch the next one. */
+    private run;
+    private steps;
+    private readonly listeners;
+    private readonly now;
+    constructor(now?: () => number);
+    begin(query: string): void;
+    end(): void;
+    setModelStreaming(streaming: boolean): void;
+    /** Starts (or restarts) a step that the caller closes with {@link endStep}. */
+    beginStep(id: string, label: string): void;
+    endStep(id: string, status: Exclude<SearchProgressStatus, "running">, detail?: string): void;
+    /**
+     * Runs `work` as step `id`: running while it is in flight, done with
+     * `detail(value)` when it resolves, failed with the error's own message when
+     * it rejects (the rejection still propagates).
+     */
+    step<T>(id: string, label: string, work: () => Promise<T>, detail?: (value: T) => string | undefined): Promise<T>;
+    /**
+     * Follows one job as part of step `id`. Jobs sharing an id (the same source
+     * searched for several queries) form one step that ends when the last one
+     * settles. The job's result and rejection pass through untouched.
+     */
+    track<T>(id: string, label: string, work: Promise<T>, options?: TrackOptions<T>): Promise<T>;
+    snapshot(): SearchProgressSnapshot;
+    /** Notified after every change. Not called on subscribe: read {@link snapshot} for the current state. */
+    subscribe(listener: (snapshot: SearchProgressSnapshot) => void): () => void;
+    private open;
+    private emit;
+}
+/** `7s` under a minute, `1:01` after. */
+export declare function formatElapsed(ms: number): string;
+/** Colour hooks for {@link renderSearchProgress}; pi's theme supplies them, tests pass identity. */
+export interface SearchProgressPalette {
+    readonly accent: (text: string) => string;
+    readonly muted: (text: string) => string;
+    readonly success: (text: string) => string;
+    readonly error: (text: string) => string;
+}
+/**
+ * The widget's lines at time `now`. Pure so the TUI and the tests render the
+ * same thing: a spinner header with the elapsed time, then one line per step.
+ * More steps than fit keep every running step and the newest finished ones.
+ */
+export declare function renderSearchProgress(snapshot: SearchProgressSnapshot, now: number, palette: SearchProgressPalette, width: number, interruptKey: string): string[];
+/**
+ * Binds the tracker to pi's widget slot: the widget appears when a search
+ * begins and disappears when it ends. `isCurrent` lets a replaced session's
+ * late notifications be dropped.
+ */
+export declare function bindSearchProgressWidget(ui: Pick<ExtensionUIContext, "setWidget">, tracker: SearchProgressTracker, interruptKey: () => string): () => void;
+/**
+ * pi extension that shows the tracker as a widget while a search runs. The
+ * widget slot is rebound on every `session_start` (resume, `/new`, fork) and
+ * released on shutdown, so a replaced session is never written to.
+ */
+export declare function createSearchProgressExtension(tracker: SearchProgressTracker, interruptKey: () => string): ExtensionFactory;

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

@@ -21,6 +21,8 @@ export interface SelfConfigPromptInput {
     readonly configPath: string;
     readonly agentDir: string;
     readonly skill: string;
+    /** True when `manage_automations` is available: file-triggered automations are then in scope. */
+    readonly automations?: boolean;
 }
 /** The config file's current text, or `undefined` when it does not exist. */
 export declare function snapshotConfigFile(configPath: string): string | undefined;

package/dist/agent/user-requests.d.ts

@@ -0,0 +1,52 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+/** Custom session entry type under which a conversation persists what the user said. */
+export declare const USER_REQUEST_ENTRY_TYPE = "autorag.user-request";
+/**
+ * `request`: a new question or a follow-up. `steer`: a correction typed while a search runs, which
+ * adjusts the request it interrupts rather than starting a new one.
+ */
+export type UserRequestKind = "request" | "steer";
+export interface UserRequest {
+    readonly text: string;
+    readonly kind: UserRequestKind;
+}
+type SaveEntry = (request: UserRequest) => void;
+/**
+ * What the user has said in this conversation, in order, exactly as typed: the first question, every
+ * follow-up, every steer. AutoRAG's own phase prompts (fast answer, verification, direct answer, steer
+ * continuation) never enter it, because it is fed where the user's words arrive, not from the transcript.
+ *
+ * It is not truncated here. Whoever consumes it fits it to its own limit.
+ */
+export declare class UserRequestLog {
+    private items;
+    private save;
+    record(text: string, kind?: UserRequestKind): void;
+    entries(): readonly UserRequest[];
+    /** Forgets everything: a new conversation. */
+    reset(): void;
+    /** Replaces the log with a conversation read back from a session. */
+    restore(requests: readonly UserRequest[]): void;
+    /**
+     * Where each recorded message is saved. Returns a detach that only unplugs this saver: a session that
+     * shut down late must not unplug the one that replaced it. Detached, the log is in-memory only.
+     */
+    attach(save: SaveEntry): () => void;
+}
+/**
+ * pi extension that keeps the conversation's {@link UserRequestLog} in the session file, next to the
+ * transcript. Starting, resuming, forking, or navigating the session tree rebuilds the log from the branch
+ * now in view, so `/new` begins empty and `/resume` brings the earlier requests back.
+ */
+export declare function createUserRequestPersistence(log: UserRequestLog): ExtensionFactory;
+/** `text` cut to `max` characters by dropping its middle, so both what it starts with and ends with survive. */
+export declare function cutMiddle(text: string, max: number): string;
+/**
+ * The conversation as the Jev gate reads it: every user message in order, verbatim and numbered, with
+ * corrections marked. Nothing is shortened while it fits in `maxChars`. Over that, the opening request and
+ * the newest messages stay and the middle is dropped with a count (the numbering shows where), because the
+ * first message says what the user came for and the last ones say where they ended up. Only when even
+ * those two do not fit is a single message cut, in the middle.
+ */
+export declare function renderUserRequests(requests: readonly UserRequest[], maxChars: number): string;
+export {};

package/dist/agent/welcome-header.d.ts

@@ -0,0 +1,35 @@
+import type { ExtensionFactory, SettingsManager, Theme } from "@earendil-works/pi-coding-agent";
+/**
+ * One is shown per session, picked at random. Each fits on one line of an
+ * 80-column terminal after the `Tip · ` label, and is true of the TUI as shipped.
+ */
+export declare const WELCOME_TIPS: readonly string[];
+export interface WelcomeBannerOptions {
+    readonly width: number;
+    readonly version: string;
+    readonly theme: Pick<Theme, "fg" | "bold">;
+    /** Source of the rotating tip offset. Default `Math.random`. */
+    readonly random?: () => number;
+}
+/**
+ * The first screen of `autorag tui`: the logo, the version, and one random tip,
+ * centered on `width`. The logo is centered as one block so its shape holds;
+ * the version and the tip are centered on their own. The tip is always one line
+ * and is cut with `...` when the terminal is narrower than it.
+ */
+export declare function renderWelcomeBanner({ width, version, theme, random }: WelcomeBannerOptions): string[];
+/** The slice of pi's settings the banner reads and adjusts. */
+type WelcomeSettings = Pick<SettingsManager, "applyOverrides" | "getGlobalSettings" | "getProjectSettings" | "getQuietStartup">;
+export interface WelcomeHeaderOptions {
+    readonly version: string;
+    readonly settings: WelcomeSettings;
+    readonly random?: () => number;
+}
+/**
+ * Replaces pi's startup header (its logo, key hints) with the AutoRAG banner on
+ * every session start: launch, `/new`, `/resume`, `/fork`, `/reload`. pi
+ * restores its built-in header before each session start, so there is nothing
+ * to clean up. A user who saved `quietStartup: true` gets no banner.
+ */
+export declare function createWelcomeHeader(options: WelcomeHeaderOptions): ExtensionFactory;
+export {};

package/dist/automation/config.d.ts

@@ -0,0 +1,48 @@
+export type AutomationEventType = "create" | "update" | "delete";
+export declare const AUTOMATION_EVENT_TYPES: readonly AutomationEventType[];
+export interface AutomationEvent {
+    readonly type: AutomationEventType;
+    readonly path: string;
+}
+/** Which retrieval tools an agent rule's session is offered; retrieval memory is never connected. */
+export interface AutomationAgentRetrieval {
+    readonly searchAll: boolean;
+    readonly datasources: readonly string[];
+}
+/** What an agent rule runs: a registered agent profile, spawned in-process on each batch of events. */
+export interface AutomationAgent {
+    readonly profile: string;
+    readonly task: string;
+    readonly retrieval: AutomationAgentRetrieval;
+}
+/** A rule runs exactly one of `run` (a command) or `agent` (a profile session). */
+export interface Automation {
+    readonly id: string;
+    readonly paths: readonly string[];
+    readonly events: readonly AutomationEventType[];
+    readonly include: readonly string[];
+    readonly exclude: readonly string[];
+    readonly run?: readonly string[];
+    readonly agent?: AutomationAgent;
+    readonly appendFiles: boolean;
+    readonly debounceMs: number;
+    readonly timeoutMs: number;
+}
+export declare const DEFAULT_DEBOUNCE_MS = 1000;
+export declare const DEFAULT_TIMEOUT_MS = 600000;
+export declare const DEFAULT_EXCLUDES: readonly string[];
+export declare class AutomationConfigError extends Error {
+    constructor(message: string);
+}
+export declare function automationsConfigPath(env?: NodeJS.ProcessEnv): string;
+export declare function parseAutomations(raw: unknown, env?: NodeJS.ProcessEnv): Automation[];
+export declare function loadAutomations(configPath?: string, env?: NodeJS.ProcessEnv): Automation[];
+/**
+ * Insert or replace the rule with `id`, keeping every other rule as written. The
+ * whole file is validated before it is written, so an invalid rule never lands
+ * on disk and the running daemon never reloads a broken file.
+ */
+export declare function saveAutomation(configPath: string, id: string, rule: Readonly<Record<string, unknown>>, env?: NodeJS.ProcessEnv): Automation;
+export declare function deleteAutomation(configPath: string, id: string): void;
+export declare function matchesAutomationPath(automation: Automation, watchedRoot: string, filePath: string): boolean;
+export declare function matchesAutomation(automation: Automation, watchedRoot: string, event: AutomationEvent): boolean;

package/dist/automation/daemon.d.ts

@@ -0,0 +1,31 @@
+import { type Automation, type AutomationEvent } from "./config.js";
+import type { AutomationRunRecord } from "./run.js";
+export declare const DEFAULT_MAX_RUNS_PER_MINUTE = 20;
+/** An agent run costs model calls, so a rule that starts agents trips the self-trigger breaker sooner. */
+export declare const DEFAULT_MAX_AGENT_RUNS_PER_MINUTE = 6;
+export interface AutomationSubscription {
+    unsubscribe(): Promise<void>;
+}
+export type AutomationWatcherBackend = (dir: string, onEvents: (events: readonly AutomationEvent[]) => void, onError?: (error: Error) => void) => Promise<AutomationSubscription>;
+export type AutomationRunner = (automation: Automation, events: readonly AutomationEvent[]) => Promise<AutomationRunRecord>;
+export interface AutomationDaemonOptions {
+    readonly home?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly selfCommand?: readonly string[];
+    readonly watcher?: AutomationWatcherBackend;
+    readonly runner?: AutomationRunner;
+    readonly maxRunsPerMinute?: number;
+    readonly watchConfigFile?: boolean;
+    readonly onRun?: (automation: Automation, record: AutomationRunRecord) => void;
+    readonly onError?: (message: string) => void;
+}
+export interface AutomationDaemonHandle {
+    reload(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare class AutomationDaemonAlreadyRunningError extends Error {
+    constructor(home: string);
+}
+export declare function automationDaemonLockPath(home?: string): string;
+export declare function isAutomationDaemonRunning(home?: string): boolean;
+export declare function startAutomationDaemon(options?: AutomationDaemonOptions): Promise<AutomationDaemonHandle>;

package/dist/automation/dispatch.d.ts

@@ -0,0 +1,13 @@
+import type { Automation, AutomationEvent } from "./config.js";
+import { type AutomationRunRecord, type RunAutomationOptions } from "./run.js";
+import { type RunAgentAutomationOptions } from "./run-agent.js";
+/**
+ * Agent runs the process may have in flight at once, across every rule. A run
+ * holds a model session and, with retrieval tools, the configured indexes, so
+ * rules wait their turn instead of running in parallel. Events that arrive
+ * while a rule waits stay in its pending batch and are handled together.
+ */
+export declare const AGENT_RUN_CONCURRENCY = 1;
+export type RunRuleOptions = RunAutomationOptions & RunAgentAutomationOptions;
+/** Run one rule: its command, or its agent profile. The single entry for the daemon, the CLI and the tool. */
+export declare function runRule(automation: Automation, events: readonly AutomationEvent[], options?: RunRuleOptions): Promise<AutomationRunRecord>;

package/dist/automation/run-agent.d.ts

@@ -0,0 +1,22 @@
+import { type AgentProfile, type ProfileModel } from "../profiles/agent-factory.js";
+import type { Automation, AutomationEvent } from "./config.js";
+import { type AutomationRunRecord } from "./run.js";
+export interface RunAgentAutomationOptions {
+    readonly home?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    /** pi's agent dir (the shared credential store); defaults to pi's own. */
+    readonly agentDir?: string;
+    /** Resolves the model the session runs on; defaults to the AutoRAG agent's configured model. */
+    readonly resolveModel?: (cwd: string) => Promise<ProfileModel>;
+}
+/** The profile an agent rule runs, with the loop guard appended. A profile cannot leave the guard out. */
+export declare function buildAutomationProfile(automation: Automation): AgentProfile;
+/** The user message of a run: one `type: path` line per changed file, capped like `appendFiles`. */
+export declare function eventsPrompt(events: readonly AutomationEvent[]): string;
+/**
+ * Run an agent rule: spawn its profile as an in-memory pi session, hand it the
+ * changed files, and wait for its final reply. The session never touches
+ * AutoRAG's retrieval memory; retrieval tools, when the rule asks for them, run
+ * against a throwaway memory file.
+ */
+export declare function runAgentAutomation(automation: Automation, events: readonly AutomationEvent[], options?: RunAgentAutomationOptions): Promise<AutomationRunRecord>;

package/dist/automation/run.d.ts

@@ -0,0 +1,32 @@
+import type { Automation, AutomationEvent } from "./config.js";
+export declare const AUTOMATION_MAX_APPEND_FILES = 100;
+export interface AutomationRunRecord {
+    readonly id: string;
+    readonly startedAt: string;
+    readonly durationMs: number;
+    readonly eventCount: number;
+    readonly filesOverflow: boolean;
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly timedOut: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly error?: string;
+}
+export interface RunAutomationOptions {
+    readonly home?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    /** Override `[nodePath, cliEntry]` used when `run[0] === "autorag"`. */
+    readonly selfCommand?: readonly string[];
+}
+export declare function automationLogPath(home: string | undefined, id: string): string;
+export declare function appendAutomationRunLog(home: string, record: AutomationRunRecord): void;
+export declare function readLastAutomationRun(home: string, id: string): AutomationRunRecord | undefined;
+/**
+ * `[runtime, cliEntry]` for this AutoRAG install, found by walking up from this
+ * module to the package root. `process.argv[1]` is not used: inside the MCP
+ * server or a library host it is not the AutoRAG CLI. Bundled installs run
+ * `dist/cli/index.js`; a source checkout without a build runs the TypeScript entry.
+ */
+export declare function autoragCliCommand(): readonly string[];
+export declare function runAutomation(automation: Automation, events: readonly AutomationEvent[], options?: RunAutomationOptions): Promise<AutomationRunRecord>;

package/dist/automation/service.d.ts

@@ -0,0 +1,61 @@
+import { type Automation } from "./config.js";
+import { type AutomationRunRecord } from "./run.js";
+export interface AutomationServiceSpec {
+    readonly id: string;
+    readonly nodePath: string;
+    readonly cliEntry: string;
+    readonly envFilePath: string;
+    readonly logPath: string;
+    readonly home: string;
+    readonly pathEnv: string;
+    readonly configPath?: string;
+}
+export interface AutomationServiceDescriptor {
+    readonly platform: NodeJS.Platform;
+    readonly id: string;
+    readonly definitionPath: string;
+    readonly envFilePath: string;
+    readonly logPath: string;
+}
+export interface ServiceExecResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export type ServiceCommandExec = (cmd: string, args: readonly string[]) => Promise<ServiceExecResult>;
+export interface AutomationServiceOptions {
+    readonly platform?: NodeJS.Platform;
+    readonly home?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly selfCommand?: readonly string[];
+    readonly exec?: ServiceCommandExec;
+    /** How long install waits for the daemon to hold its lock. Default 15000. */
+    readonly waitForRunningMs?: number;
+}
+export interface AutomationServiceInstallResult extends AutomationServiceDescriptor {
+    /** Whether the daemon was observed running before install returned. */
+    readonly running: boolean;
+}
+export interface AutomationStatusEntry extends Automation {
+    readonly lastRun?: AutomationRunRecord;
+}
+export interface AutomationStatusReport {
+    readonly service: {
+        readonly platform: NodeJS.Platform;
+        readonly id: string;
+        readonly definitionPath: string;
+        readonly logPath: string;
+        readonly installed: boolean;
+        readonly running: boolean;
+    };
+    readonly configPath: string;
+    readonly configError?: string;
+    readonly automations: readonly AutomationStatusEntry[];
+}
+export declare function automationServiceDescriptor(options?: AutomationServiceOptions): AutomationServiceDescriptor;
+export declare function renderLaunchdPlist(spec: AutomationServiceSpec): string;
+export declare function renderSystemdUnit(spec: AutomationServiceSpec): string;
+export declare function renderWindowsTaskXml(spec: AutomationServiceSpec): string;
+export declare function installAutomationService(options?: AutomationServiceOptions): Promise<AutomationServiceInstallResult>;
+export declare function uninstallAutomationService(options?: AutomationServiceOptions): Promise<AutomationServiceDescriptor>;
+export declare function getAutomationStatus(options?: AutomationServiceOptions): AutomationStatusReport;

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

@@ -0,0 +1,2 @@
+import type { CommandContext } from "./types.js";
+export declare function runAutomate(ctx: CommandContext): Promise<number>;

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

@@ -1,2 +1,4 @@
+import { type SetupReport } from "../setup.js";
 import type { CommandContext } from "./types.js";
 export declare function runSetupCommand(ctx: CommandContext): Promise<number>;
+export declare function renderSetup(report: SetupReport): string;

package/dist/cli/config.d.ts

@@ -3,6 +3,7 @@ import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import type { AutoRAGAgentOptions, AutoRAGRefreshLimits, AutoRAGRetrievalLimits } from "../agent/agent.js";
 import type { JevBackendName } from "../agent/jev-extension.js";
 import { type LoadLocalAutoRAGModelOptions } from "../agent/local-model.js";
+import { type PermissionMode } from "../agent/permission-gate.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";
@@ -169,6 +170,11 @@ export interface CliConfig {
      * agent's own model decompose.
      */
     queryDecomposition?: QueryDecompositionConfig | false;
+    /**
+     * Approval gate for file changes by the agent: `auto` (default for the TUI: Jev first, user as fallback; `full` for `search` and a bridged TUI), `ask`
+     * (the user approves every file-capable call, Jev unused), or `full` (no gate). `--permission-mode` and `AUTORAG_PERMISSION_MODE` override the file.
+     */
+    permissionMode?: PermissionMode;
     /** Post-merge reranking. Absent ⇒ reranking disabled. `false` disables it. */
     rerank?: RerankConfig | false;
     parserOptions?: Record<string, unknown>;
@@ -178,6 +184,16 @@ export interface CliConfig {
         timeoutMs?: number;
     };
     excludeExactDuplicates?: boolean;
+    /** Filee command line behind the `convert_files` tool. `enabled: false` removes the conversion tools. */
+    filee?: {
+        enabled?: boolean;
+        binaryPath?: string;
+        /** Download the pinned filee-cli into `<AUTORAG_HOME>/tools` when none is found. Default true. */
+        autoInstall?: boolean;
+        timeoutMs?: number;
+        /** Folder for Filee's own settings and engines (`FILEE_DATA_DIR`); default is Filee's per-user folder. */
+        dataDir?: string;
+    };
     /** Absolute or workspace-relative files/directories omitted from local indexing. */
     excludePaths?: string[];
     /** Hard caps on retrieval, baseline prefetch, and model-facing candidate lists. */
@@ -192,6 +208,11 @@ export interface ResolveConfigInput {
     env?: NodeJS.ProcessEnv;
     cwd?: string;
     readOnly?: boolean;
+    /**
+     * Mode when no flag, environment variable, or config file sets one. Commands that run with nobody to approve
+     * (`search`) or through a remote bridge pass `full`; the interactive TUI leaves it to the default (`auto`).
+     */
+    defaultPermissionMode?: PermissionMode;
 }
 export interface ResolvedConfigPath {
     configPath: string;

package/dist/cli/index.d.ts

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