@autorag/librarian 2.11.0 → 2.12.0

package/NOTICE

@@ -24,6 +24,9 @@ License: MIT
 @modelcontextprotocol/server@2.3.1
 License: Apache-2.0
 
+@parcel/watcher@2.6.0
+License: MIT
+
 chardet@2.2.0
 License: MIT
 
@@ -51,6 +54,9 @@ License: MIT
 pdfjs-dist@6.4.299
 License: Apache-2.0
 
+pi-ask-user@0.17.0
+License: MIT
+
 pi-discord-remote@0.2.4
 License: MIT
 

package/README.md

@@ -222,7 +222,7 @@ A fresh session — at launch and after `/new` (or `/reload`) — opens on AutoR
 
 Typing while a search runs works like steering one of Pi's own turns. **Enter** steers the running search: AutoRAG treats the text as a correction of a search that is going wrong, delivers it before the search's next model request (also between phases, where no turn is streaming), cuts in-flight retrieval short so the correction lands promptly, and always runs the verification phase so the answer reflects the correction. **Alt+Enter** queues a new question that runs after the current search answers. **Esc** stops the search instead of letting it continue into its next phase. Pi's registered `/` commands still run during a search; any other line starting with `/` (a path, for example) is a steer like any other text. A query typed after a search answers is a new search in the same session, as before.
 
-From the moment a question is submitted, a live progress widget sits above the editor: a spinner, the elapsed time, and one line per step the search is running (routing, splitting the question, each retrieval source with its hit count and time, ranking, the first answer, verification). A slow source shows its own running timer, a failing source shows its error text verbatim, and the widget disappears when the answer is final or **Esc** stops the search. While the model streams, Pi's own `Working` loader takes over and the widget keeps only the header and steps.
+From the moment a question is submitted, a live progress widget sits above the editor: a spinner, the elapsed time, and one line per step the search is running (routing, splitting the question, each retrieval source with its hit count and time, ranking, the first answer, verification). A slow source shows its own running timer, a failing source shows its error text verbatim, and the widget disappears when the answer is final or **Esc** stops the search. While the model streams, Pi's own `Working` loader takes over and the widget keeps only the header and steps. Every tool call also carries a short model-written intent (the `i` argument): Pi's `Working` loader shows the newest one, and `autorag search` and the desktop app receive it as progress, so the model does not write separate progress notes before tool calls.
 
 Update notices are AutoRAG's, not Pi's: `autorag tui` suppresses Pi's "run `pi update`" banner (Pi is a bundled host, not a separate install) and instead checks the published `@autorag/librarian` release, showing a one-line notice in the session when a newer version exists. Set `AUTORAG_NO_UPDATE_CHECK=1` to skip the lookup; `AUTORAG_UPDATE_CHECK_URL` overrides the registry endpoint.
 
@@ -263,6 +263,7 @@ bun add @autorag/librarian
 - **Rust Toolchain (Optional):** Automatically compiles Jikji (`jikji-cli`) if installed.
 - **MinSync:** Automatically downloaded and installed into `<workspace>/.autorag/bin` on first run.
 - **Everything (Windows only, bundled):** The package ships the portable Everything 1.4.1.1032 and its ES 1.1.0.38 CLI (x64 and ARM64, SHA-256 pinned). On Windows, AutoRAG extracts them into `<workspace>/.autorag/everything/` and runs a private, user-level instance that indexes only your configured search roots: no administrator rights, no Everything service, no whole-drive scan, no HTTP/ETP server, and no change to any Everything you already run. Set `"everything": false` in the config to turn it off. macOS and Linux are not affected.
+- **filee-cli (file conversion, automatic):** `autorag setup` and the TUI download the pinned filee-cli release (~85 MB, SHA-256 verified) into `<AUTORAG_HOME>/tools/filee-cli/<version>/`, so the agent can convert between 255 formats offline with `convert_files`. A `filee`/`filee-cli` already on `PATH` is used instead. Set `"filee": { "autoInstall": false }` to forbid the download or `"filee": { "enabled": false }` to remove the tools. Filee fetches its own engines (FFmpeg, Pandoc, LibreOffice, calibre, Ghostscript; hundreds of MB, only when a conversion needs one) on first use.
 - **FSearch (macOS/Linux only, separate install):** Install [`fsearch-cli`](https://github.com/NomaDamas/fsearch-mac) yourself (e.g. `brew install NomaDamas/fsearch-mac/fsearch-mac` (installs the `fsearch-cli` binary); GPL-2.0, spawned as a separate process, never bundled or linked). On macOS and Linux, AutoRAG builds a per-workspace database at `<workspace>/.autorag/fsearch/` indexing only your configured search roots, and keeps a `fsearch-cli watch` daemon live (FSEvents/inotify) for sub-second name search. It never touches the FSearch app's own database. Without fsearch-cli, name search falls back to a slow bounded filesystem walk. Set `"fsearch": false` in the config to turn it off. Windows is not affected (Everything covers it).
 
 ---
@@ -475,7 +476,7 @@ mirrored are kept and not re-parsed on the next run. `onProgress` reports `parse
 | `autorag health` | Check model provider authentication, token validity, and API reachability |
 | `autorag models list` | List chat models the pi runtime can resolve (built-ins, `models.json`, custom/extension providers) with provider auth status; never prints credential values |
 | `autorag update-check` | Compare the running `autorag` against the published npm version (also runs on `autorag tui` launch) |
-| `autorag tui` | Open Pi's interactive librarian TUI (`/login`, `/model`, `/resume`, …); `--telegram` / `--whatsapp` / `--discord` add the Telegram / WhatsApp / Discord remote-control bridges |
+| `autorag tui` | Open Pi's interactive librarian TUI (`/login`, `/model`, `/resume`, …); the agent can stop and ask you a multiple-choice or open question through the [`ask_user` tool](docs/ask-user.md); `--telegram` / `--whatsapp` / `--discord` add the Telegram / WhatsApp / Discord remote-control bridges; `--permission-mode ask\|auto\|full` (Shift+Tab, `/permissions`) sets the [approval gate for file changes](docs/permissions.md) |
 | `autorag duplicates [DIR]` | Read-only scan for exact and near-duplicate document families with `dupey` |
 | `autorag lite ...` | CLI bootstrap, indexing repair, terminal maintenance, and fallback interface; agents use MCP for normal Lite operation |
 | `autorag memory inspect` | Render a read-only, path-opaque snapshot of retrieval memory (judged evidence, curated results, evidence chunks, insights); model-free |
@@ -649,7 +650,7 @@ AutoRAG Agent connects to external tools and communication platforms using dedic
 | **macOS Spotlight** | `spotlight` | Native `mdfind` CLI | macOS system metadata and content index | System Native |
 | **Browser History** | `hister` | [Hister](https://github.com/asciimoo/hister) server (AGPL-3.0-or-later, separate program, HTTP API) | Pages visited in Chrome/Chromium/Firefox, captured by Hister's own extension and indexed by Hister (web pages only; its local-file indexing is never used) | Lexical full-text; optional Semantic via Hister's own embedding endpoint |
 
-For configuration syntax and connector details, see [docs/datasource-skills.md](docs/datasource-skills.md). Non-interactive `sync`/`index` steps get a 30-minute per-connector budget (`connector.indexTimeoutMs`) because first-run imports routinely take minutes; interactive search keeps its 60-second default.
+For configuration syntax and connector details, see [docs/datasource-skills.md](docs/datasource-skills.md). Non-interactive `sync`/`index` steps get a one-hour per-connector budget (`connector.indexTimeoutMs`) because first-run imports routinely take minutes; interactive search keeps its 60-second default.
 
 ---
 
@@ -729,7 +730,7 @@ Deep dive into AutoRAG Agent's architecture, security, and integration guides:
 - **[Telegram Remote Control](docs/telegram.md):** Ask the librarian from a Telegram chat through a running `autorag tui --telegram` session: setup, commands, and keeping it alive.
 - **[Datasource Skills Reference](docs/datasource-skills.md):** Full configuration contracts, connection aliases, and connector options.
 - **[Apple Calendar & Reminders via EventKit MCP](docs/eventkit-mcp.md):** macOS-only: read Calendar events and Reminders (Google/iCloud/Exchange accounts already in Calendar.app) by running `mcp-server-apple-events` beside `autorag-mcp`. Live, read-only; not indexed.
-- **[Jev Decisions](docs/jev-decisions.md):** Jev query pipeline, **on by default** via Dazzi Models when signed in (OpenRouter otherwise): it routes each question to a direct answer (intrinsic knowledge) or local search (everything needing more information; web search is left to the agent after the fast answer), splits multi-part questions into up to five parallel searches (`dazzi/openai/gpt-6-luna` when signed in, else `openrouter/qwen/qwen3.7-flash`), picks which registered datasources to search before the fast answer, and ends the run after the fast answer when that answer is complete. Also covers the `jev` judgment tool, backends (OpenRouter, TypeSafe, Vercel AI Gateway), and how to opt out.
+- **[Jev Decisions](docs/jev-decisions.md):** Jev query pipeline, **on by default** via Dazzi Models when signed in (OpenRouter otherwise): it routes each question to a direct answer (intrinsic knowledge), local search (everything needing more information; web search is left to the agent after the fast answer), `organize` (move, rename, convert, or sort files and folders), or `extra` (any other action such as committing code; no retrieval), splits multi-part questions into up to five parallel searches (`dazzi/openai/gpt-6-luna` when signed in, else `openrouter/qwen/qwen3.7-flash`), picks which registered datasources to search before the fast answer, and ends the run after the fast answer when that answer is complete. Also covers the `jev` judgment tool, backends (OpenRouter, TypeSafe, Vercel AI Gateway), and how to opt out.
 - **[Manual QA & Datasource Test Harnesses](docs/manual-qa-datasources.md):** Real-world testing guides for Discord, KakaoTalk, Slack, Notion, and email.
 - **[Supply Chain Security & License Audits](docs/supply-chain.md):** Software bill of materials (SBOM) and dependency gate policies.
 - **[Competitive Landscape Study](docs/competitive-landscape-2026-09.md):** In-depth analysis of why in-place federation outperforms centralized RAG.
@@ -742,6 +743,7 @@ Deep dive into AutoRAG Agent's architecture, security, and integration guides:
 AutoRAG Agent is an open-source project built by the community. We welcome contributions, bug reports, datasource connectors, and ideas!
 
 - **Contributing:** Feel free to open an issue or pull request. Start with [CONTRIBUTING.md](CONTRIBUTING.md) — development setup, the `make ci` check we ask for, the `Signed-off-by` trailer every commit needs, and when to run the live end-to-end lanes. [MAINTAINERS](MAINTAINERS) lists who reviews which area. AI tools are allowed; unverified dumps are not — see [AI_POLICY.md](AI_POLICY.md).
+- **Discussions:** For questions, usage help, ideas, and open-ended design talk, please use [GitHub Discussions](https://github.com/Marker-Inc-Korea/AutoRAG/discussions) instead of opening an issue. Keep issues for confirmed bugs and concrete, actionable work.
 - **Security:** Private vulnerability reports and the response SLA live in [SECURITY.md](SECURITY.md).
 - **GitHub Contributors:** [View all contributors](https://github.com/Marker-Inc-Korea/AutoRAG/graphs/contributors) on GitHub.
 
@@ -758,6 +760,7 @@ AutoRAG Agent stands on the shoulders of fantastic open-source projects:
 - **[FSearch](https://github.com/cboxdoerfer/fsearch)** and **[fsearch-cli](https://github.com/NomaDamas/fsearch-mac)** — Everything-style file-name search for macOS/Linux (GPL-2.0-or-later). Never bundled or linked: users install fsearch-cli separately and AutoRAG spawns it as a separate process (mere aggregation per the FSF GPL FAQ).
 - **[Hister](https://github.com/asciimoo/hister)** by [asciimoo](https://github.com/asciimoo) and contributors — Self-hosted browser web-history search (AGPL-3.0-or-later). Never bundled, linked, copied, or modified: users run Hister as a separate program and AutoRAG only calls its public HTTP search API (mere aggregation). Hister is always named as the backend of the `hister` datasource.
 - **[dupey](https://github.com/NomaDamas/dupey)** by [NomaDamas](https://github.com/NomaDamas) — Fast duplicate and near-duplicate document family detection.
+- **[Filee](https://github.com/KnifeLemon/Filee)** by [KnifeLemon](https://github.com/KnifeLemon) — Offline conversion of 240+ file formats (MIT). Never bundled or linked: AutoRAG downloads the SHA-256-pinned [`filee-cli`](https://github.com/NomaDamas/filee-cli) release (NomaDamas' CLI-only redistribution, MIT) into `<AUTORAG_HOME>/tools/filee-cli/` on `autorag setup` / first conversion and spawns it as a separate process. An existing `filee`/`filee-cli` on `PATH` or `filee.binaryPath` wins. Filee downloads its own engines (FFmpeg, Pandoc, LibreOffice, …) on first use.
 - **Federated CLI Authors:** External datasource tools [`lazykatok`](https://github.com/changeroa/lazykatok), [`discrawl`](https://github.com/openclaw/discrawl), [`mailcrawl`](https://github.com/NomaDamas/mailcrawl), [`wacrawl`](https://github.com/openclaw/wacrawl), [`telecrawl`](https://github.com/openclaw/telecrawl), [`slacrawl`](https://github.com/openclaw/slacrawl), [`notcrawl`](https://github.com/openclaw/notcrawl), and [`rclone`](https://rclone.org).
 - **[kordoc](https://github.com/chrisryugj/kordoc)** by [chrisryugj](https://github.com/chrisryugj) — HWP/HWPX/HWPML, PDF, DOCX and XLSX parsing with nested-table fidelity, used as AutoRAG's default document parser.
 

package/dist/agent/agent.d.ts

@@ -1,5 +1,6 @@
 import type { Agent, AgentTool } from "@earendil-works/pi-agent-core";
 import type { Api, ImageContent, Model } from "@earendil-works/pi-ai";
+import { type FileeCliOptions, type FileeConvertRequest } from "../convert/index.js";
 import { type DatasourceRetryOptions } from "../datasource/retry.js";
 import type { DatasourceIndexResult, DatasourceSkill } from "../datasource/types.js";
 import { type DupeyCliOptions } from "../dupey/index.js";
@@ -15,10 +16,12 @@ import { RetrievalEngine } from "../retrieval/engine.js";
 import { RetrievalMethodRegistry } from "../retrieval/registry.js";
 import type { DatasourceCatalogEntry } from "../retrieval/selection.js";
 import type { RetrievalDiagnostic, RetrievalOptions, RetrievalResult } from "../retrieval/types.js";
+import { type ConvertFilesDetails } from "./convert-tool.js";
 import { type DatasourceAgentSkill } from "./datasource-skill.js";
 import { type ScanDuplicateDocumentsDetails } from "./dupey-tool.js";
 import { type JevToolOptions } from "./jev-extension.js";
 import { type JikjiFindProviderResult } from "./jikji-find-tool.js";
+import { PermissionController, type PermissionMode } from "./permission-gate.js";
 import { type AutoRAGPiInteractiveRuntime, type AutoRAGPiSession } from "./pi-session.js";
 import { type RefreshProgressCounts, type RefreshProgressPhase } from "./refresh-progress.js";
 import { type SearchDocumentDiagnostic, type SearchDocumentsResponse, type SearchDocumentsStreamEvent } from "./search-documents.js";
@@ -256,6 +259,12 @@ export interface AutoRAGAgentOptions {
     autoRefresh?: AutoRefreshOptions;
     parserOptions?: DefaultParserRegistryOptions;
     dupey?: DupeyCliOptions | false;
+    /**
+     * Filee command line behind `convert_files` and `list_file_conversions`.
+     * `false` leaves both tools out. The duplicate-family check on converted
+     * copies follows `dupey`.
+     */
+    filee?: FileeCliOptions | false;
     /**
      * Jev (TypeSafe's judgment model: typed questions in, calibrated
      * probabilities out). When set, the two-phase search asks Jev before the
@@ -358,6 +367,15 @@ export interface AutoRAGAgentOptions {
      * owner pairing live in pi's `telegram.json`, never in AutoRAG config.
      */
     telegram?: boolean;
+    /**
+     * Approval gate for what the agent does to existing files. `full` (the programmatic default) installs a
+     * gate that never asks; `ask` and `auto` approve deletes, moves, renames, and in-place edits of originals
+     * (copying and creating new files never ask). `auto` asks Jev first and only falls back to the user when
+     * Jev will not approve. See {@link PermissionMode}.
+     */
+    permissionMode?: PermissionMode;
+    /** Share one controller (mode, session grants) with a host that switches modes itself. Wins over `permissionMode`. */
+    permissionController?: PermissionController;
 }
 /** Post-merge reranking options. Mirrors the CLI `RerankConfig` (secrets via env). */
 export interface RerankAgentOptions {
@@ -406,6 +424,8 @@ export declare class AutoRAGAgent {
     private readonly memory;
     private readonly runLogger;
     private lastQuery;
+    /** What the user has said in this conversation; Jev's permission gate judges file changes against it. */
+    private readonly userRequests;
     private lastSessionId;
     private activeRun;
     /**
@@ -428,6 +448,10 @@ export declare class AutoRAGAgent {
      * run starts from an empty ledger.
      */
     private readonly evidenceLedger;
+    /** The result numbers (`[n]`) this conversation has shown, kept next to the ledger's `e<N>` ordinals. */
+    private readonly citationNumbers;
+    /** Everything the user typed in this conversation; Jev reads it to judge whether a citation relates to what was asked. */
+    private readonly conversationQueries;
     private preliminaryCallback;
     /** Per-phase thinking levels of the two-phase search. */
     private readonly fastThinkingLevel;
@@ -460,10 +484,14 @@ export declare class AutoRAGAgent {
     private readonly datasourceAgentSkills;
     private readonly parserOptions;
     private readonly dupeyOptions;
+    private readonly fileeOptions;
     /** pi extension registering the optional `jev` tool; undefined when disabled. */
     private readonly jevExtension;
     /** Jev judge shared by the `jev` tool and the query router; undefined when disabled. */
     private readonly jevJudge;
+    /** Mode and grants of the file-change approval gate; shared by every pi session this agent creates. */
+    private readonly permissions;
+    private readonly permissionGate;
     /** Self-configuration, enabled only with Jev on a local session. */
     private readonly selfConfig;
     private readonly queryDecompositionModel;
@@ -497,11 +525,15 @@ export declare class AutoRAGAgent {
     /** The memory context loaded for the in-flight run; cleared whenever a run starts. */
     private memoryContextCache;
     private readonly discordRemote;
+    /** Whether the bound interactive session offers `ask_user`; the phase prompts name it only then. */
+    private askUserOffered;
     private activeRetrievalOptions;
     private readonly toolBurstGuard;
     private readonly limits;
     private readonly refreshLimits;
     constructor(options: AutoRAGAgentOptions);
+    convertFiles(request: FileeConvertRequest, signal?: AbortSignal): Promise<ConvertFilesDetails>;
+    listFileConversions(from?: string, signal?: AbortSignal): Promise<string>;
     scanDuplicateDocuments(): Promise<ScanDuplicateDocumentsDetails>;
     /**
      * Reference memory for the current question: everything judged earlier in
@@ -544,6 +576,8 @@ export declare class AutoRAGAgent {
     private configureSearchSession;
     private recordSearchToolEvent;
     private currentSystemPromptConfig;
+    /** The approval gate's controller: read or switch the permission mode of this agent's sessions. */
+    get permissionControl(): PermissionController;
     subscribe(listener: Parameters<Agent["subscribe"]>[0]): () => void;
     createPiInteractiveRuntime(): Promise<AutoRAGPiInteractiveRuntime>;
     /**
@@ -565,7 +599,12 @@ export declare class AutoRAGAgent {
      * matters, so the steer reaches the model before the next request.
      */
     private interruptibleBySteer;
-    /** Resolve the model's inline `[eN]` citations against this run's evidence and derive the structured results. */
+    /**
+     * Resolve the model's inline `[eN]` citations against this run's evidence and derive the structured results.
+     * With Jev on, every cited chunk is first checked for relevance to the sentence that cites it and to what
+     * the user typed in this conversation; a chunk Jev finds unrelated (a table of contents, a footer) is dropped
+     * from the citations before the answer is returned or judged for memory.
+     */
     private deriveAnswer;
     /**
      * Routes one TUI input the way pi routes typed input for its own turns. With
@@ -718,6 +757,12 @@ export declare class AutoRAGAgent {
      * continues on the retrieval-order fallback.
      */
     private reportRerankFailure;
+    /**
+     * Sentence for the phase prompts that forbid tool calls: `ask_user` is not a search tool, and a request
+     * that hinges on a choice only the user can make must be asked, not guessed. Empty when the session does
+     * not offer the tool.
+     */
+    private askUserException;
     /**
      * Fast-phase prompt for two-phase searches. The baseline retrieval context
      * is already gathered, so the model answers immediately with minimal thinking,
@@ -736,6 +781,24 @@ export declare class AutoRAGAgent {
      * reply is the final answer.
      */
     buildDirectAnswerPrompt(query: string): string;
+    /**
+     * Tools an `organize` turn keeps: pi's file tools plus the converter, the
+     * duplicate scan, and file-name discovery, whichever this agent registered.
+     * The retrieval, datasource, and web tools stay out: the turn acts on files.
+     */
+    private organizeToolNames;
+    /**
+     * Prompt for a request Jev routed to `organize`: act on files and folders
+     * (move, rename, convert, sort). No retrieval ran and no verification
+     * follows; the model's plain final message is the answer.
+     */
+    buildOrganizePrompt(query: string): string;
+    /**
+     * Prompt for a request Jev routed to `extra`: a task that is neither
+     * knowledge, the user's records, file organization, nor configuration.
+     * The model acts with every tool it has; there is no retrieval or verification phase.
+     */
+    buildExtraPrompt(query: string): string;
     /** Discovery-tool hint naming only the registered discovery tools; empty when none. */
     private discoveryHint;
     /**

package/dist/agent/answer-citations.d.ts

@@ -1,3 +1,4 @@
+import type { CitationNumbers } from "./citation-numbers.js";
 import { type EvidenceLedger } from "./evidence-ledger.js";
 import type { AutoRAGResultsDetails } from "./results.js";
 import type { SearchDocumentDiagnostic } from "./search-documents.js";
@@ -5,6 +6,31 @@ export interface DerivedAnswer {
     readonly details: AutoRAGResultsDetails;
     readonly diagnostics: readonly SearchDocumentDiagnostic[];
 }
+/**
+ * Identity of one cited chunk: the source plus the recorded chunk text. A
+ * source can back several chunks, so a chunk is judged and excluded on its own.
+ */
+export declare function citedChunkKey(ref: {
+    readonly source: string;
+    readonly content?: string;
+}): string;
+/** One chunk the answer cites, with the sentences that cite it. */
+export interface CitedChunk {
+    /** {@link citedChunkKey} of the chunk. */
+    readonly key: string;
+    readonly source: string;
+    readonly content: string;
+    /** Each distinct sentence ending in a marker that cites this chunk, in answer order. */
+    readonly sentences: readonly string[];
+}
+/**
+ * Every chunk the answer cites, read from the raw markers. It resolves ids the
+ * way {@link deriveResultsFromAnswer} does but numbers nothing, so judging a
+ * citation never touches the conversation's result numbers.
+ */
+export declare function citedChunks(text: string, ledger: EvidenceLedger, options: {
+    readonly allowLocalFiles: boolean;
+}): CitedChunk[];
 /**
  * Turn the model's plain answer into the structured results the rest of the
  * harness consumes. The model cites with the evidence ids the retrieval tools
@@ -12,11 +38,17 @@ export interface DerivedAnswer {
  * itself. Each id is resolved against the run's evidence ledger, so a source,
  * method, and chunk always come from recorded evidence, never from model text.
  *
- * Results are one per cited source, numbered by first appearance, and every
- * marker in the returned answer is rewritten to its result number (`[1]`).
+ * Results are one per cited source, in order of first appearance in this answer. A source's
+ * number comes from the conversation's {@link CitationNumbers}: a source
+ * numbered in an earlier answer (or an earlier phase of this turn) keeps its
+ * number, a new source gets the next unused one, and every marker in the
+ * returned answer is rewritten to its result number (`[1]`).
  * A marker that matches no evidence, and any numeric marker the model wrote on
  * its own, is dropped and reported: it can never point at the wrong result.
  */
 export declare function deriveResultsFromAnswer(text: string, ledger: EvidenceLedger, options: {
     readonly allowLocalFiles: boolean;
+    readonly numbers: CitationNumbers;
+    /** Chunks ({@link citedChunkKey}) a relevance judgment rejected: a citation of only these is dropped silently. */
+    readonly excludedChunks?: ReadonlySet<string>;
 }): DerivedAnswer;

package/dist/agent/answer-guidelines.d.ts

@@ -34,8 +34,8 @@ export declare const ANSWER_UNCERTAINTY_RULE = "**Uncertainty placement**: when
 /**
  * Inline evidence citations. The model writes the id the retrieval tools print
  * next to each result; the harness resolves it to the recorded source and
- * renumbers the markers `[1]`, `[2]`, ... in order of first appearance, so the
- * caller only ever sees numbered citations backed by recorded evidence.
+ * renumbers the markers `[1]`, `[2]`, ... (a source keeps its number for the whole
+ * conversation), so the caller only ever sees numbered citations backed by recorded evidence.
  */
 export declare const ANSWER_CITATION_RULE = "**Citations**: cite supporting evidence inline with the evidence id shown next to each retrieved result, in square brackets (e.g. [e3], or [e3][e7] for two). Copy ids exactly; never invent one. For a local file you opened yourself with `bash`, cite `[file:<absolute path>]`. Cite the evidence that backs a sentence at the end of that sentence. Do not cite numbers, paths, or anything else.";
 /**

package/dist/agent/ask-user.d.ts

@@ -0,0 +1,8 @@
+/** Tool the `pi-ask-user` extension registers; pi's allow-list must name it to keep it active. */
+export declare const ASK_USER_TOOL_NAME = "ask_user";
+/**
+ * Entry file of the community `pi-ask-user` extension (the most-installed pi package for this: Claude
+ * Code's AskUserQuestion, with a searchable single/multi-select sheet, freeform answers, and 2-4 question
+ * batches). It ships TypeScript source and no `main`, so pi's own extension loader runs it from this path.
+ */
+export declare function resolveAskUserExtensionPath(): string;

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

@@ -0,0 +1,45 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+import type { AutomationRunRecord } from "../automation/run.js";
+import { type ServiceCommandExec } from "../automation/service.js";
+export declare const MANAGE_AUTOMATIONS_TOOL_NAME = "manage_automations";
+declare const manageAutomationsSchema: Type.TObject<{
+    action: Type.TUnion<[Type.TLiteral<"list">, Type.TLiteral<"save">, Type.TLiteral<"delete">, Type.TLiteral<"run">, Type.TLiteral<"install_service">, Type.TLiteral<"uninstall_service">]>;
+    id: Type.TOptional<Type.TString>;
+    automation: Type.TOptional<Type.TObject<{
+        paths: Type.TArray<Type.TString>;
+        events: Type.TOptional<Type.TArray<Type.TUnion<[Type.TLiteral<"create">, Type.TLiteral<"update">, Type.TLiteral<"delete">]>>>;
+        include: Type.TOptional<Type.TArray<Type.TString>>;
+        exclude: Type.TOptional<Type.TArray<Type.TString>>;
+        run: Type.TOptional<Type.TArray<Type.TString>>;
+        agent: Type.TOptional<Type.TObject<{
+            profile: Type.TString;
+            task: Type.TString;
+            retrieval: Type.TOptional<Type.TObject<{
+                searchAll: Type.TOptional<Type.TBoolean>;
+                datasources: Type.TOptional<Type.TArray<Type.TString>>;
+            }>>;
+        }>>;
+        appendFiles: Type.TOptional<Type.TBoolean>;
+        debounceMs: Type.TOptional<Type.TInteger>;
+        timeoutMs: Type.TOptional<Type.TInteger>;
+    }>>;
+    events: Type.TOptional<Type.TArray<Type.TObject<{
+        type: Type.TUnion<[Type.TLiteral<"create">, Type.TLiteral<"update">, Type.TLiteral<"delete">]>;
+        path: Type.TString;
+    }>>>;
+}>;
+export interface ManageAutomationsToolOptions {
+    readonly home?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly exec?: ServiceCommandExec;
+    readonly waitForRunningMs?: number;
+}
+export interface ManageAutomationsDetails {
+    readonly action: string;
+    readonly id?: string;
+    readonly run?: AutomationRunRecord;
+}
+export declare function createManageAutomationsTool(options?: ManageAutomationsToolOptions): AgentTool<typeof manageAutomationsSchema, ManageAutomationsDetails>;
+export {};

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

@@ -0,0 +1,23 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { type EvidenceLedger } from "./evidence-ledger.js";
+/** `file://` URL of an absolute local path, an http(s) URL as is, otherwise undefined (a datasource id, a message id). */
+export declare function openableTarget(source: string): string | undefined;
+/**
+ * Rewrite the citation markers of an assistant answer into Markdown links, so
+ * pi renders them as terminal hyperlinks that open the cited file or page.
+ *
+ * `[e3]` and `[e3, e7]` keep their brackets and ids; each id that resolves to
+ * an openable source becomes a link. `[file:/abs/path]` becomes `[<file name>]`
+ * linked to that file. Markers that resolve to nothing openable stay as the
+ * model wrote them.
+ *
+ * `sourceOf` maps an evidence id to its recorded source; `isFile` says whether
+ * a `[file:...]` path is a real local file.
+ */
+export declare function linkCitations(markdown: string, sourceOf: (id: string) => string | undefined, isFile: (path: string) => boolean): string;
+/**
+ * pi extension that makes the citations in the interactive transcript
+ * clickable. The model cites by evidence id; the ledger recorded the source
+ * each id names, so the link target is never model-written text.
+ */
+export declare function createCitationLinks(ledger: EvidenceLedger): ExtensionFactory;

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