@autorag/librarian 2.11.0 → 2.13.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).
 
 ---
@@ -460,7 +461,9 @@ mirrored are kept and not re-parsed on the next run. `onProgress` reports `parse
 (`processed`/`total` are files, `currentVirtualPath` is the file about to be processed) and
 `datasources` (`processed`/`total` are datasource skills). During the parse phase
 `.autorag/refresh-progress.json` also carries the running `sourceFiles.total` and
-`parsedCounts`. Without these options a refresh behaves as before.
+`parsedCounts`, refreshed every 25 files rather than per file. The marker is replaced with a
+retried rename (an in-place overwrite if a reader keeps the destination held, as on Windows).
+Without these options a refresh behaves as before.
 
 ---
 
@@ -475,7 +478,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 |
@@ -600,7 +603,10 @@ and `skills/autorag-setup` only when the agent should also drive the
 model-backed librarian, and `skills/autorag-doctor` for diagnostics. Other
 agents read their own skill directories; copy the same setup folder there and
 reload the agent session so it picks up the MCP registration instructions.
-Do not copy or retain the removed `autorag-lite-search` skill.
+Do not copy or retain the removed `autorag-lite-search` skill. The package also
+ships `internal-skills/`, which holds the librarian's own turn rules (for
+example `internal-skills/organize/`) — those are never parent-agent skills, so
+do not copy them into another agent.
 
 ### Quick Agent Workflow
 
@@ -649,7 +655,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 +735,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 local search (everything needing more information, including the public web when the question needs recent public facts), `extra` (a knowledge answer or any other action such as committing code; one turn with every tool, no retrieval), `organize` (move, rename, convert, or sort files and folders), or its own `config` branch, and keeps a weakly-favored non-local verdict on local search through a 0.75 confidence floor. It also 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 +748,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 +765,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,13 @@ 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 { type PackagedAgentSkill } from "./packaged-skill.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,11 +260,18 @@ 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
-     * fast answer whether the question is answerable from intrinsic knowledge
-     * (direct answer) or needs local search, and whether to decompose it; after the fast answer, whether
+     * fast answer which branch handles the question (local search, file
+     * organization, an extra task, or — in a local host — its own configuration)
+     * and whether to decompose it; after the fast answer, whether
      * verification is needed. It also exposes the `jev` tool.
      *
      * The CLI config enables this by default on OpenRouter (`buildAgentOptions`
@@ -288,6 +299,12 @@ export interface AutoRAGAgentOptions {
      * message.
      */
     selfConfig?: SelfConfigOptions;
+    /**
+     * Override for the packaged `organize` skill file that the Jev `organize`
+     * branch loads into its turn; defaults to the packaged skill. Present for a
+     * host that ships its own organize rules, and for tests.
+     */
+    organizeSkillPath?: string;
     /**
      * Question decomposition used by the Jev query pipeline. `model` (with its
      * `apiKey`) is the LLM that splits one question into at most five search
@@ -358,6 +375,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 +432,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 +456,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,12 +492,18 @@ 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;
+    /** Override for the packaged organize skill the `organize` branch loads; undefined keeps the packaged one. */
+    private readonly organizeSkillPath;
     private readonly queryDecompositionModel;
     /** Web search options for the agent's `web_search` / `web_fetch` tools; undefined when web tools are off. */
     private readonly webSearchOptions;
@@ -497,11 +535,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 +586,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 +609,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
@@ -677,39 +726,52 @@ export declare class AutoRAGAgent {
     private shouldFollowUp;
     /**
      * Jev query pipeline, run before the fast answer. Jev picks the branch
-     * (direct answer or local search) and whether the question
-     * needs decomposition; a "yes" splits it into at most five search queries
-     * with the configured decomposition model (default: the session model). On
-     * the local branch, Jev also judges, per registered datasource, whether it
-     * must be searched (in parallel with decomposition). Without Jev, and on any
-     * routing failure, this is today's single local search for the original
-     * question with no datasource search.
+     * (local search, file organization, an extra task, AutoRAG configuration)
+     * and whether the question needs decomposition; a "yes" splits it into at
+     * most five search queries with the configured decomposition model
+     * (default: the session model). On the local branch, Jev also judges, per
+     * registered datasource, whether it must be searched (in parallel with
+     * decomposition). Without Jev, and on any routing failure, this is today's
+     * single local search for the original question with no datasource search.
+     * A non-local branch that misses the confidence floor is not a failure: it
+     * becomes a full local plan, decomposition and datasource check included.
      */
     private planQuery;
     /**
      * Jev datasource check for the local branch: one `noul` per configured
-     * datasource that has retrieval methods, with where similar past questions
-     * were answered (from retrieval memory) in the state. Returns the ids to
-     * search with every query before the rerank; a failed check searches none.
+     * datasource that has retrieval methods, plus the public web when its tools
+     * are enabled, with where similar past questions were answered (from
+     * retrieval memory) in the state. Returns the datasource ids and whether the
+     * web is to be searched with every query before the rerank; a failed check
+     * searches neither.
      */
     private selectSearchDatasources;
     /**
-     * Baseline local evidence for the fast answer. Jikji, MinSync, and every
-     * Jev-selected datasource run for every search query in parallel (MinSync
-     * itself queues per workspace), the per-query hits are interleaved and
-     * deduplicated into one pool, and that pool is reranked against the
-     * original question.
+     * Baseline local evidence for the fast answer. Jikji, MinSync, every
+     * Jev-selected datasource, and (when Jev selected it) one web search run for
+     * every search query in parallel (MinSync itself queues per workspace), the
+     * per-query hits are interleaved and deduplicated into one pool, and that
+     * pool is reranked against the original question.
      */
     private prefetchInitialRetrievalContext;
+    /**
+     * One web search for the baseline, on the same provider chain, ordering, and
+     * credentials as the `web_search` tool. Hits carry the URL as their source
+     * and the title plus snippet as their content, so they merge, rerank, and
+     * register like any other candidate. A failure contributes no evidence and
+     * is reported by the caller; a steer abort is the user stopping the search,
+     * not a failure.
+     */
+    private prefetchWebSearch;
     /**
      * Rerank the pre-fast-answer baseline pool — Jikji answer paths, MinSync
-     * chunks, and Jev-selected datasource chunks — down to the configured
-     * `rerank.topN`. With decomposition the pool merges every search query's
-     * hits (interleaved), capped at the same per-source sizes as a single query
-     * so the rerank request does not grow with the query count. Returns
-     * `undefined` when reranking is disabled or the pool is empty. A configured
-     * reranker that is unavailable, throws, or returns nothing for a non-empty
-     * pool throws, so the caller can report it and fall back.
+     * chunks, Jev-selected datasource chunks, and prefetched web hits — down to
+     * the configured `rerank.topN`. With decomposition the pool merges every
+     * search query's hits (interleaved), capped at the same per-source sizes as a
+     * single query so the rerank request does not grow with the query count.
+     * Returns `undefined` when reranking is disabled or the pool is empty. A
+     * configured reranker that is unavailable, throws, or returns nothing for a
+     * non-empty pool throws, so the caller can report it and fall back.
      */
     private rerankPrefetchPool;
     /**
@@ -718,10 +780,23 @@ 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 exception to the no-tools rule, naming only the web tools this
+     * session actually registered. Empty when web tools are off, so the prompt
+     * never mentions a tool the model does not have.
+     */
+    private fastPhaseWebHint;
     /**
      * Fast-phase prompt for two-phase searches. The baseline retrieval context
      * is already gathered, so the model answers immediately with minimal thinking,
-     * as plain text, without any further tool calls.
+     * as plain text, without further retrieval; the web tools are the only
+     * exception, for public facts the baseline cannot settle.
      */
     buildFastAnswerPrompt(query: string, options: RetrievalOptions, baseline: string): string;
     /**
@@ -731,17 +806,45 @@ export declare class AutoRAGAgent {
      */
     private isConversationTurn;
     /**
-     * Prompt for a question Jev routed to a direct answer: general knowledge or
-     * small talk. No retrieval ran and no verification phase follows, so the
-     * reply is the final answer.
+     * Prompt for a request Jev routed to `organize`: act on files and folders
+     * (move, rename, convert, sort). No route changes the active tools any more,
+     * so the prompt names the tools the task uses and the ones it must not, and
+     * carries the loaded organize skill with the rules. No retrieval ran and no
+     * verification follows; the model's plain final message is the answer.
+     */
+    buildOrganizePrompt(query: string, skill: PackagedAgentSkill): string;
+    /**
+     * The tool-scope sentence of an `organize` turn: the tools the task uses and
+     * the content-retrieval and web tools it must not call. Every route keeps the
+     * whole tool set now, so the prompt is what scopes the turn; both lists name
+     * only tools this agent actually registered, so the prompt never points the
+     * model at a tool the session does not have.
+     */
+    private organizeToolScope;
+    /**
+     * Prompt for a request Jev routed to `extra`: no branch had a confident
+     * non-local verdict, and handling it needs no search of the user's records
+     * first. Nothing was retrieved and nothing follows this turn — no fast
+     * answer, follow-up check, or verification — so the single tool-capable
+     * turn either answers the question or carries the task out. No tool is
+     * forbidden: the model looks facts up itself when they are not its own.
+     */
+    buildExtraPrompt(query: string): string;
+    /**
+     * One tool-capable turn for an action route (`organize`, `extra`): the model
+     * carries the request out with the tools it has and reports through its plain
+     * final message. No retrieval, no fast answer, no verification — and no route
+     * changes the session's active tools, so the turn prompt is what scopes the
+     * work. Returns the report, or `undefined` when the user stopped the run or
+     * the turn ended without one.
      */
-    buildDirectAnswerPrompt(query: string): string;
+    private runActionTurn;
     /** Discovery-tool hint naming only the registered discovery tools; empty when none. */
     private discoveryHint;
     /**
-     * Verification-phase nudge toward the internet. Jev no longer routes to web
-     * search, so the agent decides after the fast answer: when local evidence is
-     * missing, thin, or possibly stale, it searches the web. Empty when web tools are off.
+     * Verification-phase nudge toward the internet, for when the web was not
+     * selected before the fast answer or its evidence fell short: when local
+     * evidence is missing, thin, or possibly stale, the agent searches the web. Empty when web tools are off.
      */
     private webFallbackHint;
     /**

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

@@ -31,13 +31,30 @@ export declare const ANSWER_EMPHASIS_RULE = "**Emphasis**: put the values a read
 export declare const ANSWER_LANGUAGE_RULE = "**Answer language**: write the answer in the language of the user's question (a Korean question gets a Korean answer) even when the sources are in another language; if the user asks for a specific language, use that one. Keep proper nouns, identifiers, code, and terms quoted from sources in their original form.";
 /** Uncertainty goes last so it never buries the conclusion. */
 export declare const ANSWER_UNCERTAINTY_RULE = "**Uncertainty placement**: when the answer is incomplete or uncertain, state that in one short sentence on the last line of the answer, never before or ahead of the conclusion. Do not hedge the conclusion itself.";
+/**
+ * Every sentence answers the question. Models that find nothing on point tend to
+ * prove the search was thorough by listing what they found instead and why it
+ * does not match; the caller never asked for that, so it is left out for every
+ * phase, delta included.
+ */
+export declare const ANSWER_RELEVANCE_RULE = "**Answer only what was asked**: every sentence must answer the user's question. Never list retrieved items, topics, documents, or figures that do not answer it, never describe how or where you searched, and never explain why something was left out or how it differs from what was asked (no \"I also found X, but it is not what you asked\", no near-miss lists, no \"nothing about Y, only Z\", no inventory of the sources that lacked it). Unrelated or merely adjacent material is omitted entirely unless the user asked for related items or alternatives.";
+/**
+ * Fast phase, no supporting evidence: park the question in one line. The
+ * verification phase that follows keeps searching, so the line is true.
+ */
+export declare const ANSWER_UNCONFIRMED_FAST_RULE = "**When the evidence does not answer the question yet**: do not build an answer out of what was found instead, and do not argue that the answer is absent by naming what the sources did contain (no \"only X exists\" contrast). The whole answer is then one short line saying it is not confirmed yet and that you are searching further (the verification phase that follows does the searching), with no bullets and no citations. A different subject, place, year, or party is unrelated evidence, not part of the answer. If a part the user actually asked for is answered, answer that part normally and say on the last line what is still being searched.";
+/**
+ * Phases that can end the run: search before giving up, and when the search
+ * still finds nothing the answer is one line, not an inventory of the corpus.
+ */
+export declare const ANSWER_UNCONFIRMED_FINAL_RULE = "**When the answer cannot be found**: keep searching first (different terms, synonyms, other retrieval methods or datasources) instead of answering from unrelated results. If it still cannot be confirmed, the whole answer is one short line saying so, with no bullets, no citations, no mention of what was found instead (no \"only X exists\" contrast), and no account of where you looked or what the documents do contain. A different subject, place, year, or party is unrelated evidence, not part of the answer. If a part the user actually asked for is answered, answer that part normally and say on the last line what is still unconfirmed.";
 /**
  * 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.";
+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. A retrieved result may carry a measured location note such as `(lines 7-8, section \"\uC81C5\uC870(\uD68C\uC6D0\uC758 \uC758\uBB34)\")` next to its id: when you state a line number, line range, or article/section of a passage, copy it from that note, and when no note is printed give none. Never count or infer line numbers yourself, and never state how many items (paragraphs, articles, results) there are unless you counted them in the quoted text.";
 /**
  * Deliverable/artifact rule (issue #1832). The 5-bullet cap and direct-answer
  * format remain the default unless the user explicitly asks otherwise; when the

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;