@autorag/librarian 2.11.0 → 2.13.0

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

@@ -2,15 +2,25 @@ import type { JevJudge } from "./jev-extension.js";
 /**
  * Where a user question is answered from:
  * - `local`: anything needing information beyond the model's own knowledge —
- *   the user's files, chats, mail, or any fact the model cannot reliably recall.
- *   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.
+ *   the user's files, chats, mail, or any fact the model cannot reliably recall,
+ *   recent, specific, or changing public facts included. Local retrieval runs
+ *   first, together with every datasource Jev selects, the public web among
+ *   them when web tools are enabled.
+ * - `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`: neither of the other branches, and no search of the user's own
+ *   records is needed first: the request is answerable from the model's own
+ *   knowledge (stable general knowledge, definitions, simple reasoning, small
+ *   talk), or it is a task for the agent's tools that is not file organization
+ *   and not AutoRAG configuration (commit, PR, build, write code, run a
+ *   script). No retrieval, decomposition, fast answer, follow-up check, or
+ *   verification: one tool-capable turn does it, with every tool 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" | "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. */
@@ -24,18 +34,35 @@ 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.
+ * Minimum Jev branch probability required to leave local search. A non-local
+ * branch (`organize`, `extra`, `config`) at or below this floor — or one Jev
+ * reported without a probability — keeps the run on local search, the
+ * corpus-grounded default, with a `query-route-fallback` diagnostic naming the
+ * floor as the reason (the rejected branch's probability is still reported as
+ * `routeProbability`). Without the floor a weakly-favored non-local verdict
+ * skips retrieval entirely, so a question that depends on the user's own
+ * records can be answered from general knowledge instead.
+ *
+ * The floor does not weaken a real non-local verdict: the fallback is a
+ * full local plan (datasource selection and decomposition still run). Removed
+ * by #1995 (982e464d) together with the intrinsic-knowledge branch, restored
+ * here because the reasons above did not go away.
  */
 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. */
 export declare function datasourceQuestionId(datasourceId: string): string;
+/**
+ * Reserved candidate id of the public web in the datasource gate.
+ *
+ * Datasource ids come from the config's `datasources` keys, which are only
+ * required to be non-empty (see `DatasourceSkillRegistry.register`), so a
+ * configured datasource *can* be called `web`. When one is, the web candidate
+ * is withheld and {@link DatasourceSelection.webIdTaken} says so, so the
+ * question id `datasource:web` always names exactly one candidate.
+ */
+export declare const WEB_DATASOURCE_ID = "web";
 export interface FollowUpDecision {
     /** True when the run continues into the verification phase. */
     readonly followUp: boolean;
@@ -54,7 +81,7 @@ export declare function needsFollowUp(judge: JevJudge, query: string, answer: st
 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}. */
     readonly route: QueryRoute;
-    /** True when Jev judged the question needs decomposition (never for `direct`). */
+    /** True when Jev judged the question needs decomposition; only a `local` route acts on it. */
     readonly decompose: boolean;
     /** Probability Jev gave the winning branch, including a rejected non-local branch whose floor moved the route to local. */
     readonly routeProbability?: number;
@@ -62,17 +89,27 @@ export interface QueryRouteDecision {
     readonly decomposeProbability?: number;
     /** Why the decision fell back instead of following Jev; absent when Jev decided. */
     readonly fallbackReason?: string;
+    /**
+     * True when a non-local branch won but did not clear
+     * {@link NON_LOCAL_ROUTE_PROBABILITY_THRESHOLD}: `route` is `local` and the
+     * full local plan still runs (datasource selection and decomposition),
+     * unlike a fallback from an unavailable or unusable verdict, which keeps a
+     * bare single-query local search.
+     */
+    readonly floorApplied?: boolean;
 }
 export interface RouteQueryOptions {
     /** Offer the `config` branch: the agent may change its own settings. */
     readonly selfConfig?: boolean;
 }
 /**
- * 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.
+ * Ask Jev, in one batched call about the user question, which branch handles it
+ * and whether it needs decomposition. The most probable branch wins once it
+ * clears {@link NON_LOCAL_ROUTE_PROBABILITY_THRESHOLD}: a weakly-favored or
+ * probability-less `organize`, `extra`, or `config` verdict keeps the local
+ * default and still runs the full local plan (`floorApplied`). 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. */
@@ -84,12 +121,23 @@ export interface DatasourceCandidate {
     readonly description: string;
 }
 export interface DatasourceSelection {
-    /** Datasource ids to search, in registration order. */
+    /** Datasource ids to search, in registration order; the web candidate's id is {@link WEB_DATASOURCE_ID}. */
     readonly selected: readonly string[];
-    /** Jev's P(search needed) per datasource id, for every datasource it answered. */
+    /** Jev's P(search needed) per candidate id, for every candidate it answered. */
     readonly probabilities: Readonly<Record<string, number>>;
     /** Why no datasource is searched instead of following Jev; absent when Jev decided. */
     readonly fallbackReason?: string;
+    /**
+     * True when the web candidate was withheld because a configured datasource
+     * already uses {@link WEB_DATASOURCE_ID}: `datasource:web` then names that
+     * configured datasource, and the run searches no web before the fast answer.
+     */
+    readonly webIdTaken?: boolean;
+}
+/** Options of {@link selectDatasources}. */
+export interface SelectDatasourcesOptions {
+    /** Offer the public web as one more candidate (the host has web tools enabled). */
+    readonly web?: boolean;
 }
 /** A similar question asked before, its results, and where each was found. */
 export interface PastSearchHint {
@@ -104,12 +152,15 @@ export interface PastSearchHint {
     }[];
 }
 /**
- * Ask Jev, in one batched call, one `noul` per registered datasource: does
- * answering the question need that datasource searched? The state describes
- * every datasource (descriptions are flagged as non-exhaustive summaries), so
- * Jev judges each one against the others, plus where similar past questions
- * were answered, when retrieval memory has any. Never throws: a missing
- * credential or an unreachable backend searches no datasource, which is the
- * behavior without Jev.
+ * Ask Jev, in one batched call, one `noul` per candidate: does answering the
+ * question need that datasource searched? The state describes every candidate
+ * (descriptions are flagged as non-exhaustive summaries), so Jev judges each
+ * one against the others, plus where similar past questions were answered,
+ * when retrieval memory has any. With `options.web`, the public web is one
+ * more candidate, under the reserved id {@link WEB_DATASOURCE_ID}; it is
+ * withheld when a configured datasource already uses that id
+ * ({@link DatasourceSelection.webIdTaken}), so a question id never names two
+ * candidates. Never throws: a missing credential or an unreachable backend
+ * searches nothing, which is the behavior without Jev.
  */
-export declare function selectDatasources(judge: JevJudge, query: string, datasources: readonly DatasourceCandidate[], pastSearches?: readonly PastSearchHint[]): Promise<DatasourceSelection>;
+export declare function selectDatasources(judge: JevJudge, query: string, datasources: readonly DatasourceCandidate[], pastSearches?: readonly PastSearchHint[], options?: SelectDatasourcesOptions): Promise<DatasourceSelection>;

package/dist/agent/results.d.ts

@@ -16,6 +16,8 @@ export declare const reportSchema: Type.TObject<{
         evidence: Type.TArray<Type.TObject<{
             excerpt: Type.TString;
             lineNumber: Type.TOptional<Type.TInteger>;
+            lineEnd: Type.TOptional<Type.TInteger>;
+            section: Type.TOptional<Type.TString>;
         }>>;
         confidence: Type.TNumber;
     }>>;
@@ -38,7 +40,8 @@ export declare const reportSchema: Type.TObject<{
             documentType: Type.TOptional<Type.TString>;
             documentArea: Type.TOptional<Type.TString>;
             evidenceType: Type.TOptional<Type.TString>;
-            evidenceLocation: Type.TOptional<Type.TString>;
+            lineEnd: Type.TOptional<Type.TInteger>;
+            section: Type.TOptional<Type.TString>;
             confidence: Type.TOptional<Type.TNumber>;
         }>>>;
     }>>;
@@ -47,6 +50,10 @@ export declare const reportSchema: Type.TObject<{
 export interface AutoRAGEmittedEvidence {
     readonly excerpt: string;
     readonly lineNumber?: number;
+    /** Last line of the chunk; with {@link lineNumber} the exact range in the parsed document. */
+    readonly lineEnd?: number;
+    /** Article or heading the chunk sits in. */
+    readonly section?: string;
 }
 export interface AutoRAGEmittedResult {
     readonly number: number;
@@ -64,13 +71,14 @@ export interface AutoRAGEvidenceRef {
     readonly retrievalResultId?: string;
     readonly chunkIndex?: number;
     readonly lineNumber?: number;
+    readonly lineEnd?: number;
+    readonly section?: string;
     readonly stableEvidenceId?: string;
     readonly retrieverMix?: readonly string[];
     readonly parserType?: string;
     readonly documentType?: string;
     readonly documentArea?: string;
     readonly evidenceType?: string;
-    readonly evidenceLocation?: string;
     readonly confidence?: number;
 }
 export interface AutoRAGMappingEntry {

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" | "web-datasource-id-taken" | "web-search-failed" | "citation-without-result" | "line-reference-unverified" | "citation-irrelevant" | "citation-relevance-fallback" | "evidence-judged" | "evidence-judgment-fallback" | "memory-search-fallback" | "self-config-unavailable" | "self-config-rolled-back" | "organize-skill-unavailable" | "embedding-unavailable";
 export interface SearchDocumentDiagnostic {
     readonly code: SearchDocumentDiagnosticCode;
     readonly severity: SearchDocumentDiagnosticSeverity;
@@ -19,7 +19,12 @@ export interface SearchDocumentDiagnostic {
 }
 export interface SearchDocumentEvidence {
     readonly excerpt: string;
+    /** First line of the chunk in its parsed document, measured by the harness. */
     readonly lineNumber?: number;
+    /** Last line of the chunk in its parsed document. */
+    readonly lineEnd?: number;
+    /** Article or heading the chunk sits in. */
+    readonly section?: string;
 }
 export interface SearchDocumentResult {
     readonly number: number;

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

@@ -1,3 +1,4 @@
+import type { PackagedAgentSkill } from "./packaged-skill.js";
 /**
  * Host opt-in for agent self-configuration: the Jev `config` branch, where the
  * agent edits its own settings with the full `autorag-setup` skill in hand.
@@ -5,7 +6,7 @@
 export interface SelfConfigOptions {
     /** The active AutoRAG config file the agent may read and edit. */
     readonly configPath: string;
-    /** Override for the `autorag-setup` SKILL.md; defaults to the packaged skill. */
+    /** Override for the packaged `autorag-setup` skill file; defaults to the packaged skill. */
     readonly skillPath?: string;
     /**
      * Check the config file after a config turn changed it. Resolves to a
@@ -14,13 +15,14 @@ export interface SelfConfigOptions {
      */
     readonly validate?: (configPath: string) => Promise<string | undefined>;
 }
-/** Full text of the `autorag-setup` skill with its YAML front matter removed. */
-export declare function loadSetupSkill(skillPath?: string): string;
 export interface SelfConfigPromptInput {
     readonly query: string;
     readonly configPath: string;
     readonly agentDir: string;
-    readonly skill: string;
+    /** The loaded `autorag-setup` skill, embedded as a `<skill …>` invocation. */
+    readonly skill: PackagedAgentSkill;
+    /** 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/skill-invocation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The `<skill name="…" location="…">…</skill>` invocation block AutoRAG embeds
+ * in a turn prompt: the shape pi uses for its file-backed skills, with a
+ * path-opaque `location`. AutoRAG loads skills that have no path the model
+ * should resolve against (datasource skills and its own packaged skills), so
+ * the location names the skill without exposing a real filesystem path.
+ */
+export interface SkillInvocation {
+    /** Skill name, as listed in the prompt's skill listing. */
+    readonly name: string;
+    /** Opaque, path-free location: `datasource://<name>` or `autorag-skill://<name>`. */
+    readonly location: string;
+    /** Full skill instructions. */
+    readonly content: string;
+}
+/** Render one skill's full instructions in the shared invocation shape. */
+export declare function formatSkillInvocation(skill: SkillInvocation): string;

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, the extra/organize/config
+ * turn, 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/commands/evidence.d.ts

@@ -9,6 +9,8 @@ interface EvidenceView {
     readonly retrievalResultId?: string;
     readonly chunkIndex?: number;
     readonly lineNumber?: number;
+    readonly lineEnd?: number;
+    readonly section?: string;
     readonly metadata?: Record<string, unknown>;
 }
 export declare function evidenceFor(schema: MemorySchema, sessionId: string, resultNumber?: 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 {