@autorag/librarian 2.11.0 → 2.12.0

package/dist/agent/intent-tracing.d.ts

@@ -0,0 +1,33 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/**
+ * Intent tracing: every tool the model can call also takes a short `i` argument, one line saying
+ * what that call is for. The text is shown while the model works (pi's `Working` loader in the TUI,
+ * `progress` events of `searchDocumentsStream` for the CLI and the desktop app), so a long search
+ * says what it is doing without the model writing separate progress notes.
+ *
+ * Pi has no such feature; this mirrors oh-my-pi's. The field exists only on the wire: it is added to
+ * the tool declarations of each model request and removed again before the tool validates and runs,
+ * so no tool ever sees it.
+ */
+export declare const INTENT_FIELD = "i";
+/** The text to show for a model-written intent, or `undefined` when it is not a usable label. */
+export declare function normalizeIntent(value: unknown): string | undefined;
+/** The intent of the last tool call in an assistant message that carries one, or `undefined`. */
+export declare function intentOfMessage(message: {
+    readonly role?: string;
+    readonly content?: unknown;
+}): string | undefined;
+/** Whether the tool schema already has its own `i` parameter, which then belongs to the tool. */
+export declare function schemaDefinesIntent(schema: unknown): boolean;
+/**
+ * The wire schema of a tool with the required `i` field first. A schema that is not an object, that
+ * already defines `i`, or that rejects unknown properties comes back unchanged: the tool would
+ * refuse the field once the model filled it in.
+ */
+export declare function withIntentField(schema: unknown): unknown;
+/**
+ * Wires intent tracing into a pi session: declares `i` on every tool, takes it off the arguments
+ * before the tool runs, and, when the session has a terminal UI, shows the newest intent as the
+ * working message. Register it in every session whose model calls AutoRAG's tools.
+ */
+export declare function registerIntentTracing(pi: ExtensionAPI): void;

package/dist/agent/permission-gate.d.ts

@@ -0,0 +1,78 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { JevJudge } from "./jev-extension.js";
+import { type PermissionKind } from "./permission-judgment.js";
+import { type UserRequestLog } from "./user-requests.js";
+export { AUTO_APPROVE_MIN_CONFIDENCE, DEFAULT_MAX_STATE_CHARS, PERMISSION_GATE_QUESTION_ID, } from "./permission-judgment.js";
+/**
+ * How much the agent may do to the user's files without asking.
+ *
+ * - `full`: no gate; the agent does everything on its own, and Jev is never asked.
+ * - `ask`: every `bash`, `write`, `edit`, and saved automation is put to the user. Jev is not used.
+ * - `auto` (default): Jev classifies each of those calls first. One it finds safe runs; one it flags is approved
+ *   by Jev when the user's request clearly covers it, and only what Jev will not approve confidently reaches
+ *   the user.
+ */
+export type PermissionMode = "full" | "ask" | "auto";
+/** Order Shift+Tab cycles through. */
+export declare const PERMISSION_MODES: readonly PermissionMode[];
+/** Mode a fresh interactive or CLI session starts in. */
+export declare const DEFAULT_PERMISSION_MODE: PermissionMode;
+export declare function parsePermissionMode(value: unknown): PermissionMode | undefined;
+export declare function cyclePermissionMode(mode: PermissionMode): PermissionMode;
+type ModeListener = (mode: PermissionMode) => void;
+/** What a session grant covers: one category of change, every call Jev could not classify, or (`ask`) every call. */
+export type GrantKey = PermissionKind | "unclassified" | "all";
+/**
+ * Session-wide permission state: the mode, and what the user allowed for the rest of the session. One
+ * controller is shared by every pi session of an agent.
+ */
+export declare class PermissionController {
+    private current;
+    private readonly listeners;
+    private readonly granted;
+    private readonly created;
+    constructor(mode?: PermissionMode);
+    get mode(): PermissionMode;
+    /** Switches mode. Session grants end with the mode they were given in. */
+    set(mode: PermissionMode): void;
+    cycle(): PermissionMode;
+    subscribe(listener: ModeListener): () => void;
+    isGranted(key: GrantKey): boolean;
+    grant(keys: readonly GrantKey[]): void;
+    /** Records paths a successful call brought into existence: the agent's own files, not the user's originals. */
+    markCreated(paths: readonly string[]): void;
+    /** Whether the agent created this path, or a folder it lies in, earlier in this session. */
+    isCreated(path: string): boolean;
+}
+export interface PermissionGateOptions {
+    readonly controller: PermissionController;
+    /**
+     * Jev, which classifies every gated call. Without one the gate cannot classify, so in `ask` and `auto` it
+     * asks the user about every `bash`, `write`, and `edit` call.
+     */
+    readonly judge?: JevJudge;
+    /**
+     * What the user has said in this conversation: the first question, every follow-up, every steer. Jev judges
+     * the call against all of it. The host feeds it from the user's own input, so AutoRAG's internal phase
+     * prompts are never in it.
+     */
+    readonly requests?: UserRequestLog;
+    /** Cap on the state shown to Jev, in characters. Default: Jev's context ceiling with a safety margin. */
+    readonly maxStateChars?: number;
+    /** Files the agent may always write and edit without Jev being asked (the config its self-configuration turn edits). */
+    readonly trustedPaths?: readonly string[];
+}
+/** Appended to the system prompt while a gate is active, so the model stays on the happy path. */
+export declare const PERMISSION_PROMPT_ADDENDUM: string;
+/** `ask` addendum: the user sees every call, so the model should batch work and still not refuse requests. */
+export declare const ASK_PROMPT_ADDENDUM: string;
+/**
+ * pi extension that gates what the agent does to existing files.
+ *
+ * Every `bash`, `write`, `edit`, and `manage_automations save` call is gated (reads, searches, and other tools
+ * never touch originals and are not asked about). In `ask` each one is put to the user. In `auto` Jev
+ * classifies it first: a call it finds safe runs, one it flags is approved by Jev when the user's request
+ * clearly covers it, and otherwise put to the user. Shift+Tab and `/permissions` switch the mode; the footer
+ * shows it.
+ */
+export declare function createPermissionGate(options: PermissionGateOptions): ExtensionFactory;

package/dist/agent/permission-judgment.d.ts

@@ -0,0 +1,72 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { JevJudge } from "./jev-extension.js";
+import { type ProposedCall } from "./permission-paths.js";
+import { type UserRequest } from "./user-requests.js";
+/**
+ * What a tool call does to the user's existing files, as Jev judges it. A call can be several at once
+ * (`mkdir x && mv a x/ && rm b` is a move and a delete).
+ *
+ * `unclear` is for code whose effect cannot be told from what is shown: an unseen script file, `make clean`,
+ * an encoded command. It is asked about like any other category.
+ */
+export declare const PERMISSION_KINDS: readonly ["delete", "move", "rename", "overwrite", "edit", "unclear"];
+export type PermissionKind = (typeof PERMISSION_KINDS)[number];
+export declare function permissionKindQuestionId(kind: PermissionKind): string;
+/** Jev question id of the "may this run without asking?" check that `auto` mode adds to the same batch. */
+export declare const PERMISSION_GATE_QUESTION_ID = "permission_gate";
+/** Jev must be at least this sure before `auto` skips the user. Stricter than jev-use's own 0.5 default. */
+export declare const AUTO_APPROVE_MIN_CONFIDENCE = 0.8;
+/**
+ * Largest state the gate shows Jev, in characters. jev-use hands every question back ("oversized") once the
+ * state passes {@link DEFAULT_MAX_STATE_TOKENS} estimated tokens (about 4 characters each), and then the gate
+ * could not classify anything. The ceiling is read from jev-use so it cannot drift, and 10% is left for
+ * jev-use's own estimate being rough.
+ */
+export declare const DEFAULT_MAX_STATE_CHARS: number;
+/** The tool calls the gate classifies. Everything else (reads, searches, MCP tools) never touches originals. */
+export declare function isGatedCall(toolName: string, input: Readonly<Record<string, unknown>>): boolean;
+/** One line (or the command) naming what a call does, for the approval dialog and the notice. */
+export declare function summarizeCall(call: ProposedCall): string;
+/** The earlier calls of this session that ran and succeeded, oldest first. */
+export declare function successfulCalls(branch: readonly SessionEntry[]): ProposedCall[];
+export interface JudgedState {
+    readonly call: ProposedCall;
+    readonly requests: readonly UserRequest[];
+    readonly history: readonly ProposedCall[];
+    readonly maxStateChars: number;
+    /** Whether the agent itself brought this path into existence earlier in the session. */
+    readonly isCreated?: (path: string) => boolean;
+}
+/**
+ * The state Jev judges, within `maxStateChars`: how to judge, what the user said, what the agent already did,
+ * and the call itself. The call and the history are cut first (the call to 40% of the budget, the history to
+ * 20%, each keeping the start and end), and the conversation gets whatever is left, so the whole stays under
+ * the ceiling however long any one part is.
+ */
+export declare function buildJudgedState({ call, requests, history, maxStateChars, isCreated }: JudgedState): string;
+export interface FlaggedKind {
+    readonly kind: PermissionKind;
+    /** Jev's probability that the call is in this category; undefined when Jev was unsure and gave none. */
+    readonly probability: number | undefined;
+}
+export interface Approval {
+    readonly approved: boolean;
+    /** Why not, when it was not approved. */
+    readonly why: string;
+}
+/** Jev's reading of one call, or the reason it could not give one. */
+export type Classification = {
+    readonly status: "classified";
+    readonly flagged: readonly FlaggedKind[];
+    readonly approval: Approval;
+} | {
+    readonly status: "failed";
+    readonly why: string;
+};
+export type ClassifyOptions = JudgedState;
+/**
+ * Asks Jev what `options.call` does to existing files, in one batched request. Never throws: no answer
+ * (unreachable, timed out, oversized, a missing verdict) is a `failed` classification, and the gate then
+ * asks the user instead of letting the call through.
+ */
+export declare function classifyCall(judge: JevJudge, options: ClassifyOptions): Promise<Classification>;

package/dist/agent/permission-paths.d.ts

@@ -0,0 +1,23 @@
+/** A tool call the gate is about to judge. */
+export interface ProposedCall {
+    readonly tool: string;
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly cwd: string;
+}
+/** `raw` as an absolute path: relative to `cwd`, with `~` expanded. */
+export declare function resolveToolPath(raw: string, cwd: string): string;
+export interface NamedPath {
+    readonly path: string;
+    /**
+     * True when the word is certainly a path (absolute, `~/`, `./`, `../`, a file name with an extension) or
+     * names something that exists. A plain word that exists nowhere (`fresh` in `mkdir fresh`) is only a
+     * candidate: the gate watches whether the call brings it into existence, and shows it to Jev only then.
+     */
+    readonly always: boolean;
+}
+/**
+ * The paths a call names, for the facts Jev is shown (does each exist, did the agent make it). This does not
+ * decide anything and does not understand the command: it picks out the words that look like paths. A word it
+ * misses is a fact Jev lacks; a word it wrongly takes is a harmless "does not exist" line.
+ */
+export declare function pathsNamedBy(call: ProposedCall): NamedPath[];

package/dist/agent/query-routing.d.ts

@@ -6,11 +6,17 @@ import type { JevJudge } from "./jev-extension.js";
  *   Local retrieval runs first; web search is left to the agent after the fast
  *   answer, when local evidence falls short.
  * - `direct`: intrinsic knowledge or small talk the model answers on its own.
+ * - `organize`: the user wants files or folders acted on — move, rename in
+ *   bulk, rename by content, convert, sort, tidy — rather than information
+ *   found. No retrieval and no verification: one tool-capable turn does it.
+ * - `extra`: none of the other branches (committing code, opening a pull
+ *   request, running a build, any other task for the agent's tools). The Jev
+ *   gate is skipped: no retrieval, no verification, tools stay available.
  * - `config`: the user wants to inspect or change AutoRAG's own settings
  *   (model, providers, datasources). Offered only when the host enables
  *   agent self-configuration.
  */
-export type QueryRoute = "local" | "direct" | "config";
+export type QueryRoute = "local" | "direct" | "organize" | "extra" | "config";
 /** Jev question id of the intrinsic-knowledge / local branch. */
 export declare const QUERY_ROUTE_QUESTION_ID = "route";
 /** Jev question id of the "does this need decomposition?" check. */
@@ -23,15 +29,6 @@ export declare const FALLBACK_QUERY_ROUTE: QueryRoute;
 export declare const DECOMPOSE_PROBABILITY_THRESHOLD = 0.5;
 /** A `noul` probability at or above this sends the fast answer on to verification. */
 export declare const FOLLOW_UP_PROBABILITY_THRESHOLD = 0.5;
-/**
- * Minimum Jev branch probability required to leave local search. A `direct`
- * branch at or below this floor — or one Jev reported without a probability —
- * keeps the run on local search, the corpus-grounded default.
- * Without the floor a weakly-favored `direct` verdict (observed at p 0.57-0.63
- * on personal-corpus questions) skips retrieval entirely and answers from
- * general knowledge, so the caller loses the evidence the question depends on.
- */
-export declare const NON_LOCAL_ROUTE_PROBABILITY_THRESHOLD = 0.75;
 /** A `noul` probability at or above this searches that datasource before the fast answer. */
 export declare const DATASOURCE_PROBABILITY_THRESHOLD = 0.5;
 /** Jev question id of the "search this datasource?" check for one datasource. */
@@ -52,11 +49,11 @@ export interface FollowUpDecision {
  */
 export declare function needsFollowUp(judge: JevJudge, query: string, answer: string): Promise<FollowUpDecision>;
 export interface QueryRouteDecision {
-    /** Most probable branch; {@link FALLBACK_QUERY_ROUTE} when Jev gave none or its non-local branch missed {@link NON_LOCAL_ROUTE_PROBABILITY_THRESHOLD}. */
+    /** Most probable branch; {@link FALLBACK_QUERY_ROUTE} when Jev gave none. */
     readonly route: QueryRoute;
-    /** True when Jev judged the question needs decomposition (never for `direct`). */
+    /** True when Jev judged the question needs decomposition (only ever for `local`). */
     readonly decompose: boolean;
-    /** Probability Jev gave the winning branch, including a rejected non-local branch whose floor moved the route to local. */
+    /** Probability Jev gave the winning branch; absent when Jev reported none. */
     readonly routeProbability?: number;
     /** Jev's P(decomposition needed), when it answered. */
     readonly decomposeProbability?: number;
@@ -69,10 +66,10 @@ export interface RouteQueryOptions {
 }
 /**
  * Ask Jev, in one batched call about the user question, which branch answers
- * it and whether it needs decomposition. Never throws: a missing credential,
- * an unreachable backend, an unusable verdict, or a `direct` branch that does
- * not clear {@link NON_LOCAL_ROUTE_PROBABILITY_THRESHOLD} falls back to a
- * single local search, with the reason recorded.
+ * it and whether it needs decomposition. The most probable branch wins, with
+ * no confidence floor. Never throws: a missing credential, an unreachable
+ * backend, or an unusable verdict falls back to a single local search, with
+ * the reason recorded.
  */
 export declare function routeQuery(judge: JevJudge, query: string, options?: RouteQueryOptions): Promise<QueryRouteDecision>;
 /** One configured datasource Jev may send the question to. */

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

@@ -9,7 +9,7 @@ export type SearchDocumentDiagnosticSeverity = "info" | "warning" | "error";
  * (#21/#22) does not require another source-breaking type change; codes not yet
  * emitted are still valid members.
  */
-export type SearchDocumentDiagnosticCode = "empty-query" | "no-verified-results" | "unknown-warning" | "caller-tool-dropped" | "minsync-staging-excluded" | "minsync-file-skipped" | "minsync-sync-failed" | "minsync-lock-held" | "embedder-unavailable" | "embedding-identity-mismatch" | "lexical-tokenizer-unavailable" | "parser-skipped" | "parser-failed" | "parser-crashed" | "source-vanished" | "source-unreadable" | "source-read-failed" | "mirror-write-failed" | "parser-warning" | "duplicate-excluded" | "unsupported-file" | "stale-index" | "deleted-mirror" | "search-root-unavailable" | "mass-delete-suppressed" | "walk-truncated" | "directory-unreadable" | "pdf-extract-thin" | "retrieval-method-failed" | "rerank-failed" | "jikji-unavailable" | "jikji-prepare-failed" | "jikji-find-failed" | "everything-index-failed" | "fsearch-index-failed" | "fsearch-binary-missing" | "refresh-failed" | "refresh-interrupted" | "watch-failed" | "watch-limited" | "unknown-datasource-skill" | "no-final-answer" | "model-request-failed" | "tool-call-burst" | "query-routed" | "query-route-fallback" | "query-decomposition-failed" | "follow-up-skipped" | "follow-up-check-fallback" | "datasources-selected" | "datasource-selection-fallback" | "citation-without-result" | "evidence-judged" | "evidence-judgment-fallback" | "memory-search-fallback" | "self-config-unavailable" | "self-config-rolled-back" | "embedding-unavailable";
+export type SearchDocumentDiagnosticCode = "empty-query" | "no-verified-results" | "unknown-warning" | "caller-tool-dropped" | "minsync-staging-excluded" | "minsync-file-skipped" | "minsync-sync-failed" | "minsync-lock-held" | "embedder-unavailable" | "embedding-identity-mismatch" | "lexical-tokenizer-unavailable" | "parser-skipped" | "parser-failed" | "parser-crashed" | "source-vanished" | "source-unreadable" | "source-read-failed" | "mirror-write-failed" | "parser-warning" | "duplicate-excluded" | "unsupported-file" | "stale-index" | "deleted-mirror" | "search-root-unavailable" | "mass-delete-suppressed" | "walk-truncated" | "directory-unreadable" | "pdf-extract-thin" | "retrieval-method-failed" | "rerank-failed" | "jikji-unavailable" | "jikji-prepare-failed" | "jikji-find-failed" | "everything-index-failed" | "fsearch-index-failed" | "fsearch-binary-missing" | "refresh-failed" | "refresh-interrupted" | "watch-failed" | "watch-limited" | "unknown-datasource-skill" | "no-final-answer" | "model-request-failed" | "tool-call-burst" | "query-routed" | "query-route-fallback" | "query-decomposition-failed" | "follow-up-skipped" | "follow-up-check-fallback" | "datasources-selected" | "datasource-selection-fallback" | "citation-without-result" | "citation-irrelevant" | "citation-relevance-fallback" | "evidence-judged" | "evidence-judgment-fallback" | "memory-search-fallback" | "self-config-unavailable" | "self-config-rolled-back" | "embedding-unavailable";
 export interface SearchDocumentDiagnostic {
     readonly code: SearchDocumentDiagnosticCode;
     readonly severity: SearchDocumentDiagnosticSeverity;

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/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/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 {