@cerebriline/core 4.100.240

package/dist/extensions/tools/executors/bash.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Bash Executor
+ *
+ * Built-in implementation for running shell commands using Node.js spawn.
+ */
+import { type ProcessStartTokenProbeResult } from "../../../runtime/process-start-token";
+import type { ShellExecutor } from "../types";
+import { type ReadReceipts } from "./read-receipts";
+import type { RunCommandExecutionController } from "./run-command-execution-controller";
+export type ProcessStartTokenProbe = (pid: number) => ProcessStartTokenProbeResult | Promise<ProcessStartTokenProbeResult>;
+export interface DetachedCommandLogCleanupOptions {
+    tempDirectory?: string;
+    retentionMs?: number;
+    nowMs?: number;
+    processStartTokenProbe?: ProcessStartTokenProbe;
+    activeCommandPollIntervalMs?: number;
+}
+/**
+ * Reaps completed detached command logs outside the retention window,
+ * schedules retained logs for their remaining lifetime, and follows active
+ * command identities until they exit. Local runtime hosts call this at startup
+ * so cleanup survives host exits and restarts instead of depending only on the
+ * process that launched the command.
+ */
+export declare function cleanupStaleDetachedCommandLogs(options?: DetachedCommandLogCleanupOptions): Promise<number>;
+export declare class CommandExitError extends Error {
+    readonly exitCode: number;
+    readonly output: string;
+    constructor(exitCode: number, output: string);
+}
+export interface ShellExecutorOptions {
+    /**
+     * Shell to use for execution
+     * @default "/bin/bash" on Unix, "powershell" on Windows
+     */
+    shell?: string;
+    /**
+     * Timeout for command execution in milliseconds
+     * @default 30000 (30 seconds)
+     */
+    timeoutMs?: number;
+    /**
+     * Maximum output kept, in characters. Output beyond this is
+     * middle-truncated: the head and tail are preserved and the middle is
+     * elided, since build and test failures usually live at the end of the
+     * output.
+     * @default 48_000 — see MAX_COMMAND_OUTPUT_CHARS in output-limits.ts
+     */
+    maxOutputChars?: number;
+    /**
+     * @deprecated Misnamed — the limit was always enforced in characters,
+     * not bytes. Use {@link maxOutputChars}; this alias is honored when
+     * maxOutputChars is not set.
+     */
+    maxOutputBytes?: number;
+    /**
+     * Environment variables to add/override
+     */
+    env?: Record<string, string>;
+    /**
+     * Whether to combine stdout and stderr
+     * @default true
+     */
+    combineOutput?: boolean;
+    /**
+     * The session's read receipts, so a command's effect on files the model has
+     * read can be reported back — see {@link sweepTrackedFiles}.
+     *
+     * Omit it and the executor behaves exactly as it did: no sweep, no stat, no
+     * note. The shell does not need receipts to run a command; it needs them to
+     * say what the command did to what the model believes.
+     */
+    receipts?: ReadReceipts;
+    /**
+     * Optional host-scoped controller that can release an in-flight command
+     * from its tool call while continuing to drain output to a bounded log.
+     */
+    executionController?: RunCommandExecutionController;
+    /**
+     * Transform the resolved spawn just before it runs. A delegated agent uses
+     * this to root the command tree at its sandbox launcher, so the command and
+     * every process it spawns read and write the agent's overlay rather than the
+     * workspace. Absent for the lead, whose commands run directly.
+     */
+    wrapSpawn?: (spec: {
+        executable: string;
+        args: string[];
+        cwd: string;
+        env: Record<string, string>;
+    }) => {
+        executable: string;
+        args: string[];
+        cwd: string;
+        env: Record<string, string>;
+    };
+    /**
+     * How long a completed detached command log remains available before its
+     * temporary directory is removed.
+     *
+     * @default 24 hours
+     */
+    detachedLogRetentionMs?: number;
+    /** Process identity provider used to enable safe command detachment. */
+    processStartTokenProbe?: ProcessStartTokenProbe;
+}
+/**
+ * Create a shell executor using Node.js spawn
+ *
+ * @example
+ * ```typescript
+ * const shell = createShellExecutor({
+ *   timeoutMs: 60000, // 1 minute timeout
+ *   shell: "/bin/zsh",
+ * })
+ *
+ * const output = await shell("ls -la", "/path/to/project", context)
+ * ```
+ */
+export declare function createShellExecutor(options?: ShellExecutorOptions): ShellExecutor;

package/dist/extensions/tools/executors/document/assets.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Where the document readers' data files are: pdf.js's decoders and
+ * character maps, tesseract's worker and core, and the bundled English model.
+ *
+ * Each is looked for beside the bundle first, which is where the extension's
+ * and the CLI's builds copy them, and then in the npm package it ships in,
+ * which is the case for tests and for an embedder using core from
+ * `node_modules`.
+ */
+export declare function moduleDirectory(): string;
+/** pdf.js's CCITT, JBIG2 and JPEG 2000 decoders, and its colour management. */
+export declare function resolvePdfjsWasmDirectory(): string | undefined;
+/** pdf.js's character maps, which CJK text needs to decode. */
+export declare function resolvePdfjsCmapDirectory(): string | undefined;
+/**
+ * tesseract's worker, bundled on its own because it runs in a worker thread.
+ * Undefined means the package's own, which is right when core runs from
+ * `node_modules`.
+ */
+export declare function resolveTesseractWorker(): string | undefined;
+/** The English model that ships with the tool (tessdata best_int). */
+export declare function resolveBundledTessdata(): string | undefined;

package/dist/extensions/tools/executors/document/ebook.d.ts

@@ -0,0 +1,11 @@
+/**
+ * EPUB, MOBI, AZW3 (KF8) and FB2 through lingo-reader.
+ *
+ * lingo-reader returns each chapter as HTML and writes the book's resources
+ * into a directory it is given, pointing every `<img src>` at the file it
+ * wrote. The chapter HTML becomes markdown here, and each picture is taken
+ * from that directory into the image collector before lingo-reader's own
+ * `destroy()` deletes the directory.
+ */
+import type { DocumentFormat, DocumentReadResult, ReadOptions } from "./formats";
+export declare function readEbook(filePath: string, data: Uint8Array, format: Extract<DocumentFormat, "epub" | "mobi" | "azw3" | "fb2">, options: ReadOptions): Promise<DocumentReadResult>;

package/dist/extensions/tools/executors/document/formats.d.ts

@@ -0,0 +1,83 @@
+/**
+ * What a document is, and which reader takes it.
+ */
+import type { ImageCollector } from "./images";
+export type DocumentFormat = "pdf" | "docx" | "pptx" | "xlsx" | "odt" | "odp" | "ods" | "odg" | "rtf" | "csv" | "html" | "epub" | "mobi" | "azw3" | "fb2" | "doc" | "xls" | "ppt";
+/** The names a format is known by, and the reader it goes to. */
+export declare const FORMAT_LABELS: Record<DocumentFormat, string>;
+/** Every extension this tool reads, for the tool description and read_files. */
+export declare const DOCUMENT_EXTENSIONS: readonly string[];
+export type FormatVerdict = {
+    format: DocumentFormat;
+} | {
+    unsupported: string;
+};
+/**
+ * The format of a file, from its extension and checked against its bytes.
+ *
+ * The bytes decide when the two disagree. A `.doc` that is really an RTF or a
+ * DOCX is common (Word saves under whatever name it was opened as), and so is
+ * a `.mobi` that is a KF8 file.
+ */
+export declare function detectFormat(filePath: string, head: Uint8Array): FormatVerdict;
+/** A unit a range can select: pages, slides, sheets or chapters. */
+export type UnitName = "page" | "slide" | "sheet" | "chapter";
+export interface ReadOptions {
+    images: ImageCollector;
+    /** Whether pictures are wanted at all (`images: "none"` skips the work). */
+    wantImages: boolean;
+    password?: string;
+    /** Which units to read; undefined reads everything. */
+    selects?: (unit: number) => boolean;
+    /** A scratch directory inside the extraction directory, removed afterwards. */
+    scratchDir: string;
+    /**
+     * Reads the text of a scanned page from its pictures (OCR). Undefined when
+     * recognition is off; resolves undefined for a page it did not read.
+     */
+    recognize?: (page: number, images: readonly PageImage[]) => Promise<RecognizedText | undefined>;
+}
+/** A picture a scanned page is drawn from, as a PNG. */
+export interface PageImage {
+    png: Uint8Array;
+    width: number;
+    height: number;
+    /** Share of the page it covers, 0-1. */
+    coverage: number;
+}
+export interface RecognizedText {
+    text: string;
+    /** Who read it, for the page's note: `tesseract (eng, 91%)`, `the vision model`. */
+    by: string;
+}
+export interface DocumentReadResult {
+    markdown: string;
+    reader: string;
+    title?: string;
+    author?: string;
+    /** How many units the document has, and what they are called. */
+    units?: {
+        name: UnitName;
+        total: number;
+        read: number[];
+    };
+    /** Chapter titles for an ebook, in reading order. */
+    contents?: string[];
+    /** Pages whose text is an image of text, for OCR. */
+    scannedPages?: number[];
+    /** Scanned pages whose text was recognized here, by `ReadOptions.recognize`. */
+    recognizedPages?: number[];
+    /** Pages scanned with a hidden text layer already on them. */
+    ocrLayerPages?: number[];
+    /** Pages drawn as shapes: no text and no pictures to read. */
+    vectorPages?: number[];
+    notes?: string[];
+}
+/**
+ * What `read_files` says instead of returning a binary document as text.
+ *
+ * Decided by the bytes, so a PDF saved as `.txt` is caught and an RTF, CSV,
+ * HTML or FB2 file, which are text, is still read as text. Undefined for
+ * everything else.
+ */
+export declare function unreadableDocumentMessage(filePath: string, head: Uint8Array, documentReader: boolean): string | undefined;

package/dist/extensions/tools/executors/document/images.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Where a document's pictures go.
+ *
+ * Every reader hands its pictures here as bytes, whatever form it found them
+ * in (base64 in officeparser's tree and office_oxide's markdown, raw pixels
+ * from pdf.js, files lingo-reader wrote), so the naming, deduplication and the
+ * index are the same for every format.
+ */
+export interface ExtractedImage {
+    /** File name inside the images directory. */
+    file: string;
+    /** Path relative to the extraction directory, for markdown links. */
+    link: string;
+    mediaType: string;
+    bytes: number;
+    width?: number;
+    height?: number;
+    /** Where in the document it came from: `page 7`, `slide 3`, `chapter 2`. */
+    source?: string;
+    /** The document's own alt text or caption, when it carries one. */
+    alt?: string;
+    /** What the vision model saw in it, when descriptions were asked for. */
+    description?: string;
+    /**
+     * Set for a format no model can view (EMF, WMF, PICT, TIFF, BMP): the file is
+     * kept, but it is not a picture anyone downstream can look at as it is.
+     */
+    notViewable?: boolean;
+    sha1: string;
+}
+/** The formats a vision model is sent, which is what `inline` can attach. */
+export declare const VIEWABLE_MEDIA_TYPES: Set<string>;
+/**
+ * The media type of an image, from its first bytes.
+ *
+ * The containers are not trusted for this: officeparser labels by extension,
+ * office_oxide by record type, and an EMF inside a `.png`-named part is
+ * common enough in real decks.
+ */
+export declare function sniffImageType(data: Uint8Array): string | undefined;
+export interface AddImageInput {
+    data: Uint8Array;
+    /** A name to build the file name from, such as `p7` or the part's own name. */
+    stem: string;
+    mediaType?: string;
+    width?: number;
+    height?: number;
+    source?: string;
+    alt?: string;
+}
+/**
+ * Collects a document's images, named and deduplicated, for writing.
+ *
+ * Deduplicated by content: a logo on every slide of a deck is one file, and
+ * every place it appears links to that one file.
+ */
+export declare class ImageCollector {
+    private readonly linkDir;
+    private readonly byHash;
+    private readonly names;
+    private readonly pending;
+    constructor(linkDir?: string);
+    add(input: AddImageInput): ExtractedImage | undefined;
+    get images(): readonly ExtractedImage[];
+    /** Every image with its bytes, in the order they were found. */
+    entries(): readonly {
+        image: ExtractedImage;
+        data: Uint8Array;
+    }[];
+    private uniqueName;
+}
+/** Markdown for an image: its alt text when the document gave one. */
+export declare function imageMarkdown(image: ExtractedImage): string;

package/dist/extensions/tools/executors/document/legacy.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Word, Excel and PowerPoint 97-2003 through office_oxide.
+ *
+ * office_oxide renders markdown with each picture inline as
+ * `[image-base64:<data>]` at its place in the text; each becomes a file and a
+ * link. Its Word reader misses some pictures (measured: POI's PngPicture.doc,
+ * one PNG), so a Word file's streams are also scanned for complete PNG and
+ * JPEG images, and any not already found are listed after the text.
+ *
+ * Word only. Excel splits a record longer than 8,224 bytes with a 4-byte
+ * CONTINUE header, so a picture in a workbook stream is not contiguous there:
+ * a byte scan of POI's SimpleWithImages.xls "found" a JPEG 4 bytes longer than
+ * the real one, damaged from byte 8,108 on, beside the one office_oxide read
+ * correctly. PowerPoint keeps its pictures in one flat stream, which
+ * office_oxide reads whole.
+ */
+import type { DocumentReadResult, ReadOptions } from "./formats";
+/** Complete PNG and JPEG images inside a compound file's streams. */
+export declare function scanCompoundImages(data: Uint8Array): Promise<Uint8Array[]>;
+export declare function readLegacyOffice(data: Uint8Array, format: "doc" | "xls" | "ppt", options: ReadOptions): Promise<DocumentReadResult>;

package/dist/extensions/tools/executors/document/ocr.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Text recognition with tesseract (tesseract.js, WebAssembly, in a worker
+ * thread), and the language models it reads with.
+ *
+ * English ships with the tool (tessdata best_int, 3 MB). Every other language
+ * is installed on request into one folder under the data directory, from the
+ * same CDN tesseract.js itself defaults to, so a session never downloads
+ * anything the user did not ask for.
+ */
+/** How scanned pages are read. `vision` is the Vision tab's model. */
+export type OcrEngine = "tesseract" | "vision" | "off";
+/** The user's Document Reader settings, as the host hands them over. */
+export interface DocumentReaderSettings {
+    /** @default "tesseract" */
+    ocr?: OcrEngine;
+    /** tesseract language codes. @default ["eng"] */
+    ocrLanguages?: readonly string[];
+    /** Where installed languages live. @default <data dir>/tessdata */
+    ocrDataDir?: string;
+    /** Describe extracted pictures with the vision model. @default false */
+    describePictures?: boolean;
+}
+export declare const BUNDLED_OCR_LANGUAGE = "eng";
+export declare function resolveOcrDataDir(): string;
+/** Codes from a setting or a tool call: "eng+deu", "eng, deu", or a list. */
+export declare function parseOcrLanguages(input: string | readonly string[] | undefined | null): string[];
+export declare function isOcrLanguageCode(code: string): boolean;
+/** Where a language is downloaded from: tessdata best_int, as tesseract.js's own default. */
+export declare function ocrLanguageSource(code: string): string;
+/** The languages that can be read with now: installed ones, and English. */
+export declare function installedOcrLanguages(dataDir?: string): Promise<string[]>;
+export interface OcrInstallResult {
+    installed: string[];
+    failed: {
+        language: string;
+        reason: string;
+    }[];
+}
+/**
+ * Download the languages not installed yet. English is never downloaded: it
+ * ships with the tool.
+ *
+ * Written to a partial file and renamed, so an interrupted download is never
+ * taken for a model, and checked for gzip's magic bytes, so an error page
+ * served with status 200 is not either.
+ */
+export declare function installOcrLanguages(languages: readonly string[], options?: {
+    dataDir?: string;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<OcrInstallResult>;
+export declare class OcrLanguageMissingError extends Error {
+    readonly languages: readonly string[];
+    constructor(languages: readonly string[]);
+}
+/** One tesseract worker, for every page of one call. */
+export declare class TesseractReader {
+    private readonly worker;
+    readonly languages: readonly string[];
+    private constructor();
+    static open(languages: readonly string[], dataDir?: string): Promise<TesseractReader>;
+    recognize(png: Uint8Array): Promise<{
+        text: string;
+        confidence: number;
+    }>;
+    close(): Promise<void>;
+}

package/dist/extensions/tools/executors/document/office-oxide.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The vendored office_oxide module (`scripts/build-office-oxide.sh`).
+ */
+export interface OfficeOxideDocument {
+    toMarkdownWithImages(): string;
+    plainText(): string;
+    free(): void;
+}
+/**
+ * Where the module is. Two places, in the order a host would want.
+ *
+ * Beside the bundle is the shipped case: the extension's build copies it to
+ * `dist/office-oxide/`, as it does the tree-sitter grammars. Otherwise it is
+ * core's own `assets/`, found by walking up from this module: one level from
+ * `dist/`, five from this file in `src/`.
+ */
+export declare function resolveOfficeOxideWasm(besideDir?: string): string | undefined;
+/** Open a legacy Office file. Throws with a sentence when the module is missing. */
+export declare function openOfficeOxide(data: Uint8Array, format: "doc" | "xls" | "ppt" | "docx" | "xlsx" | "pptx"): OfficeOxideDocument;

package/dist/extensions/tools/executors/document/office-oxide.generated.d.ts

@@ -0,0 +1,82 @@
+/**
+ * A parsed Office document for use in JavaScript/WASM.
+ */
+export declare class WasmDocument {
+    __destroy_into_raw(): any;
+    free(): void;
+    /**
+     * Return the format name: "docx", "xlsx", or "pptx".
+     * @returns {string}
+     */
+    formatName(): string;
+    /**
+     * Create a new document from raw bytes and a format string ("docx", "xlsx", "pptx").
+     * @param {Uint8Array} data
+     * @param {string} format
+     */
+    constructor(data: any, format: any);
+    /**
+     * Extract plain text from the document.
+     * @returns {string}
+     */
+    plainText(): string;
+    /**
+     * Convert the document to an HTML fragment.
+     * @returns {string}
+     */
+    toHtml(): string;
+    /**
+     * Convert the document to a JSON IR representation.
+     * @returns {any}
+     */
+    toIr(): any;
+    /**
+     * Convert to markdown, embedding each image inline as
+     * `[image-base64:<data>]` at its position in the document flow.
+     *
+     * Images are otherwise dropped from markdown entirely, which loses
+     * both their content and their position.
+     * @returns {string}
+     */
+    toMarkdownWithImages(): string;
+    /**
+     * Convert the document to markdown.
+     * @returns {string}
+     */
+    toMarkdown(): string;
+}
+/**
+ * An Office document opened for editing from JavaScript/WASM.
+ *
+ * WASM had no file-editing API at all, so an agent could read a document
+ * but never change one. The document is held in memory with every OPC part
+ * preserved, so parts this crate does not model (images, charts, custom
+ * XML) survive the round-trip untouched.
+ */
+export declare class WasmEditableDocument {
+    __destroy_into_raw(): any;
+    free(): void;
+    /**
+     * Open a document for editing from raw bytes and a format string
+     * ("docx", "xlsx", "pptx").
+     * @param {Uint8Array} data
+     * @param {string} format
+     */
+    constructor(data: any, format: any);
+    /**
+     * Replace every occurrence of `find` with `replace` in the document's
+     * text, returning how many replacements were made.
+     * @param {string} find
+     * @param {string} replace
+     * @returns {number}
+     */
+    replaceText(find: any, replace: any): number;
+    /**
+     * Serialise the edited document back to bytes.
+     * @returns {Uint8Array}
+     */
+    toBytes(): any;
+}
+declare function initSync(module: any): any;
+declare function __wbg_init(module_or_path: any): Promise<any>;
+export { initSync, __wbg_init as default };

package/dist/extensions/tools/executors/document/office.d.ts

@@ -0,0 +1,10 @@
+/**
+ * OOXML, OpenDocument, RTF, CSV and HTML through officeparser.
+ *
+ * officeparser parses to a tree and renders the tree to markdown. Its
+ * markdown carries every picture as a base64 data URI, which in a tool result
+ * is the picture's bytes spelled out as text, so the renderer's `onNode` hook
+ * replaces each one with a link to the file it was written to.
+ */
+import type { DocumentFormat, DocumentReadResult, ReadOptions } from "./formats";
+export declare function readOffice(data: Uint8Array, format: DocumentFormat, options: ReadOptions): Promise<DocumentReadResult>;

package/dist/extensions/tools/executors/document/pdf.d.ts

@@ -0,0 +1,6 @@
+/**
+ * PDF through pdf.js (`pdfjs-dist`, legacy build, in this thread: no canvas,
+ * no worker file). See `pdfjs.ts` for why not unpdf.
+ */
+import type { DocumentReadResult, ReadOptions } from "./formats";
+export declare function readPdf(data: Uint8Array, options: ReadOptions): Promise<DocumentReadResult>;

package/dist/extensions/tools/executors/document/pdfjs.d.ts

@@ -0,0 +1,30 @@
+/**
+ * pdf.js, from `pdfjs-dist`'s legacy build, run in this thread.
+ *
+ * Not unpdf's "serverless" build, which this reader used first: to be
+ * dependency-free, that build replaces pdf.js's WebAssembly decoders with
+ * stubs, so every CCITT, JBIG2 and JPEG 2000 image fails to decode ("JBig2
+ * failed to initialize"). Those are how most scanners and archives store a
+ * page, which made it useless for the one job OCR needs it for: getting the
+ * page image out.
+ */
+export type Pdfjs = typeof import("pdfjs-dist/legacy/build/pdf.mjs");
+/**
+ * Loaded on first use: pdf.js is megabytes of code that a session which never
+ * reads a PDF should not pay for at startup.
+ *
+ * The worker's code is put on `globalThis.pdfjsWorker`, which pdf.js checks
+ * before starting a worker: it then runs in this thread, with no worker file
+ * to find, which is what lets it be bundled.
+ */
+export declare function loadPdfjs(): Promise<Pdfjs>;
+/**
+ * A directory in the form pdf.js takes: ending in a forward slash.
+ *
+ * pdf.js appends a file name to it and refuses anything else ("must include
+ * trailing slash"), so the platform separator is wrong on Windows, where it
+ * failed every PDF. Node reads `C:\\dir/file` there without complaint.
+ */
+export declare function asDirectoryUrl(directory: string | undefined): string | undefined;
+/** What every document is opened with: decoders and character maps found. */
+export declare function pdfjsDocumentOptions(): Record<string, unknown>;

package/dist/extensions/tools/executors/document/range.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `range`: which pages, slides, sheets or chapters to read.
+ */
+export interface UnitRange {
+    /** Whether a one-based unit is selected. */
+    selects: (unit: number) => boolean;
+    /** The spec as given, for file names and messages. */
+    spec: string;
+}
+/**
+ * Parse `"1-5,9,12-"`: single units, closed spans, and an open end.
+ *
+ * Throws with a sentence the model can act on; the executor turns a throw
+ * into `success: false`.
+ */
+export declare function parseUnitRange(spec: string | undefined): UnitRange | undefined;
+/** `[1,2,3,5,7,8]` as `1-3, 5, 7-8`. */
+export declare function formatUnits(units: readonly number[]): string;

package/dist/extensions/tools/executors/document/recognition.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Reading scanned pages and describing pictures: which engine a call uses,
+ * and the work itself.
+ *
+ * Three ways to read a scanned page, in the user's order of preference:
+ * tesseract on this machine; the vision model the user configured for the
+ * session (the Vision tab, or the CLI's --vision-model); or, with neither, the
+ * session's own model, which is handed the page images when it can see them.
+ */
+import type { AgentImageToDescribe } from "@cerebriline/shared";
+import type { PageImage, RecognizedText } from "./formats";
+import { type DocumentReaderSettings } from "./ocr";
+export type DescribeImages = (images: readonly AgentImageToDescribe[]) => Promise<readonly (string | undefined)[]>;
+/** What the call asked for: `auto` is the user's setting. */
+export type OcrRequest = "auto" | "tesseract" | "vision" | "none";
+/**
+ * Pages recognized per call. Past it the rest are named, and a range reads
+ * them: a 400-page scanned book is minutes of recognition, and the call would
+ * outlast its timeout long before it finished.
+ */
+export declare const TESSERACT_PAGE_LIMIT = 40;
+/** A vision model reads a page in seconds, and each page is a request. */
+export declare const VISION_PAGE_LIMIT = 12;
+/** Pages handed to the session's own model: each is an image in its context. */
+export declare const SELF_PAGE_LIMIT = 4;
+/** Pictures described per call. */
+export declare const DESCRIBE_LIMIT = 16;
+export interface RecognitionPlan {
+    /** Passed to the reader; undefined when no recognition happens. */
+    recognize?: (page: number, images: readonly PageImage[]) => Promise<RecognizedText | undefined>;
+    /** Page images for the session's model to read, in `self` mode. */
+    readonly attachments: {
+        page: number;
+        png: Uint8Array;
+    }[];
+    /** Sentences for the result header. */
+    notes(scannedPages: readonly number[], recognizedPages: readonly number[]): string[];
+    close(): Promise<void>;
+}
+interface PlanInput {
+    request: OcrRequest | undefined;
+    languages: string | undefined;
+    settings: DocumentReaderSettings;
+    describeImages?: DescribeImages;
+    modelSupportsImages: boolean;
+}
+/**
+ * The recognition a call will do, ready to hand to the reader.
+ *
+ * tesseract's worker is started on the first scanned page, not before: most
+ * documents have none, and starting it costs a fifth of a second and a thread.
+ */
+export declare function planRecognition(input: PlanInput): RecognitionPlan;
+export interface PictureToDescribe {
+    link: string;
+    mediaType: string;
+    data: Uint8Array;
+    source?: string;
+}
+/**
+ * Descriptions of a document's pictures, one request each, in order.
+ * `undefined` for any the vision model could not describe.
+ */
+export declare function describePictures(describeImages: DescribeImages, pictures: readonly PictureToDescribe[], documentName: string): Promise<(string | undefined)[]>;
+/** A description short enough for alt text: its first sentences, up to 300 characters. */
+export declare function altTextOf(description: string): string;
+export {};