@autorag/librarian 2.11.0 → 2.13.0

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

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

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

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

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

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

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

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

package/dist/agent/current-date.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The prompt block that tells the model what "now" is. AutoRAG replaces pi's whole
+ * system prompt, so nothing else gives the model a clock; without it "last month",
+ * "this year", "is the deadline past", and "the most recent" have no anchor.
+ *
+ * Built per turn from the host's local clock and time zone, so a session left open
+ * for days never shows yesterday's date. It sits last in the prompt so the stable
+ * part before it keeps its prompt-cache prefix.
+ */
+export declare function currentDateAddendum(now?: Date): string;

package/dist/agent/datasource-skill.d.ts

@@ -36,8 +36,8 @@ export declare function toDatasourceAgentSkill(manifest: DatasourceSkillManifest
  */
 export declare function buildDatasourceSkillsPrompt(skills: readonly DatasourceAgentSkill[]): string;
 /**
- * Format the full instructions for a loaded datasource skill, matching pi's
- * `<skill …>` invocation shape but with a path-opaque location (no real
+ * Format the full instructions for a loaded datasource skill in the shared
+ * `<skill …>` invocation shape, with a path-opaque location (no real
  * filesystem reference, so no "references are relative to …" line).
  */
 export declare function formatDatasourceSkillInvocation(skill: DatasourceAgentSkill): string;

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

@@ -0,0 +1,20 @@
+export interface EnvironmentInfo {
+    readonly cwd: string;
+    readonly platform: string;
+    readonly arch: string;
+    readonly release: string;
+    /** The shell the `bash` tool runs commands in; undefined when pi found none. */
+    readonly shell: string | undefined;
+}
+/**
+ * Where the agent runs: OS, shell, and working directory. AutoRAG replaces pi's whole
+ * system prompt, so without this the model writes POSIX commands for a Windows host
+ * and relative paths against an unknown directory. Fixed for the life of a session.
+ */
+export declare function environmentAddendum(info: EnvironmentInfo): string;
+/**
+ * Everything the host appends after AutoRAG's own prompt. Ordered most stable first:
+ * the environment never changes in a session, the date changes every minute, so the
+ * longest possible prefix of the prompt stays identical between turns for prompt caching.
+ */
+export declare function runtimeContextAddendum(cwd: string, now?: Date): string;

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

@@ -8,11 +8,12 @@ export interface LedgerEvidenceInput {
     readonly retrievalResultId?: string;
     readonly chunkIndex?: number;
     readonly lineNumber?: number;
+    readonly lineEnd?: number;
+    readonly section?: string;
     readonly parserType?: string;
     readonly documentType?: string;
     readonly documentArea?: string;
     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";
@@ -27,11 +28,12 @@ declare const ledgerEntrySchema: Type.TObject<{
     retrievalResultId: Type.TOptional<Type.TString>;
     chunkIndex: Type.TOptional<Type.TNumber>;
     lineNumber: Type.TOptional<Type.TNumber>;
+    lineEnd: Type.TOptional<Type.TNumber>;
+    section: Type.TOptional<Type.TString>;
     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>;

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

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

package/dist/agent/index.d.ts

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

package/dist/agent/intent-tracing.d.ts

@@ -0,0 +1,33 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+/**
+ * Intent tracing: every tool the model can call also takes a short `i` argument, one line saying
+ * what that call is for. The text is shown while the model works (pi's `Working` loader in the TUI,
+ * `progress` events of `searchDocumentsStream` for the CLI and the desktop app), so a long search
+ * says what it is doing without the model writing separate progress notes.
+ *
+ * Pi has no such feature; this mirrors oh-my-pi's. The field exists only on the wire: it is added to
+ * the tool declarations of each model request and removed again before the tool validates and runs,
+ * so no tool ever sees it.
+ */
+export declare const INTENT_FIELD = "i";
+/** The text to show for a model-written intent, or `undefined` when it is not a usable label. */
+export declare function normalizeIntent(value: unknown): string | undefined;
+/** The intent of the last tool call in an assistant message that carries one, or `undefined`. */
+export declare function intentOfMessage(message: {
+    readonly role?: string;
+    readonly content?: unknown;
+}): string | undefined;
+/** Whether the tool schema already has its own `i` parameter, which then belongs to the tool. */
+export declare function schemaDefinesIntent(schema: unknown): boolean;
+/**
+ * The wire schema of a tool with the required `i` field first. A schema that is not an object, that
+ * already defines `i`, or that rejects unknown properties comes back unchanged: the tool would
+ * refuse the field once the model filled it in.
+ */
+export declare function withIntentField(schema: unknown): unknown;
+/**
+ * Wires intent tracing into a pi session: declares `i` on every tool, takes it off the arguments
+ * before the tool runs, and, when the session has a terminal UI, shows the newest intent as the
+ * working message. Register it in every session whose model calls AutoRAG's tools.
+ */
+export declare function registerIntentTracing(pi: ExtensionAPI): void;

package/dist/agent/location-claims.d.ts

@@ -0,0 +1,14 @@
+/** A line range a cited chunk occupies in its parsed document. */
+export interface CitedLineRange {
+    readonly lineStart?: number;
+    readonly lineEnd?: number;
+}
+/**
+ * Line numbers `prose` states that no cited chunk covers, each once, in order of
+ * appearance. The line range of a chunk is measured from the parsed document,
+ * so a number outside every cited range is one the model made up or miscounted.
+ *
+ * Nothing can be checked when no cited chunk carries a line range, so that
+ * yields no claims rather than flagging every number.
+ */
+export declare function findUnverifiedLineClaims(prose: string, cited: readonly CitedLineRange[]): number[];

package/dist/agent/packaged-skill.d.ts

@@ -0,0 +1,19 @@
+import type { SkillInvocation } from "./skill-invocation.js";
+/** The packaged `autorag-setup` skill, loaded for the Jev `config` branch. */
+export declare const SETUP_SKILL_NAME = "autorag-setup";
+/** The packaged `organize` skill, loaded for the Jev `organize` branch. */
+export declare const ORGANIZE_SKILL_NAME = "organize";
+/** A packaged skill as a turn prompt needs it: name, opaque location, body. */
+export type PackagedAgentSkill = SkillInvocation;
+/**
+ * Opaque, path-free location used for a packaged agent skill. Packaged skills
+ * live on disk, but AutoRAG never exposes real filesystem paths to the model.
+ */
+export declare function packagedSkillLocation(name: string): string;
+/**
+ * Load one packaged agent skill: the file at `path` when given (the host's
+ * override), otherwise the packaged skill named `name`. The body is returned
+ * with its YAML front matter removed, so the model sees only instructions.
+ * Throws when the skill cannot be found or read; callers fall back to `local`.
+ */
+export declare function loadPackagedSkill(name: string, path?: string): PackagedAgentSkill;

package/dist/agent/permission-gate.d.ts

@@ -0,0 +1,78 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { JevJudge } from "./jev-extension.js";
+import { type PermissionKind } from "./permission-judgment.js";
+import { type UserRequestLog } from "./user-requests.js";
+export { AUTO_APPROVE_MIN_CONFIDENCE, DEFAULT_MAX_STATE_CHARS, PERMISSION_GATE_QUESTION_ID, } from "./permission-judgment.js";
+/**
+ * How much the agent may do to the user's files without asking.
+ *
+ * - `full`: no gate; the agent does everything on its own, and Jev is never asked.
+ * - `ask`: every `bash`, `write`, `edit`, and saved automation is put to the user. Jev is not used.
+ * - `auto` (default): Jev classifies each of those calls first. One it finds safe runs; one it flags is approved
+ *   by Jev when the user's request clearly covers it, and only what Jev will not approve confidently reaches
+ *   the user.
+ */
+export type PermissionMode = "full" | "ask" | "auto";
+/** Order Shift+Tab cycles through. */
+export declare const PERMISSION_MODES: readonly PermissionMode[];
+/** Mode a fresh interactive or CLI session starts in. */
+export declare const DEFAULT_PERMISSION_MODE: PermissionMode;
+export declare function parsePermissionMode(value: unknown): PermissionMode | undefined;
+export declare function cyclePermissionMode(mode: PermissionMode): PermissionMode;
+type ModeListener = (mode: PermissionMode) => void;
+/** What a session grant covers: one category of change, every call Jev could not classify, or (`ask`) every call. */
+export type GrantKey = PermissionKind | "unclassified" | "all";
+/**
+ * Session-wide permission state: the mode, and what the user allowed for the rest of the session. One
+ * controller is shared by every pi session of an agent.
+ */
+export declare class PermissionController {
+    private current;
+    private readonly listeners;
+    private readonly granted;
+    private readonly created;
+    constructor(mode?: PermissionMode);
+    get mode(): PermissionMode;
+    /** Switches mode. Session grants end with the mode they were given in. */
+    set(mode: PermissionMode): void;
+    cycle(): PermissionMode;
+    subscribe(listener: ModeListener): () => void;
+    isGranted(key: GrantKey): boolean;
+    grant(keys: readonly GrantKey[]): void;
+    /** Records paths a successful call brought into existence: the agent's own files, not the user's originals. */
+    markCreated(paths: readonly string[]): void;
+    /** Whether the agent created this path, or a folder it lies in, earlier in this session. */
+    isCreated(path: string): boolean;
+}
+export interface PermissionGateOptions {
+    readonly controller: PermissionController;
+    /**
+     * Jev, which classifies every gated call. Without one the gate cannot classify, so in `ask` and `auto` it
+     * asks the user about every `bash`, `write`, and `edit` call.
+     */
+    readonly judge?: JevJudge;
+    /**
+     * What the user has said in this conversation: the first question, every follow-up, every steer. Jev judges
+     * the call against all of it. The host feeds it from the user's own input, so AutoRAG's internal phase
+     * prompts are never in it.
+     */
+    readonly requests?: UserRequestLog;
+    /** Cap on the state shown to Jev, in characters. Default: Jev's context ceiling with a safety margin. */
+    readonly maxStateChars?: number;
+    /** Files the agent may always write and edit without Jev being asked (the config its self-configuration turn edits). */
+    readonly trustedPaths?: readonly string[];
+}
+/** Appended to the system prompt while a gate is active, so the model stays on the happy path. */
+export declare const PERMISSION_PROMPT_ADDENDUM: string;
+/** `ask` addendum: the user sees every call, so the model should batch work and still not refuse requests. */
+export declare const ASK_PROMPT_ADDENDUM: string;
+/**
+ * pi extension that gates what the agent does to existing files.
+ *
+ * Every `bash`, `write`, `edit`, and `manage_automations save` call is gated (reads, searches, and other tools
+ * never touch originals and are not asked about). In `ask` each one is put to the user. In `auto` Jev
+ * classifies it first: a call it finds safe runs, one it flags is approved by Jev when the user's request
+ * clearly covers it, and otherwise put to the user. Shift+Tab and `/permissions` switch the mode; the footer
+ * shows it.
+ */
+export declare function createPermissionGate(options: PermissionGateOptions): ExtensionFactory;

package/dist/agent/permission-judgment.d.ts

@@ -0,0 +1,72 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { JevJudge } from "./jev-extension.js";
+import { type ProposedCall } from "./permission-paths.js";
+import { type UserRequest } from "./user-requests.js";
+/**
+ * What a tool call does to the user's existing files, as Jev judges it. A call can be several at once
+ * (`mkdir x && mv a x/ && rm b` is a move and a delete).
+ *
+ * `unclear` is for code whose effect cannot be told from what is shown: an unseen script file, `make clean`,
+ * an encoded command. It is asked about like any other category.
+ */
+export declare const PERMISSION_KINDS: readonly ["delete", "move", "rename", "overwrite", "edit", "unclear"];
+export type PermissionKind = (typeof PERMISSION_KINDS)[number];
+export declare function permissionKindQuestionId(kind: PermissionKind): string;
+/** Jev question id of the "may this run without asking?" check that `auto` mode adds to the same batch. */
+export declare const PERMISSION_GATE_QUESTION_ID = "permission_gate";
+/** Jev must be at least this sure before `auto` skips the user. Stricter than jev-use's own 0.5 default. */
+export declare const AUTO_APPROVE_MIN_CONFIDENCE = 0.8;
+/**
+ * Largest state the gate shows Jev, in characters. jev-use hands every question back ("oversized") once the
+ * state passes {@link DEFAULT_MAX_STATE_TOKENS} estimated tokens (about 4 characters each), and then the gate
+ * could not classify anything. The ceiling is read from jev-use so it cannot drift, and 10% is left for
+ * jev-use's own estimate being rough.
+ */
+export declare const DEFAULT_MAX_STATE_CHARS: number;
+/** The tool calls the gate classifies. Everything else (reads, searches, MCP tools) never touches originals. */
+export declare function isGatedCall(toolName: string, input: Readonly<Record<string, unknown>>): boolean;
+/** One line (or the command) naming what a call does, for the approval dialog and the notice. */
+export declare function summarizeCall(call: ProposedCall): string;
+/** The earlier calls of this session that ran and succeeded, oldest first. */
+export declare function successfulCalls(branch: readonly SessionEntry[]): ProposedCall[];
+export interface JudgedState {
+    readonly call: ProposedCall;
+    readonly requests: readonly UserRequest[];
+    readonly history: readonly ProposedCall[];
+    readonly maxStateChars: number;
+    /** Whether the agent itself brought this path into existence earlier in the session. */
+    readonly isCreated?: (path: string) => boolean;
+}
+/**
+ * The state Jev judges, within `maxStateChars`: how to judge, what the user said, what the agent already did,
+ * and the call itself. The call and the history are cut first (the call to 40% of the budget, the history to
+ * 20%, each keeping the start and end), and the conversation gets whatever is left, so the whole stays under
+ * the ceiling however long any one part is.
+ */
+export declare function buildJudgedState({ call, requests, history, maxStateChars, isCreated }: JudgedState): string;
+export interface FlaggedKind {
+    readonly kind: PermissionKind;
+    /** Jev's probability that the call is in this category; undefined when Jev was unsure and gave none. */
+    readonly probability: number | undefined;
+}
+export interface Approval {
+    readonly approved: boolean;
+    /** Why not, when it was not approved. */
+    readonly why: string;
+}
+/** Jev's reading of one call, or the reason it could not give one. */
+export type Classification = {
+    readonly status: "classified";
+    readonly flagged: readonly FlaggedKind[];
+    readonly approval: Approval;
+} | {
+    readonly status: "failed";
+    readonly why: string;
+};
+export type ClassifyOptions = JudgedState;
+/**
+ * Asks Jev what `options.call` does to existing files, in one batched request. Never throws: no answer
+ * (unreachable, timed out, oversized, a missing verdict) is a `failed` classification, and the gate then
+ * asks the user instead of letting the call through.
+ */
+export declare function classifyCall(judge: JevJudge, options: ClassifyOptions): Promise<Classification>;

package/dist/agent/permission-paths.d.ts

@@ -0,0 +1,23 @@
+/** A tool call the gate is about to judge. */
+export interface ProposedCall {
+    readonly tool: string;
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly cwd: string;
+}
+/** `raw` as an absolute path: relative to `cwd`, with `~` expanded. */
+export declare function resolveToolPath(raw: string, cwd: string): string;
+export interface NamedPath {
+    readonly path: string;
+    /**
+     * True when the word is certainly a path (absolute, `~/`, `./`, `../`, a file name with an extension) or
+     * names something that exists. A plain word that exists nowhere (`fresh` in `mkdir fresh`) is only a
+     * candidate: the gate watches whether the call brings it into existence, and shows it to Jev only then.
+     */
+    readonly always: boolean;
+}
+/**
+ * The paths a call names, for the facts Jev is shown (does each exist, did the agent make it). This does not
+ * decide anything and does not understand the command: it picks out the words that look like paths. A word it
+ * misses is a fact Jev lacks; a word it wrongly takes is a harmless "does not exist" line.
+ */
+export declare function pathsNamedBy(call: ProposedCall): NamedPath[];