@autorag/librarian 2.11.0 → 2.13.0

package/dist/memory/memory.d.ts

@@ -6,7 +6,10 @@ export interface EvidenceContext {
     readonly documentType?: string;
     readonly documentArea?: string;
     readonly evidenceType?: string;
-    readonly evidenceLocation?: string;
+    /** Last line of the chunk in its parsed document; the first line is the ref's `lineNumber`. */
+    readonly lineEnd?: number;
+    /** Article or heading the chunk sits in. */
+    readonly section?: string;
     readonly confidence?: number;
 }
 export interface EvidenceChunkRecord extends NormalizedEvidenceRef, EvidenceContext {

package/dist/minsync/installer.d.ts

@@ -1,4 +1,4 @@
-export declare const MINSYNC_VERSION = "0.4.11";
+export declare const MINSYNC_VERSION = "0.4.12";
 export declare const MINSYNC_CARGO_INSTALL_TIMEOUT_MS: number;
 export interface MinSyncReleaseAsset {
     readonly name: string;

package/dist/mirror/atomic-write.d.ts

@@ -1,6 +1,21 @@
+export interface RenameRetryOptions {
+    /** Retries after the first attempt. Default 5, so six attempts in total. */
+    readonly retries?: number;
+    /** First wait in milliseconds; it doubles each retry (25/50/100/200/400 by default). */
+    readonly backoffMs?: number;
+}
+/** True for a rename error that a short wait can clear (`EPERM`, `EACCES`, `EBUSY`). */
+export declare function isRetryableRenameError(error: unknown): boolean;
+/**
+ * `renameSync` that waits and retries while the destination is transiently held (see
+ * {@link RETRYABLE_RENAME_CODES}). Any other error, and the last retryable one, is rethrown unchanged.
+ */
+export declare function renameWithRetry(from: string, to: string, options?: RenameRetryOptions): void;
 /**
  * Write `content` to `path` through a sibling temp file and an atomic rename.
- * On any failure the temp file is removed before the error is rethrown, so a full
+ * A destination that stays held through every rename retry is overwritten in place instead: replacing by
+ * rename needs delete rights on the destination, writing to an existing file does not.
+ * On any other failure the temp file is removed before the error is rethrown, so a full
  * disk or an I/O error never leaves `*.tmp` orphans in the mirror.
  */
 export declare function writeFileAtomic(path: string, content: string): void;

package/dist/mirror/sync.d.ts

@@ -2,6 +2,8 @@ import { type DefaultParserRegistryOptions } from "../parser/defaults.js";
 import type { ParserRegistry } from "../parser/registry.js";
 /** Refuse to fully load/parse sources larger than this. Keeps Node heap stable on home folders. */
 export declare const DEFAULT_MAX_SOURCE_BYTES: number;
+/** Persist partial mirror progress this often so an OOM mid-run still restarts incrementally. */
+export declare const MIRROR_CHECKPOINT_EVERY = 25;
 /** A refresh may delete at most this share of the indexed documents (above {@link MASS_DELETE_FLOOR}). */
 export declare const DEFAULT_MAX_DELETE_RATIO = 0.3;
 /** Directory entries examined per search root before the walk stops. */

package/dist/profiles/agent-factory.d.ts

@@ -0,0 +1,60 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { type AgentSession, type CreateAgentSessionOptions, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+/**
+ * Plain pi agent sessions for helper features, one per {@link AgentProfile}.
+ *
+ * The AutoRAG agent (`AutoRAGAgent`) answers searches and is not touched here.
+ * Every other helper agent (smart indexing in the desktop app, file-triggered
+ * automations, and whatever follows) is a vanilla pi session: its own system
+ * prompt, its own tool set, and its own choice of what pi would otherwise load
+ * on its own (AGENTS.md, skills, extensions). What the profiles share is the
+ * account: the model the AutoRAG agent runs on, and the credential store under
+ * the same agent dir (`auth.json`, `models.json`), so a sign-in or key change
+ * reaches them without a second login.
+ *
+ * A session lives in memory and is gone with `dispose()`: nothing is written
+ * under the agent dir or the working directory, and the user's own pi settings
+ * (default tools, themes, ...) never apply. A profile session never reads or
+ * writes AutoRAG's retrieval memory.
+ */
+/** How hard the model thinks; the same levels pi's session takes. */
+export type ProfileThinking = NonNullable<CreateAgentSessionOptions["thinkingLevel"]>;
+/** What pi loads on its own besides the profile's prompt and tools. Everything is off unless a profile turns it on. */
+export interface ProfileContext {
+    /** AGENTS.md style instruction files from the agent dir and the working directory. */
+    readonly projectFiles?: boolean;
+    readonly skills?: boolean;
+    /** Extensions from the agent dir and the working directory. An extension's tools still have to be named in {@link AgentProfile.tools}. */
+    readonly extensions?: boolean;
+}
+export interface AgentProfile {
+    readonly id: string;
+    readonly systemPrompt: string;
+    /**
+     * Names of the pi tools the model may call (`read`, `ls`, `find`, `grep`, and
+     * `bash`/`edit`/`write` for a profile that may change things; an extension's
+     * tool when {@link ProfileContext.extensions} is on). Tools in
+     * {@link customTools} are always allowed and need no entry here.
+     */
+    readonly tools: readonly string[];
+    readonly customTools?: readonly ToolDefinition[];
+    readonly thinking: ProfileThinking;
+    readonly context?: ProfileContext;
+}
+/** The model a session runs on and the credentials resolved for it; see `resolveSessionModel`. */
+export interface ProfileModel {
+    readonly model: Model<Api>;
+    readonly apiKey?: string;
+    readonly providerApiKeys?: Readonly<Record<string, string>>;
+}
+export interface ProfileSessionOptions {
+    readonly profile: AgentProfile;
+    /** Working directory of the session: relative paths and project context resolve against it. */
+    readonly cwd: string;
+    /** pi's agent dir; `auth.json` and `models.json` in it are the shared credential store. */
+    readonly agentDir: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly model: ProfileModel;
+}
+/** Builds a ready session for `profile`; the caller prompts it and disposes it. */
+export declare function createProfileSession(options: ProfileSessionOptions): Promise<AgentSession>;

package/dist/profiles/automation-profiles.d.ts

@@ -0,0 +1,25 @@
+import type { AgentProfile } from "./agent-factory.js";
+/**
+ * Agent profiles an automation rule can name (`"agent": { "profile": "<id>" }`).
+ *
+ * A rule only carries the id, never a prompt or a tool list: what an agent may
+ * do is decided here, in code, so a rules file (which the librarian agent can
+ * itself edit) cannot grant `bash` or `write` to an agent that was meant to read.
+ * The runner appends the mandatory loop guard (`loop-guard.ts`) to every
+ * profile's prompt, writing profiles included.
+ */
+/** What a profile builder is told about the run it serves. */
+export interface AutomationProfileInput {
+    /** The rule's own instruction for this run; a profile folds it into its prompt. */
+    readonly task: string;
+}
+export interface AutomationProfileDefinition {
+    readonly id: string;
+    readonly description: string;
+    /** True when the profile may change files (offers `bash`, `edit` or `write`). */
+    readonly writes: boolean;
+    build(input: AutomationProfileInput): AgentProfile;
+}
+export declare function registerAutomationProfile(definition: AutomationProfileDefinition): void;
+export declare function getAutomationProfile(id: string): AutomationProfileDefinition | undefined;
+export declare function listAutomationProfiles(): readonly AutomationProfileDefinition[];

package/dist/profiles/loop-guard.d.ts

@@ -0,0 +1,23 @@
+/** The part of an automation rule the loop guard describes to the agent. */
+export interface LoopGuardRule {
+    readonly id: string;
+    readonly paths: readonly string[];
+    readonly events: readonly string[];
+    readonly include: readonly string[];
+    readonly exclude: readonly string[];
+}
+/**
+ * File extensions a rule's include globs name (`**\/*.pdf`, `*.{md,txt}`), lower-case with the dot.
+ * Empty when some glob names no extension (`**`, `docs/**`): the rule then fires on every file type.
+ */
+export declare function includedExtensions(include: readonly string[]): readonly string[];
+/**
+ * The system-prompt section every agent run started by an automation carries.
+ *
+ * The automation runner appends it to the profile's own prompt; a profile cannot
+ * leave it out. An agent that may write files could otherwise change a file the
+ * rule watches, which fires the rule again and starts another run of the agent:
+ * an endless loop. The section names the rule's folders, file types, and events,
+ * and forbids every change that would fire the rule.
+ */
+export declare function loopGuardPrompt(rule: LoopGuardRule): string;

package/dist/profiles/retrieval-tools.d.ts

@@ -0,0 +1,24 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type CliConfig } from "../cli/config.js";
+/** Which of AutoRAG's retrieval tools a profile session is offered, on top of its own tools. */
+export interface RetrievalToolOptions {
+    /** `search_all_documents`: fan-out across every configured retrieval method. */
+    readonly searchAll?: boolean;
+    /** Datasource ids to offer one `search_datasource_<id>` tool for each. */
+    readonly datasources?: readonly string[];
+}
+export interface RetrievalToolkit {
+    readonly tools: readonly ToolDefinition[];
+    dispose(): Promise<void>;
+}
+export declare function hasRetrievalTools(options: RetrievalToolOptions | undefined): boolean;
+/**
+ * Retrieval tools for a profile session, backed by the configured indexes.
+ *
+ * Retrieval memory is never connected: the backing agent is pointed at a
+ * throwaway memory file with the memory embedder off, so nothing the profile
+ * searches is read from or recorded into the user's real `memory.json`. Only
+ * the search tools are handed out; the backing agent's other surfaces (web,
+ * Everything, FSearch, Jev, duplicate scan) stay off.
+ */
+export declare function createRetrievalToolkit(config: CliConfig, options: RetrievalToolOptions): Promise<RetrievalToolkit>;

package/dist/profiles/session-model.d.ts

@@ -0,0 +1,69 @@
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { type CliConfig } from "../cli/config.js";
+import type { ProfileModel } from "./agent-factory.js";
+/**
+ * Why the hosted plan's key must not ride along as a session API key.
+ *
+ * The `dazzi` provider is OAuth-only: its credential is the `/login` entry in
+ * Pi's `auth.json`. Handing the resolved key to `ModelRuntime.setRuntimeApiKey`
+ * replaces that OAuth credential with an `api_key` one, and an OAuth-only
+ * provider accepts no API key, so the session stops with "No API key found for
+ * dazzi" even though the user is signed in. That only happens when the
+ * session's runtime already lists the model (the persisted catalog snapshot the
+ * sign-in writes); a model the runtime does not list is registered from the key
+ * instead and works.
+ *
+ * So for a plan model the runtime lists, the key is dropped and Pi resolves the
+ * stored OAuth credential itself. A model it does not list keeps the key.
+ */
+/** The slice of Pi's `ModelRuntime` this module reads. */
+export interface PlanRuntime {
+    getModel(provider: string, id: string): unknown;
+    refresh(options: {
+        readonly allowNetwork: boolean;
+        readonly providers: readonly string[];
+        readonly force: boolean;
+    }): Promise<unknown>;
+}
+/** A resolved agent model with the credentials a session receives. */
+export interface SessionModelAuth {
+    readonly model: {
+        readonly provider: string;
+        readonly id: string;
+    };
+    readonly apiKey?: string;
+    readonly providerApiKeys?: Readonly<Record<string, string>>;
+}
+/** Open Pi's runtime on `agentDir` with the plan provider registered, offline until asked. */
+export declare function openPlanRuntime(agentDir: string, env: NodeJS.ProcessEnv): Promise<ModelRuntime>;
+/**
+ * Drop the plan's API key from a resolved model when Pi can authenticate it
+ * from the stored OAuth credential. Any other model, or a plan model Pi cannot
+ * list (offline, unknown id), is returned unchanged.
+ */
+export declare function preferPlanOAuth<T extends SessionModelAuth>(resolved: T, openRuntime: () => Promise<PlanRuntime>): Promise<T>;
+/**
+ * The Dazzi `/v1/models` catalog omits `thinkingLevelMap` for its OpenRouter-backed
+ * model ids (e.g. `z-ai/glm-5.3-flash`, `anthropic/claude-haiku-5.5`). Without it,
+ * Pi's `clampThinkingLevel(model, "off")` keeps `"off"` and `openai-responses`
+ * sends `reasoning: { effort: "none" }`, which mandatory-reasoning endpoints
+ * reject with HTTP 400 (`Reasoning is mandatory for this endpoint and cannot be
+ * disabled`). Inherit the upstream OpenRouter `thinkingLevelMap` when present so
+ * `"off"` clamps to `"low"` for those models.
+ */
+export declare function applyDazziThinkingLevels<T extends {
+    readonly provider: string;
+    readonly id: string;
+    readonly thinkingLevelMap?: unknown;
+}>(model: T): T;
+/**
+ * The model every profile agent runs on: the one the shared AutoRAG config names
+ * for the AutoRAG agent, with its credentials. AI Search and the profile agents
+ * both resolve it, so there is one answer to "which model, which key".
+ *
+ * Credentials are read fresh on every call, so a login or key change reaches the
+ * next session without a restart.
+ */
+export declare function resolveSessionModel(config: CliConfig, env: NodeJS.ProcessEnv, cwd: string, agentDir: string): Promise<ProfileModel>;
+/** {@link resolveSessionModel} for the config file the app and the CLI share. */
+export declare function resolveConfiguredSessionModel(env: NodeJS.ProcessEnv, cwd: string, agentDir: string): Promise<ProfileModel>;

package/dist/profiles.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@autorag/librarian/profiles`: agent profiles for helper features.
+ *
+ * A profile is a system prompt, a tool set, and a thinking level; the factory turns
+ * one into a plain in-memory pi session on the AutoRAG agent's own model and
+ * credentials. The desktop app's smart indexing and file-triggered automations
+ * are built on it. No profile session touches AutoRAG's retrieval memory.
+ */
+export { type AgentProfile, createProfileSession, type ProfileContext, type ProfileModel, type ProfileSessionOptions, type ProfileThinking, } from "./profiles/agent-factory.js";
+export { type AutomationProfileDefinition, type AutomationProfileInput, getAutomationProfile, listAutomationProfiles, registerAutomationProfile, } from "./profiles/automation-profiles.js";
+export { includedExtensions, type LoopGuardRule, loopGuardPrompt } from "./profiles/loop-guard.js";
+export { createRetrievalToolkit, hasRetrievalTools, type RetrievalToolkit, type RetrievalToolOptions, } from "./profiles/retrieval-tools.js";
+export { applyDazziThinkingLevels, openPlanRuntime, type PlanRuntime, preferPlanOAuth, resolveConfiguredSessionModel, resolveSessionModel, type SessionModelAuth, } from "./profiles/session-model.js";