@autorag/librarian 2.10.0 → 2.10.2

package/dist/agent/agent.d.ts

@@ -1,14 +1,15 @@
 import type { Agent, AgentTool } from "@earendil-works/pi-agent-core";
-import type { Api, Model } from "@earendil-works/pi-ai";
+import type { Api, ImageContent, Model } from "@earendil-works/pi-ai";
+import { type DatasourceRetryOptions } from "../datasource/retry.js";
 import type { DatasourceIndexResult, DatasourceSkill } from "../datasource/types.js";
 import { type DupeyCliOptions } from "../dupey/index.js";
 import { type Embedder } from "../embedding-runtime/gateway-embedder.js";
 import { type EverythingClientOptions, type EverythingSearchRequest, type EverythingSearchResult } from "../everything/index.js";
 import { type FSearchClientOptions, type FSearchFailureReason, type FSearchSearchRequest, type FSearchSearchResult } from "../fsearch/index.js";
-import { type JikjiFailureReason, type JikjiOptions } from "../jikji/index.js";
+import { type JikjiFailureReason, type JikjiOptions, type JikjiPrepareOptions } from "../jikji/index.js";
 import { type LanguageTag } from "../language.js";
 import { type MinSyncSyncResult, type MinSyncVectorMethodOptions } from "../minsync/index.js";
-import { type ParsedMirrorSyncResult } from "../mirror/sync.js";
+import { type ParsedMirrorSyncOptions, type ParsedMirrorSyncResult } from "../mirror/sync.js";
 import type { PolicyResolver } from "../p2p/policy-filter.js";
 import type { SimplexQueryState } from "../p2p/simplex-query-store.js";
 import { type SimplexTransport } from "../p2p/simplex-transport.js";
@@ -26,9 +27,28 @@ import { type AutoRAGPiInteractiveRuntime, type AutoRAGPiSession } from "./pi-se
 import { type RefreshProgressCounts, type RefreshProgressPhase } from "./refresh-progress.js";
 import { type SearchDocumentDiagnostic, type SearchDocumentsResponse, type SearchDocumentsStreamEvent } from "./search-documents.js";
 import { type SelfConfigOptions } from "./self-config.js";
+import { type ToolBurstGuardOptions } from "./tool-burst-guard.js";
 import { type WatcherFactory, type WatchRefreshHandle } from "./watch-refresh.js";
 import { type WebFetchToolOptions } from "./web-fetch-tool.js";
 import { type WebSearchToolOptions } from "./web-search-tool.js";
+/**
+ * Safety limits for the parsed-mirror refresh. Every field is optional; an
+ * omitted field keeps the shipped default.
+ */
+export interface AutoRAGRefreshLimits {
+    /**
+     * Largest share (0–1) of indexed documents one refresh may delete because
+     * their source disappeared; a bigger deletion above 100 documents is
+     * suppressed unless the refresh is forced. Default 0.3.
+     */
+    readonly maxDeleteRatio?: number;
+    /** Directory entries examined per search root before the walk stops. Default 2,000,000. */
+    readonly maxScannedEntries?: number;
+    /** Deepest directory level walked below a search root. Default 64. */
+    readonly maxDepth?: number;
+    /** Retries for a transient per-file I/O error (EMFILE/EBUSY/EIO/ETIMEDOUT) before the file is skipped. Default 3. */
+    readonly transientRetries?: number;
+}
 /**
  * Hard caps on retrieval, baseline prefetch, and the candidate lists handed to
  * the model. Every field is optional: an omitted field keeps the shipped
@@ -64,9 +84,40 @@ export interface AutoRefreshOptions {
 }
 /** Methods that `refresh` can selectively run. Defaults to all when omitted. */
 export type RefreshMethod = "parsed" | "minsync" | "datasources" | "jikji" | "everything" | "fsearch";
+/**
+ * Progress of a refresh phase that can count its work. `parsed` counts source files
+ * (`currentVirtualPath` is the opaque virtual path of the file about to be processed);
+ * `datasources` counts configured datasource skills. Other phases do not report counts.
+ */
+export interface AutoRAGRefreshProgress {
+    readonly phase: "parsed" | "datasources";
+    /** Items finished so far. Advances by one per item and ends equal to `total`. */
+    readonly processed: number;
+    readonly total: number;
+    readonly currentVirtualPath?: string;
+}
 export interface AutoRAGRefreshOptions {
     /** Restrict refresh to specific methods. Defaults to all when undefined. */
     readonly methods?: readonly RefreshMethod[];
+    /**
+     * Retry sources previously skipped as parser-failed or source-unreadable once, ignoring their
+     * skip records. Unlike `force`, healthy unchanged mirrors are not re-parsed.
+     */
+    readonly retrySkipped?: boolean;
+    /**
+     * Cancels the refresh. It is checked between files and between phases, and it kills an in-flight parse
+     * worker and the MinSync, Jikji and datasource child processes. `refresh` then rejects with the signal's
+     * reason and records the run as failed; mirror entries written before the abort are kept.
+     */
+    readonly signal?: AbortSignal;
+    /** Called while the parse and datasource phases run. A throwing callback is ignored; it never fails the refresh. */
+    readonly onProgress?: (progress: AutoRAGRefreshProgress) => void;
+    /**
+     * Per-root `jikji prepare` controls: a hard `timeoutMs` wall per root and a
+     * `parseTimeout` (seconds, forwarded to `--parse-timeout`). Unset values fall
+     * back to the `jikji` client options. Cancel through the refresh `signal`.
+     */
+    readonly jikjiPrepare?: Omit<JikjiPrepareOptions, "signal">;
 }
 export interface AutoRAGMinSyncRefreshResult {
     readonly ok: boolean;
@@ -185,7 +236,6 @@ export interface AutoRAGAgentOptions {
     providerApiKeys?: Readonly<Record<string, string>>;
     searchPaths: string[];
     languages?: readonly LanguageTag[];
-    manifestDir?: string;
     memoryPath?: string;
     workspacePath?: string;
     tools?: AgentTool[];
@@ -278,13 +328,23 @@ export interface AutoRAGAgentOptions {
      * {@link AutoRAGRetrievalLimits}. Values must be positive integers.
      */
     limits?: AutoRAGRetrievalLimits;
+    /** Parsed-mirror refresh limits and retry tuning. See {@link AutoRAGRefreshLimits}. */
+    refresh?: AutoRAGRefreshLimits;
     datasourceSkills?: readonly DatasourceSkill[];
+    /**
+     * Retry/backoff for datasource `index()` during refresh: 2 retries with
+     * jittered exponential backoff by default, applied only to failures the
+     * skill marks retryable. `maxRetries: 0` disables retrying.
+     */
+    datasourceRetry?: DatasourceRetryOptions;
     /** Non-fatal diagnostics from config/agent construction (e.g. skipped unknown datasources). */
     startupDiagnostics?: readonly SearchDocumentDiagnostic[];
-    /** Maximum time a model/tool search may run before it is aborted. */
-    searchTimeoutMs?: number;
-    /** Maximum number of retrieval/tool executions allowed in one search. */
-    maxSearchToolCalls?: number;
+    /**
+     * Runaway-loop guard: the run is aborted when one tool is called `maxCalls`
+     * times within `windowMs` (default 60 calls in 60 s). `false` disables it.
+     * There is no limit on a run's duration or its total number of tool calls.
+     */
+    toolCallBurstGuard?: ToolBurstGuardOptions | false;
     /**
      * Outbound SimpleX queries to trusted peer AutoRAG agents. Remote sessions
      * never receive this tool.
@@ -313,9 +373,9 @@ export interface RerankAgentOptions {
     provider?: string;
     /** Wire model id. @default "voyageai/rerank-3-lite" */
     model?: string;
-    /** API key. Prefer `apiKeyEnv`; this is a programmatic seam. */
+    /** API key. Prefer `apiKeyEnv`; this is a programmatic seam. Not used by the `dazzi` provider. */
     apiKey?: string;
-    /** Environment variable holding the provider API key. */
+    /** Environment variable holding the provider API key. Not used by the `dazzi` provider, which uses the `/login` credential. */
     apiKeyEnv?: string;
     /** Override the provider base URL. */
     baseUrl?: string;
@@ -356,9 +416,23 @@ export declare class AutoRAGAgent {
     private lastQuery;
     private lastSessionId;
     private activeRun;
+    /**
+     * Steering state of the running search. A TUI query runs detached from pi's
+     * input loop (pi reads the next input only after its input handler returns),
+     * so input typed meanwhile steers this run (Enter) or waits behind it
+     * (Alt+Enter), the way pi steers its own turns. {@link steer} feeds the same
+     * state for `searchDocuments()` / `searchDocumentsStream()` callers.
+     */
+    private readonly interactive;
+    /** Aborted by {@link abort} and by the run's timeout: gates publishing and the run's own requests. */
+    private activeRunAbort;
     private modelNativeSearchAuth;
     private retrievalTrace;
-    /** Evidence every retrieval tool returned this run; the answer's inline `[eN]` citations resolve against it. */
+    /**
+     * Evidence the retrieval tools returned; the answer's inline `[eN]` citations resolve against it. A bound
+     * interactive session keeps it for the whole conversation and persists it with the transcript; any other
+     * run starts from an empty ledger.
+     */
     private readonly evidenceLedger;
     private preliminaryCallback;
     /** Per-phase thinking levels of the two-phase search. */
@@ -368,6 +442,8 @@ export declare class AutoRAGAgent {
     private refreshing;
     private refreshState;
     private readonly searchPaths;
+    /** Roots handed to Jikji: duplicates and roots nested in another root are dropped (see `outermostJikjiRoots`). */
+    private readonly jikjiRoots;
     private readonly configuredSearchPaths;
     readonly languages: readonly LanguageTag[];
     private retrievalScopeBindings;
@@ -383,6 +459,7 @@ export declare class AutoRAGAgent {
     private readonly everythingClient;
     private readonly fsearchClient;
     private readonly datasourceSkills;
+    private readonly datasourceRetry;
     private readonly startupDiagnostics;
     private readonly datasourceAgentSkills;
     private readonly parserOptions;
@@ -402,8 +479,6 @@ export declare class AutoRAGAgent {
     private readonly excludePaths;
     private readonly baseSystemPromptConfig;
     private readonly droppedCallerToolNames;
-    private readonly searchTimeoutMs;
-    private readonly maxSearchToolCalls;
     private readonly piAgentDir;
     private readonly piSessionDir;
     private readonly persistPiSessions;
@@ -423,8 +498,9 @@ export declare class AutoRAGAgent {
     /** True when this agent was constructed for an untrusted remote peer. */
     readonly remoteSession: boolean;
     private activeRetrievalOptions;
-    private searchToolCallCount;
+    private readonly toolBurstGuard;
     private readonly limits;
+    private readonly refreshLimits;
     constructor(options: AutoRAGAgentOptions);
     scanDuplicateDocuments(): Promise<ScanDuplicateDocumentsDetails>;
     /**
@@ -470,8 +546,36 @@ export declare class AutoRAGAgent {
     private currentSystemPromptConfig;
     subscribe(listener: Parameters<Agent["subscribe"]>[0]): () => void;
     createPiInteractiveRuntime(): Promise<AutoRAGPiInteractiveRuntime>;
+    /**
+     * The session's custom tools, with retrieval and web reads interruptible by a
+     * steer: stopping them loses no side effect. bash and the file tools are pi
+     * built-ins and never pass through here.
+     */
+    private steerableTools;
+    /**
+     * Lets a steer cut a retrieval tool short, like an interruptible wait in pi:
+     * the tool's signal also aborts on the steer, and the call resolves at once
+     * with a skipped result telling the model to retry if the search still
+     * 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. */
     private deriveAnswer;
+    /**
+     * Routes one TUI input the way pi routes typed input for its own turns. With
+     * no search running it starts one. During a search, Enter steers it (the
+     * user is correcting a search that is going wrong) and Alt+Enter queues a
+     * follow-up question that runs once this search answers.
+     */
+    private routeInteractiveInput;
+    /**
+     * Esc and Alt+Enter during a search. pi handles both itself while a turn
+     * streams (abort, queue follow-up); between phases it ignores Esc and submits
+     * Alt+Enter like Enter, so AutoRAG acts on them there.
+     */
+    private handleInteractiveKey;
+    /** Runs one TUI query detached from pi's input loop, then any follow-ups queued behind it. */
+    private startInteractiveQuery;
     /**
      * Drives one TUI query through the two-phase search. The model's own
      * assistant messages (progress notes before a tool call, the fast answer,
@@ -480,7 +584,31 @@ export declare class AutoRAGAgent {
      * twice and put it in the model's context twice.
      */
     private runInteractivePiQuery;
+    /** Resolves once the TUI search and every follow-up queued behind it finished. */
+    waitForIdle(): Promise<void>;
+    /**
+     * Steers the running `searchDocuments()` / `searchDocumentsStream()` search,
+     * the way Enter steers a TUI search: `text` is a correction of the search in
+     * progress, not a new question. It reaches the search's next model request
+     * (also between phases, where no turn streams), cuts in-flight retrieval and
+     * the baseline prefetch short so it lands promptly, and forces the
+     * verification phase, whose prompt restates it. A steer that lands after
+     * verification's last request gets one more verification turn in the same
+     * search. The final answer stays the answer to the original question.
+     *
+     * Returns false, and does nothing, when no search is running, the search was
+     * stopped, or it is past its last model request; the caller should then ask
+     * the text as a new question.
+     */
+    steer(text: string, images?: readonly ImageContent[]): boolean;
+    /**
+     * Stops the running search as a whole: the streaming model turn, the
+     * baseline prefetch, in-flight retrieval, and every later phase. The search
+     * then resolves without a verified answer.
+     */
     abort(): void;
+    /** The next model request took the queued steers into the transcript; later retrieval runs uninterrupted until the next steer. */
+    private steersReachedModel;
     /**
      * Periodically re-runs the incremental {@link refresh} so parsed mirrors and
      * indexes stay current. Re-parsing is incremental (mtime/size) via the
@@ -584,6 +712,12 @@ export declare class AutoRAGAgent {
      * as plain text, without any further tool calls.
      */
     buildFastAnswerPrompt(query: string, options: RetrievalOptions, baseline: string): string;
+    /**
+     * True when the bound interactive session already holds an assistant turn:
+     * the query continues a conversation instead of opening one. Read from the
+     * transcript, so a fresh session (`/new`) starts over with the full pipeline.
+     */
+    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
@@ -604,7 +738,7 @@ export declare class AutoRAGAgent {
      * against it; the model then verifies with thinking on and ends with the
      * final answer as a plain reply, returning only the delta.
      */
-    buildRefinementPrompt(query: string, options: RetrievalOptions, fastAnswer: string | undefined, fastAnswerDelivered: boolean): string;
+    buildRefinementPrompt(query: string, options: RetrievalOptions, fastAnswer: string | undefined, fastAnswerDelivered: boolean, steers?: readonly string[]): string;
     buildSearchPrompt(query: string, options: RetrievalOptions, initialRetrievalContext?: string): string;
     refresh(force?: boolean, opts?: AutoRAGRefreshOptions): Promise<AutoRAGRefreshResult>;
     /**
@@ -633,7 +767,7 @@ export declare class AutoRAGAgent {
      */
     startWatchRefresh(options?: AutoRAGWatchRefreshOptions): AutoRAGWatchRefreshHandle;
     private defaultWatcherFactory;
-    syncParsedMirrors(force?: boolean): Promise<ParsedMirrorSyncResult>;
+    syncParsedMirrors(force?: boolean, options?: Pick<ParsedMirrorSyncOptions, "signal" | "onProgress" | "retrySkipped">): Promise<ParsedMirrorSyncResult>;
     /**
      * Lightweight stat-only staleness scan used when `refresh` is called with
      * methods that exclude parsed mirrors (e.g. only `datasources` or `jikji`).
@@ -642,7 +776,7 @@ export declare class AutoRAGAgent {
      */
     private scanMirrorStaleness;
     private exactDuplicateExclusions;
-    syncMinSync(force?: boolean): Promise<MinSyncSyncResult>;
+    syncMinSync(force?: boolean, signal?: AbortSignal): Promise<MinSyncSyncResult>;
     /** Provider for the Windows-only everything_search tool. */
     searchEverything(request: EverythingSearchRequest): Promise<EverythingSearchResult>;
     /**
@@ -660,12 +794,18 @@ export declare class AutoRAGAgent {
      * macOS/Linux.
      */
     stopFsearch(): Promise<void>;
-    prepareJikji(): Promise<readonly AutoRAGJikjiPrepareResult[] | undefined>;
+    prepareJikji(options?: JikjiPrepareOptions): Promise<readonly AutoRAGJikjiPrepareResult[] | undefined>;
     /**
      * Build or incrementally update every root's Jikji index. Called only by
      * refresh/watch (and the explicit `prepareJikji()` API), never by a query:
-     * `jikji prepare` reuses unchanged documents, and roots run in parallel so
-     * one slow root does not serialize the rest.
+     * `jikji prepare` reuses unchanged documents. Roots are submitted together
+     * but `JikjiClient` runs them one at a time, because every root shares one
+     * central SQLite file that fails with "database is locked" under concurrent
+     * writers. Nested and duplicate roots are skipped: upstream rejects
+     * overlapping roots and the outer root's index already covers them. A failed
+     * or timed-out root is a degraded result (reported as a diagnostic), never a
+     * rejection, so the refresh still finishes. `jikji.parseTimeout` /
+     * `jikji.timeoutMs` / `jikji.prepareTimeoutMsPerFile` apply to every root.
      */
     private executeJikjiPrepare;
     private sanitizeJikjiPrepareResult;
@@ -679,6 +819,7 @@ export declare class AutoRAGAgent {
     findJikji(query: string, opts?: {
         readonly topK?: number;
         readonly first?: boolean;
+        readonly signal?: AbortSignal;
     }): Promise<JikjiFindProviderResult>;
     /**
      * Merge per-root answer packs into one. Concatenates answer_paths/candidates
@@ -723,6 +864,7 @@ export declare class AutoRAGAgent {
     searchAllDocuments(query: string, options?: {
         readonly topK?: number;
         readonly scope?: string;
+        readonly signal?: AbortSignal;
     }): Promise<{
         results: RetrievalResult[];
         diagnostics: RetrievalDiagnostic[];
@@ -740,6 +882,7 @@ export declare class AutoRAGAgent {
     searchSingleDatasourceDocuments(datasourceId: string, query: string, options?: {
         readonly topK?: number;
         readonly scope?: string;
+        readonly signal?: AbortSignal;
     }): Promise<{
         results: RetrievalResult[];
         diagnostics: RetrievalDiagnostic[];

package/dist/agent/context-token-guard.d.ts

@@ -0,0 +1,23 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { Model } from "@earendil-works/pi-ai";
+type ContextTokenGuardModel = Model<any> | (() => Model<any> | undefined) | undefined;
+/**
+ * Compose an optional context transform with the aggregate token guard. The
+ * guard runs on the final transcript immediately before each provider request,
+ * so it sees the system prompt, tool declarations, user query, memory context,
+ * and every prior tool result.
+ */
+export declare function createContextTokenGuardedTransform(model: ContextTokenGuardModel, base?: (messages: AgentMessage[]) => Promise<AgentMessage[]>, fixedOverheadTokens?: () => number): (messages: AgentMessage[]) => Promise<AgentMessage[]>;
+/**
+ * Keep complete retrieval candidates while the assembled request fits the
+ * model budget. Removing a per-chunk cut is only safe because this drops whole
+ * lower-ranked candidates (with an explicit marker) instead of hiding text.
+ */
+export declare function guardAgentContextMessages(model: Model<any> | undefined, messages: AgentMessage[], useReportedUsage?: boolean, fixedOverheadTokens?: number): AgentMessage[];
+/**
+ * Estimate the current transcript with pi-coding-agent's conservative chars/4
+ * counter. `useReportedUsage` adds the last assistant turn's provider-reported
+ * usage for the settled prefix; pass false when the messages were just edited.
+ */
+export declare function estimateContextMessageTokens(messages: readonly AgentMessage[], useReportedUsage?: boolean): number;
+export {};

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

@@ -1,3 +1,4 @@
+import { type Static, Type } from "typebox";
 import type { RetrievalResult } from "../retrieval/types.js";
 import type { AutoRAGEvidenceRef } from "./results.js";
 export interface LedgerEvidenceInput {
@@ -13,28 +14,65 @@ export interface LedgerEvidenceInput {
     readonly evidenceType?: string;
     readonly evidenceLocation?: string;
 }
+/** Custom session entry type under which a conversation persists its evidence ledger. */
+export declare const EVIDENCE_ENTRY_TYPE = "autorag.evidence";
+declare const ledgerEntrySchema: Type.TObject<{
+    id: Type.TString;
+    /** Source plus a digest of the full chunk: the same chunk retrieved again keeps its id. */
+    key: Type.TString;
+    method: Type.TString;
+    source: Type.TString;
+    content: Type.TString;
+    retrieverMix: Type.TArray<Type.TString>;
+    retrievalResultId: Type.TOptional<Type.TString>;
+    chunkIndex: Type.TOptional<Type.TNumber>;
+    lineNumber: Type.TOptional<Type.TNumber>;
+    parserType: Type.TOptional<Type.TString>;
+    documentType: Type.TOptional<Type.TString>;
+    documentArea: Type.TOptional<Type.TString>;
+    evidenceType: Type.TOptional<Type.TString>;
+    evidenceLocation: Type.TOptional<Type.TString>;
+}>;
+/** One recorded piece of evidence: what a retrieval tool returned, under the id it printed. */
+export type LedgerEntry = Static<typeof ledgerEntrySchema>;
+/**
+ * Entries a session persisted under {@link EVIDENCE_ENTRY_TYPE}. A malformed
+ * entry is skipped: its id then resolves to nothing and the citation is
+ * dropped with a diagnostic, never mis-resolved.
+ */
+export declare function parseLedgerEntries(data: unknown): LedgerEntry[];
+/** Highest evidence id ordinal among `entries` (`e12` is 12); 0 when there are none. */
+export declare function highestOrdinal(entries: readonly LedgerEntry[]): number;
 export interface LookupEvidenceOptions {
     /** False in remote sessions: only evidence a tool returned this run may be cited. */
     readonly allowLocalFiles: boolean;
 }
 export declare function isRegularFile(path: string): boolean;
 /**
- * Per-run record of every piece of evidence a retrieval tool returned.
+ * Record of every piece of evidence the retrieval tools returned in one
+ * conversation.
  *
  * Tools hand the model a short id (`e1`, `e2`, ...) next to each result. The
  * model cites evidence by id; the harness resolves the id back to the exact
  * source, method, content, and chunk metadata it recorded. The model never
  * retypes a path or a chunk, so it cannot misquote or invent one, and the
  * stable evidence id stored in memory is always derived from real evidence.
+ *
+ * Ids count up for as long as the process lives and are never reissued, so an
+ * id the model saw in any earlier turn keeps naming the chunk it named. The
+ * hosting session persists what {@link takeUnsaved} returns and rebuilds the
+ * ledger with {@link restore} when a conversation is resumed.
  */
 export declare class EvidenceLedger {
     private entries;
     private readonly byKey;
     private readonly byId;
+    /** Entries recorded or changed since the last {@link takeUnsaved}. */
+    private readonly unsaved;
     /**
-     * Ordinal of the last issued id. Survives {@link clear}: a hosted (TUI)
-     * conversation keeps earlier runs' tool output in context, so restarting at
-     * e1 would let a stale id silently resolve to a different chunk.
+     * Ordinal of the last issued id. Survives {@link clear} and {@link restore}:
+     * a conversation keeps earlier turns' tool output in context, so restarting
+     * at e1 would let a stale id silently resolve to a different chunk.
      */
     private lastOrdinal;
     /** Record evidence and return its id. The same chunk always gets the same id. */
@@ -49,6 +87,17 @@ export declare class EvidenceLedger {
      * citation instead of failing the run.
      */
     lookup(raw: string, options: LookupEvidenceOptions): AutoRAGEvidenceRef[];
-    /** Forget every recorded entry. Ids are never reissued, so a previous run's id stays unresolvable. */
+    /** Forget every recorded entry. Ids are never reissued, so a previous conversation's id stays unresolvable. */
     clear(): void;
+    /** Entries recorded or changed since the last call, for the hosting session to persist. */
+    takeUnsaved(): LedgerEntry[];
+    /**
+     * Rebuild the ledger from persisted entries, such as the ones on the resumed
+     * conversation branch; a later entry with the same id replaces an earlier
+     * one. Ids keep counting past every restored id and past `ordinalFloor`, the
+     * highest id issued anywhere in the conversation (other branches included),
+     * so a restored ledger never reissues an id a transcript may still show.
+     */
+    restore(entries: readonly LedgerEntry[], ordinalFloor?: number): void;
 }
+export {};

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

@@ -0,0 +1,24 @@
+import type { ExtensionFactory, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { type EvidenceLedger } from "./evidence-ledger.js";
+/** The part of pi's session manager the ledger is rebuilt from. */
+interface SessionEntries {
+    getBranch(): SessionEntry[];
+    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.
+ */
+export declare function restoreEvidenceLedger(ledger: EvidenceLedger, 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
+ * calls, resumes, or restarts happened in between.
+ */
+export declare function createEvidencePersistence(ledger: EvidenceLedger): ExtensionFactory;
+export {};

package/dist/agent/jev-extension.d.ts

@@ -4,9 +4,10 @@ import { type JevBackend, type Judgment, type Question, type State } from "jev-u
 export declare const JEV_TOOL_NAME = "jev";
 /**
  * Jev backends the `jev-use` engine resolves from the environment, in
- * auto-select order: TypeSafe -> OpenRouter -> Vercel AI Gateway.
+ * auto-select order: TypeSafe -> OpenRouter -> Vercel AI Gateway. `dazzi` is
+ * the hosted Dazzi Models plan, built here rather than resolved by jev-use.
  */
-export type JevBackendName = "typesafe" | "openrouter" | "vercel";
+export type JevBackendName = "typesafe" | "openrouter" | "vercel" | "dazzi";
 /**
  * OpenRouter's live Jev model id. `jev-use` 0.8.0 ships `typesafe/jev-latest`,
  * which OpenRouter rejects with HTTP 400 ("Model ... does not exist"), so the
@@ -39,6 +40,8 @@ export interface JevToolOptions {
 export interface JevJudgeOptions extends JevToolOptions {
     /** Environment consulted for the backend credential. Default `process.env`. */
     readonly env?: Record<string, string | undefined>;
+    /** Pi agent home whose `auth.json` holds the Dazzi `/login` credential. Default: Pi's agent dir. */
+    readonly agentDir?: string;
 }
 /**
  * One batched Jev judgment. Rejects only when no backend can be built (for
@@ -51,8 +54,8 @@ export type JevJudge = (state: State, questions: Question[], options?: {
 /**
  * Builds the Jev judge shared by the `jev` tool and the query router. The
  * `jev-use` client is created lazily on the first call, so no credential
- * resolves at construction time, and the OpenRouter model pin applies to
- * every caller.
+ * resolves at construction time, and the per-backend model default (the
+ * OpenRouter pin, or `jev-1.13` on the hosted plan) applies to every caller.
  */
 export declare function createJevJudge(options?: JevJudgeOptions): JevJudge;
 /**

package/dist/agent/jikji-find-tool.d.ts

@@ -44,6 +44,7 @@ export interface JikjiFindProvider {
     findJikji(query: string, opts?: {
         readonly topK?: number;
         readonly first?: boolean;
+        readonly signal?: AbortSignal;
     }): Promise<JikjiFindProviderResult>;
 }
 export interface JikjiFindDetails {

package/dist/agent/pi-session.d.ts

@@ -1,5 +1,5 @@
 import type { AgentMessage, AgentTool } from "@earendil-works/pi-agent-core";
-import type { Api, Model } from "@earendil-works/pi-ai";
+import type { Api, ImageContent, Model } from "@earendil-works/pi-ai";
 import { type AgentSession, type AgentSessionRuntime, type ExtensionAPI, type ExtensionFactory, SettingsManager, type ToolDefinition, type TuiMode } from "@earendil-works/pi-coding-agent";
 export declare const PI_BUILTIN_TOOL_NAMES: readonly ["read", "bash", "edit", "write", "grep", "find", "ls"];
 /**
@@ -34,10 +34,43 @@ export interface AutoRAGPiSessionOptions {
     readonly remoteSession?: boolean;
     readonly contextTransform?: (messages: AgentMessage[]) => Promise<AgentMessage[]>;
 }
+/**
+ * How AutoRAG takes one interactive input. `steer` while a pi turn streams
+ * returns the text pi should queue as steering (pi delivers it before the
+ * turn's next model request); every other outcome is fully handled by AutoRAG.
+ */
+export type AutoRAGInputDisposition = {
+    readonly kind: "handled";
+} | {
+    readonly kind: "steer";
+    readonly text: string;
+};
+export interface AutoRAGInteractiveInput {
+    readonly text: string;
+    readonly images: readonly ImageContent[] | undefined;
+    /** pi's delivery for input typed while a turn streams; undefined when no turn streams. */
+    readonly streamingBehavior: "steer" | "followUp" | undefined;
+}
+/** A TUI key AutoRAG acts on itself while a search runs, even when no pi turn streams. */
+export type AutoRAGInteractiveKey = "interrupt" | "followUp";
 export interface AutoRAGPiInteractiveRuntimeOptions extends Omit<AutoRAGPiSessionOptions, "model"> {
     readonly model?: Model<Api>;
     readonly inactiveToolNames?: readonly string[];
-    readonly onQuery: (query: string, pi: ExtensionAPI) => void | Promise<void>;
+    /**
+     * Routes one interactive input: a new query, a steer of the running search,
+     * or a follow-up queued behind it. Must not wait for a search to finish:
+     * pi's TUI reads the next input only after this returns.
+     */
+    readonly onInput: (input: AutoRAGInteractiveInput, pi: ExtensionAPI) => AutoRAGInputDisposition;
+    /** Whether a search is running: while it is, every interactive input belongs to it. */
+    readonly isSearchRunning?: () => boolean;
+    /**
+     * Called for pi's interrupt (Esc) and follow-up (Alt+Enter) keys while a
+     * search runs. pi acts on them only while a turn streams, but a search also
+     * spends time between turns (routing, prefetch, checks). Return true to
+     * consume the key; pi then never sees it.
+     */
+    readonly onKey?: (key: AutoRAGInteractiveKey) => boolean;
     /**
      * Optional best-effort provider for a startup update notice. Resolves to the
      * notice text, or `undefined` when there is nothing to announce. Called once

package/dist/agent/request-limits.d.ts

@@ -0,0 +1,20 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ModelInputLimits } from "@earendil-works/pi-ai";
+/** Stands in for an image dropped from a model request by {@link fitRequestLimits}. */
+export declare const IMAGE_OMITTED_NOTE = "[Image omitted from this request to stay within the model provider's request limits. Read the file again if you still need to see it.]";
+/**
+ * Fits a model request into the provider's declared `inputLimits`.
+ *
+ * pi keeps every image a tool returned in the transcript and resends all of
+ * them on each later turn, but it never enforces `maxRequestBytes` or
+ * `images.maxPerRequest`. A search that reads a handful of photos therefore
+ * grows past a provider's body limit and the request fails outright (the hosted
+ * AutoRAG API answers HTTP 413). Images are what grows the body, so the oldest
+ * ones are replaced with {@link IMAGE_OMITTED_NOTE} until the request fits; the
+ * newest images, which the model is looking at, go last. Text is never touched.
+ *
+ * The size is the serialized transcript, a close lower bound of the provider
+ * body, so `maxRequestBytes` should keep headroom below the hard limit.
+ * Returns undefined when the request already fits; never mutates `messages`.
+ */
+export declare function fitRequestLimits(messages: readonly AgentMessage[], limits: ModelInputLimits | undefined): AgentMessage[] | undefined;

package/dist/agent/search-all-tool.d.ts

@@ -18,6 +18,7 @@ export interface SearchAllDocumentsProvider {
     searchAllDocuments(query: string, options?: {
         readonly topK?: number;
         readonly scope?: string;
+        readonly signal?: AbortSignal;
     }): Promise<SearchAllDocumentsResult>;
 }
 export interface SearchAllDocumentsDetails {

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-sync-failed" | "embedder-unavailable" | "embedding-identity-mismatch" | "parser-skipped" | "parser-failed" | "source-vanished" | "source-unreadable" | "parser-warning" | "duplicate-excluded" | "unsupported-file" | "stale-index" | "deleted-mirror" | "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" | "search-timeout" | "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";
+export type SearchDocumentDiagnosticCode = "empty-query" | "no-verified-results" | "unknown-warning" | "caller-tool-dropped" | "minsync-staging-excluded" | "minsync-sync-failed" | "minsync-lock-held" | "embedder-unavailable" | "embedding-identity-mismatch" | "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";
 export interface SearchDocumentDiagnostic {
     readonly code: SearchDocumentDiagnosticCode;
     readonly severity: SearchDocumentDiagnosticSeverity;

package/dist/agent/search-single-datasource-tool.d.ts

@@ -39,6 +39,7 @@ export interface SingleDatasourceSearchProvider {
     searchSingleDatasourceDocuments(datasourceId: string, query: string, options?: {
         readonly topK?: number;
         readonly scope?: string;
+        readonly signal?: AbortSignal;
     }): Promise<{
         readonly results: readonly RetrievalResult[];
         readonly diagnostics: readonly RetrievalDiagnostic[];

package/dist/agent/system-prompt.d.ts

@@ -1,10 +1,8 @@
-import type { StoreManifest } from "../manifest/types.js";
 import type { DatasourceAgentSkill } from "./datasource-skill.js";
 export interface SystemPromptConfig {
     toolNames: string[];
     modelId?: string;
     memoryEntries?: readonly unknown[];
-    manifests: StoreManifest[];
     jikjiIndexingEnabled?: boolean;
     datasourceSkills?: readonly DatasourceAgentSkill[];
     retrievedContentGuard?: boolean;