@autorag/librarian 2.10.6 → 2.12.0

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/minsync/workspace-lock.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Run a sync (anything that rewrites the workspace). The in-flight count is raised
+ * before this returns, so a query issued right after the call already sees the sync.
+ */
+export declare function runWorkspaceSync<T>(workspacePath: string, run: () => Promise<T>): Promise<T>;
+/** Run a query. It is refused while a sync is pending, because the index is mid-rewrite. */
+export declare function runWorkspaceQuery<T>(workspacePath: string, run: () => Promise<T>): Promise<T>;

package/dist/process/terminate-tree.d.ts

@@ -4,11 +4,10 @@ export declare const TREE_KILL_GRACE_MS = 500;
 /**
  * Terminate a spawned external CLI together with the descendants it created.
  *
- * CLIs such as qmd 2.8.3 are launchers: the process AutoRAG spawns starts a
- * runtime descendant that inherits the launcher's stdout/stderr pipes. Node
- * emits `close` only once every holder of those pipes has exited, so signalling
- * just the direct child leaves the caller waiting on a descendant that may live
- * for minutes — the hang reported in #1578.
+ * CLIs that are launchers (an npm shim, a wrapper script) start a runtime descendant that inherits
+ * the launcher's stdout/stderr pipes. Node emits `close` only once every holder of those pipes has
+ * exited, so signalling just the direct child leaves the caller waiting on a descendant that may
+ * live for minutes — the hang reported in #1578.
  *
  * Spawn the child with `detached: true` on POSIX so it leads its own process
  * group; the group survives the direct child and stays addressable as `-pid`.

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";