@autorag/librarian 2.10.6 → 2.12.0

package/dist/agent/citation-numbers.d.ts

@@ -0,0 +1,68 @@
+import { type Static, Type } from "typebox";
+/** Custom session entry type under which a conversation persists its result numbers. */
+export declare const CITATION_NUMBERS_ENTRY_TYPE = "autorag.citation-numbers";
+declare const citationNumberEntrySchema: Type.TObject<{
+    source: Type.TString;
+    number: Type.TInteger;
+}>;
+/** One source and the result number (`[n]`) the user was shown for it. */
+export type CitationNumberEntry = Static<typeof citationNumberEntrySchema>;
+/**
+ * Entries a session persisted under {@link CITATION_NUMBERS_ENTRY_TYPE}. A
+ * malformed entry is skipped: its source is then numbered afresh, never
+ * under a number it was not shown with.
+ */
+export declare function parseCitationNumberEntries(data: unknown): CitationNumberEntry[];
+/** Highest result number among `entries`; 0 when there are none. */
+export declare function highestCitationNumber(entries: readonly CitationNumberEntry[]): number;
+/**
+ * The result numbers (`[1]`, `[2]`, ...) one conversation has shown the user.
+ *
+ * A source keeps the number it was first shown with in every later answer of
+ * the conversation, and a new source gets the next unused number. Numbers are
+ * never reissued, mirroring the `e<N>` ordinals of the `EvidenceLedger`: the
+ * quick and verification answers of one turn, and every turn after them,
+ * share one numbering, so a `[n]` a user saw never names a different source.
+ *
+ * The hosting session persists what {@link takeUnsaved} returns (through the
+ * sink installed with {@link setSink}) and rebuilds the numbers with
+ * {@link restore} when a conversation is resumed.
+ */
+export declare class CitationNumbers {
+    private readonly bySource;
+    /** Entries issued since the last {@link takeUnsaved}. */
+    private unsaved;
+    private sink;
+    /**
+     * The last number issued. Survives {@link clear} and {@link restore}: a
+     * conversation keeps earlier answers in view, so restarting at 1 would let
+     * an old `[n]` silently name a different source.
+     */
+    private lastNumber;
+    /** The number for `source`: the one it already has, else the next unused number. */
+    numberFor(source: string): number;
+    /** Forget every source. Numbers are never reissued, so a previous conversation's `[n]` stays unused. */
+    clear(): void;
+    /** Forget every source and restart at 1: for a run that owns no conversation, where no earlier `[n]` is in view. */
+    reset(): void;
+    /** Numbers issued since the last call, for the hosting session to persist. */
+    takeUnsaved(): CitationNumberEntry[];
+    /** Where {@link flush} writes numbers: the hosting session. Replaces any earlier sink. */
+    setSink(sink: ((entries: CitationNumberEntry[]) => void) | undefined): void;
+    /**
+     * Persist numbers issued since the last save right now. Answers are derived
+     * after a turn's last session event, so without this the final answer's new
+     * numbers would not reach the session file until the next turn. With no
+     * sink installed the numbers stay unsaved for the next save.
+     */
+    flush(): void;
+    /**
+     * Rebuild the numbers from persisted entries, such as the ones on the
+     * resumed conversation branch; a later entry for the same source replaces an
+     * earlier one. Numbers keep counting past every restored number and past
+     * `numberFloor`, the highest number issued anywhere in the conversation
+     * (other branches included).
+     */
+    restore(entries: readonly CitationNumberEntry[], numberFloor?: number): void;
+}
+export {};

package/dist/agent/citation-relevance.d.ts

@@ -0,0 +1,37 @@
+import type { CitedChunk } from "./answer-citations.js";
+import type { JevJudge } from "./jev-extension.js";
+/**
+ * The model sometimes cites a chunk that has nothing to do with the sentence it
+ * backs or with what the user asked: a table of contents, a navigation bar, a
+ * copyright footer, a generic introduction. Before the answer is returned,
+ * every cited chunk is put to Jev as one relevance question, and a chunk Jev
+ * finds unrelated is removed from the answer's citations.
+ *
+ * This is deliberately weaker than the memory judgment in `evidence-judgment.ts`
+ * ("does it directly support, and is it needed"): that gate decides what is
+ * worth remembering and rejects any chunk that does not state the claim. Here a
+ * chunk that is merely on topic, or backs only part of the claim, must stay, so
+ * the only thing rejected is evidence with no information on the subject at all.
+ */
+/** A chunk is kept when Jev's P(relevant) is at or above this; below it the chunk is rejected. */
+export declare const CITATION_RELEVANCE_FLOOR = 0.3;
+/** Jev question id prefix of one citation relevance check. */
+export declare const CITATION_QUESTION_ID_PREFIX = "citation:";
+export interface CitationRelevanceInput {
+    /** Everything the user typed in the conversation, oldest first; the last is the question being answered. */
+    readonly userMessages: readonly string[];
+    /** The chunks the answer cites, with the sentences citing each. */
+    readonly chunks: readonly CitedChunk[];
+}
+export interface CitationRelevance {
+    /** {@link CitedChunk.key} of every chunk Jev found unrelated. */
+    readonly rejected: ReadonlySet<string>;
+    /** Set when Jev gave no usable verdict for ANY chunk; nothing was rejected. Absent when Jev decided. */
+    readonly fallbackReason?: string;
+}
+/**
+ * Ask Jev, in one batched call, whether each cited chunk is relevant to the
+ * sentences that cite it and to what the user asked. Never throws: a rejecting
+ * judge rejects nothing and reports why, and a chunk Jev left unanswered is kept.
+ */
+export declare function judgeCitationRelevance(judge: JevJudge, input: CitationRelevanceInput): Promise<CitationRelevance>;

package/dist/agent/conversation-queries.d.ts

@@ -0,0 +1,31 @@
+/** Custom session entry type under which a conversation persists what the user typed. */
+export declare const CONVERSATION_QUERIES_ENTRY_TYPE = "autorag.queries";
+/** The queries a session persisted under {@link CONVERSATION_QUERIES_ENTRY_TYPE}; a malformed entry is skipped. */
+export declare function parseQueryEntries(data: unknown): string[];
+/**
+ * Everything the user typed in one conversation: each question and each
+ * steer, as typed. The transcript cannot stand in for it, because the first
+ * turn's user message there is the harness prompt that wraps the question
+ * with baseline evidence and formatting rules.
+ *
+ * The hosting session persists what {@link flush} hands to the sink and
+ * rebuilds the list with {@link restore} when a conversation is resumed or
+ * a new one starts, the way the evidence ledger and result numbers are.
+ */
+export declare class ConversationQueries {
+    private queries;
+    /** Queries added since the last {@link flush}. */
+    private unsaved;
+    private sink;
+    add(query: string): void;
+    /** Every query of the conversation, oldest first. */
+    all(): readonly string[];
+    /** Where {@link flush} writes queries: the hosting session. Replaces any earlier sink. */
+    setSink(sink: ((entries: string[]) => void) | undefined): void;
+    /** Persist queries added since the last save. With no sink installed they stay unsaved for the next save. */
+    flush(): void;
+    /** Replace the conversation's queries with already-persisted ones; an empty list forgets everything. */
+    restore(queries: readonly string[]): void;
+    /** Forget every query, saved or not: a run that owns no conversation starts over. */
+    reset(): void;
+}

package/dist/agent/convert-tool.d.ts

@@ -0,0 +1,28 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+import type { ConvertAndRelateResult, FileeConvertRequest } from "../convert/index.js";
+export declare const CONVERT_FILES_TOOL_NAME = "convert_files";
+export declare const LIST_FILE_CONVERSIONS_TOOL_NAME = "list_file_conversions";
+export type ConvertFilesDetails = ConvertAndRelateResult;
+export interface FileConversionProvider {
+    convertFiles(request: FileeConvertRequest, signal?: AbortSignal): Promise<ConvertFilesDetails>;
+    listFileConversions(from?: string, signal?: AbortSignal): Promise<string>;
+}
+declare const convertFilesSchema: Type.TObject<{
+    inputs: Type.TArray<Type.TString>;
+    to: Type.TString;
+    outputDir: Type.TOptional<Type.TString>;
+    recursive: Type.TOptional<Type.TBoolean>;
+    quality: Type.TOptional<Type.TInteger>;
+    overwrite: Type.TOptional<Type.TBoolean>;
+    skipExisting: Type.TOptional<Type.TBoolean>;
+    keepDates: Type.TOptional<Type.TBoolean>;
+}>;
+export declare function createConvertFilesTool(provider: FileConversionProvider): AgentTool<typeof convertFilesSchema, ConvertFilesDetails>;
+declare const listConversionsSchema: Type.TObject<{
+    from: Type.TOptional<Type.TString>;
+}>;
+export declare function createListFileConversionsTool(provider: FileConversionProvider): AgentTool<typeof listConversionsSchema, {
+    readonly from?: string;
+}>;
+export {};

package/dist/agent/evidence-persistence.d.ts

@@ -1,4 +1,6 @@
 import type { ExtensionFactory, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { type CitationNumbers } from "./citation-numbers.js";
+import { type ConversationQueries } from "./conversation-queries.js";
 import { type EvidenceLedger } from "./evidence-ledger.js";
 /** The part of pi's session manager the ledger is rebuilt from. */
 interface SessionEntries {
@@ -6,19 +8,23 @@ interface SessionEntries {
     getEntries(): SessionEntry[];
 }
 /**
- * Rebuild `ledger` for the conversation branch `session` is on. Evidence from
- * other branches stays out of reach (their transcripts are not in context), but
- * its ids still count: new evidence never reuses an id issued anywhere in the
- * conversation.
+ * Rebuild `ledger`, `numbers`, and `queries` for the conversation branch `session` is on.
+ * Evidence and result numbers from other branches stay out of reach (their
+ * transcripts are not in context), but their ids and numbers still count: new
+ * evidence and new results never reuse one issued anywhere in the conversation.
+ * What the user typed follows the branch exactly: a query typed on a branch the
+ * user left is not part of the conversation in view.
  */
-export declare function restoreEvidenceLedger(ledger: EvidenceLedger, session: SessionEntries): void;
+export declare function restoreConversationState(ledger: EvidenceLedger, numbers: CitationNumbers, queries: ConversationQueries, session: SessionEntries): void;
 /**
- * pi extension that keeps the conversation's evidence ledger in the session
- * file, next to the transcript that shows the model its `[eN]` ids. Evidence is
- * appended as the tools return it; switching, resuming, forking, or navigating
- * the session tree rebuilds the ledger from the branch now in view. An id the
- * model saw therefore resolves, and is never reissued, whatever turns, tool
+ * pi extension that keeps the conversation's evidence ledger, result numbers,
+ * and typed queries in the session file, next to the transcript that shows the
+ * model its `[eN]` ids and the user its `[n]` results. Evidence is appended as
+ * the tools return it, result numbers as answers are derived, and queries as
+ * they are typed; switching, resuming, forking, or navigating the session tree
+ * rebuilds all three from the branch now in view. An id the model saw therefore
+ * resolves, and an id or result number is never reissued, whatever turns, tool
  * calls, resumes, or restarts happened in between.
  */
-export declare function createEvidencePersistence(ledger: EvidenceLedger): ExtensionFactory;
+export declare function createEvidencePersistence(ledger: EvidenceLedger, numbers: CitationNumbers, queries: ConversationQueries): ExtensionFactory;
 export {};

package/dist/agent/index.d.ts

@@ -1,5 +1,6 @@
 export type { AutoRAGAgentOptions, AutoRefreshOptions } from "./agent.js";
 export { AutoRAGAgent } from "./agent.js";
+export { CONVERT_FILES_TOOL_NAME, type ConvertFilesDetails, createConvertFilesTool, createListFileConversionsTool, type FileConversionProvider, LIST_FILE_CONVERSIONS_TOOL_NAME, } from "./convert-tool.js";
 export { buildDatasourceSkillsPrompt, createLoadDatasourceSkillTool, type DatasourceSkillProvider, datasourceSkillLocation, formatDatasourceSkillInvocation, LOAD_DATASOURCE_SKILL_TOOL_NAME, type LoadDatasourceSkillDetails, toDatasourceAgentSkill, } from "./datasource-skill.js";
 export { createScanDuplicateDocumentsTool, SCAN_DUPLICATE_DOCUMENTS_TOOL_NAME, type ScanDuplicateDocumentsDetails, type ScanDuplicateDocumentsProvider, } from "./dupey-tool.js";
 export { createJevExtension, JEV_TOOL_NAME, type JevBackendName, type JevToolOptions, } from "./jev-extension.js";

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/mcp-client.d.ts

@@ -0,0 +1,27 @@
+import { type ExtensionFactory } from "@earendil-works/pi-coding-agent";
+/** pi's system-prompt section naming the MCP servers whose tools the model does not see declared. */
+export declare const MCP_SERVERS_SECTION = "mcp_servers";
+/**
+ * Tools pi's MCP integration owns. pi's `tools` allow-list keeps only named tools active, so every
+ * one of them has to be named: `mcp__*` covers each server tool, the rest are the codemode and
+ * tool-search entry points and the resource readers.
+ */
+export declare const MCP_TOOL_NAMES: string[];
+export interface AutoRAGMcpClient {
+    /** Extensions that connect the servers; the host registers them next to its own. */
+    readonly extensionFactories: readonly ExtensionFactory[];
+    /** Entries the session's `tools` allow-list needs so the extensions' tools stay active. */
+    readonly toolNames: readonly string[];
+}
+/**
+ * Connects the user's external MCP servers to an AutoRAG pi session, or returns `undefined` when
+ * `<agentDir>/mcp.json` is absent or names no enabled server, leaving the tool surface unchanged.
+ *
+ * Only the user-level file is read. pi would also load a project `.pi/mcp.json`, but that lets any
+ * directory AutoRAG starts in choose which processes run, so it is ignored by design. Entries go
+ * through `pi.registerMcpServer`, which validates them with pi's own rules; a rejected entry or an
+ * unreadable file is reported verbatim at session start and never stops the other servers.
+ */
+export declare function createAutoRAGMcpClient(agentDir: string): AutoRAGMcpClient | undefined;
+/** The prompt block for the servers pi reported in `sections`, or "" when it reported none. */
+export declare function mcpPromptAddendum(sections: Readonly<Record<string, string>> | undefined): string;

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/pi-session.d.ts

@@ -81,11 +81,19 @@ export interface AutoRAGPiInteractiveRuntimeOptions extends Omit<AutoRAGPiSessio
      * launch.
      */
     readonly updateNotice?: () => Promise<string | undefined>;
+    /**
+     * AutoRAG version shown on the welcome banner. Set only by the TUI: when present,
+     * every session start (launch, `/new`, `/resume`, `/reload`) replaces pi's startup
+     * header with the AutoRAG banner and hides pi's loaded-resource listing.
+     */
+    readonly welcomeVersion?: string;
 }
 export interface AutoRAGPiSession {
     readonly session: AgentSession;
     readonly baseToolNames: readonly string[];
     readonly sessionFile: string | undefined;
+    /** Stops what extensions started (MCP server processes), then disposes the session. */
+    readonly dispose: () => Promise<void>;
 }
 /** Adapts a pi-agent-core {@link AgentTool} to pi's extension {@link ToolDefinition}. */
 export declare function toToolDefinition(tool: AgentTool): ToolDefinition;

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;