@cerebriline/core 4.100.240 → 4.100.242

package/dist/extensions/tools/executors/document/read-protocol.d.ts

@@ -0,0 +1,65 @@
+/**
+ * What the session and its reader process say to each other.
+ *
+ * Sent over Node's IPC channel with structured-clone serialization, so byte
+ * arrays arrive as byte arrays.
+ */
+import type { AgentImageToDescribe } from "@cerebriline/shared";
+import type { DocumentFormat, DocumentReadResult, ReadProgress } from "./formats";
+import type { ExtractedImage } from "./images";
+import type { ReadJob } from "./read-job";
+/** Where, inside the job's scratch directory, the pictures are handed back. */
+export declare const READ_OUTPUT_DIRECTORY = ".out";
+export type ParentMessage = {
+    type: "start";
+    job: ReadJob;
+    hasVision: boolean;
+} | {
+    type: "abort";
+}
+/** The answer arrived whole: the reader may go. */
+ | {
+    type: "received";
+} | {
+    type: "described";
+    id: number;
+    descriptions?: (string | undefined)[];
+    error?: string;
+};
+export type ChildMessage = {
+    type: "ready";
+} | {
+    type: "progress";
+    progress: ReadProgress;
+} | {
+    type: "note";
+    line: string;
+} | {
+    type: "describe";
+    id: number;
+    images: AgentImageToDescribe[];
+} | {
+    type: "done";
+    format: DocumentFormat;
+    result: DocumentReadResult;
+    /** Each picture's bytes are in `file`. */
+    images: {
+        image: ExtractedImage;
+        file: string;
+    }[];
+    recognitionNotes: string[];
+    recognitionProblems: string[];
+    attachments: {
+        page: number;
+        png: Uint8Array;
+    }[];
+    problems: string[];
+    usage: {
+        ms: number;
+        peakRssMb: number;
+    };
+} | {
+    type: "failed";
+    message: string;
+    aborted: boolean;
+};

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

@@ -35,6 +35,11 @@ export interface RecognitionPlan {
     }[];
     /** Sentences for the result header. */
     notes(scannedPages: readonly number[], recognizedPages: readonly number[]): string[];
+    /**
+     * Every scanned page that has no recognized text, with the reason, a line
+     * each. `notes` is the summary a reader skims; this is the whole account.
+     */
+    problems(scannedPages: readonly number[], recognizedPages: readonly number[]): string[];
     close(): Promise<void>;
 }
 interface PlanInput {
@@ -43,6 +48,12 @@ interface PlanInput {
     settings: DocumentReaderSettings;
     describeImages?: DescribeImages;
     modelSupportsImages: boolean;
+    /**
+     * How many scanned pages are recognized. A book kept in the Library is
+     * read whole: its call is long by design and reports as it goes.
+     * @default the engine's per-call limit
+     */
+    pageLimit?: number;
 }
 /**
  * The recognition a call will do, ready to hand to the reader.
@@ -54,13 +65,11 @@ export declare function planRecognition(input: PlanInput): RecognitionPlan;
 export interface PictureToDescribe {
     link: string;
     mediaType: string;
-    data: Uint8Array;
+    /** The bytes, or where to read them when they are asked for: one picture in memory at a time. */
+    data: Uint8Array | (() => Promise<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 describePicture(describeImages: DescribeImages, picture: PictureToDescribe, documentName: string): Promise<string | undefined>;
 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;

package/dist/extensions/tools/executors/document-extract.d.ts

@@ -8,6 +8,7 @@
  */
 import type { AgentOverlay } from "../../../runtime/sandbox/overlay-fs";
 import type { ExtractDocumentExecutor } from "../types";
+import { type DocumentFormat, type ReadProgress } from "./document/formats";
 import type { DocumentReaderSettings } from "./document/ocr";
 import { type DescribeImages } from "./document/recognition";
 /** Where extractions go when the call names no `output_dir`. */
@@ -17,7 +18,7 @@ export interface DocumentExtractExecutorOptions {
     cwd?: string;
     /** A delegated agent's overlay: reads fall through, writes stay private. */
     overlay?: AgentOverlay;
-    /** @default 200 MB */
+    /** Over the reader's `maxFileMb` setting. @default 1 GB */
     maxFileSizeBytes?: number;
     /** The user's Document Reader settings: how scanned pages are read, and descriptions. */
     reader?: DocumentReaderSettings;
@@ -28,6 +29,18 @@ export interface DocumentExtractExecutorOptions {
      */
     describeImages?: DescribeImages;
 }
+/**
+ * The largest file read unless the settings say otherwise.
+ *
+ * 200 MB once, when a book was read inside the session's own process and one
+ * large enough could take it down. Each is read in a process of its own now,
+ * and out of memory there is one file's error. Measured with that reader on
+ * the largest books of a real shelf: a 228 MB EPUB, 812 MB at its peak in 3 s;
+ * a 411 MB PDF, 2.6 GB in 80 s.
+ */
+export declare const DEFAULT_MAX_FILE_MB = 1024;
+/** The limit in bytes: an explicit one, else the setting, else the default. */
+export declare function documentReaderLimitBytes(maxFileSizeBytes: number | undefined, reader: DocumentReaderSettings | undefined): number;
 /**
  * The executor options a session's configuration gives the tool: the user's
  * settings and the session's vision model. The same for the lead and every
@@ -52,4 +65,110 @@ export declare function markdownToText(markdown: string): string;
  * and all of it is tokens.
  */
 export declare function tidyMarkdown(markdown: string): string;
+export interface DocumentText {
+    /** The document as markdown. */
+    markdown: string;
+    format: DocumentFormat;
+    title?: string;
+    author?: string;
+    bytes: number;
+    /** What was skipped or could not be read, in sentences. */
+    notes: string[];
+}
+/**
+ * A document's text, and nothing written anywhere: what the Library indexes.
+ *
+ * The same readers as the tool, without the pictures. Scanned pages are read
+ * when the settings name an engine that needs no model in the conversation
+ * (tesseract, or the vision model when one is given).
+ */
+export declare function readDocumentText(filePath: string, options: {
+    /** Removed afterwards. Not the system temp directory: a book's pages can be large. */
+    scratchDir: string;
+    maxFileSizeBytes?: number;
+    reader?: DocumentReaderSettings;
+    describeImages?: DescribeImages;
+}): Promise<DocumentText>;
+export interface BookDocument extends DocumentText {
+    /**
+     * The pictures inside it; the markdown links them as `images/<file>`.
+     * Each one's bytes are in the file at `path`, not in memory: a scanned
+     * book is a picture a page. They are there until `release`.
+     */
+    images: {
+        file: string;
+        path: string;
+        mediaType: string;
+        width?: number;
+        height?: number;
+        origin?: string;
+        description?: string;
+        /** `description` is a vision model's, not the caption the document gave. */
+        described?: boolean;
+    }[];
+    /** Pages or chapters it has, and how many were read. */
+    units?: {
+        name: string;
+        total: number;
+        read: number;
+    };
+    /** Scanned pages, and how many of them had their text recognized. */
+    scanned?: {
+        pages: number;
+        recognized: number;
+    };
+    /**
+     * Everything that was left out, a line each: a scanned page with no
+     * recognized text, a picture that could not be taken out. Empty when the
+     * whole document was read.
+     */
+    problems: string[];
+    /**
+     * Removes the pictures' files. Called once the book is filed or given
+     * up, on every path; a session that dies first leaves them for
+     * `sweepAbandonedReads`.
+     */
+    release(): Promise<void>;
+}
+/**
+ * Remove scratch directories that reads left behind: a session that ended
+ * between reading a book and filing it never released its pictures.
+ */
+export declare function sweepAbandonedReads(scratchDir: string, olderThanMs?: number): Promise<void>;
+/**
+ * A document as the Library keeps a book: its text and its pictures.
+ * Nothing is written anywhere the caller sees; the caller puts the pictures
+ * where the book is kept, `describeBookPictures` has a vision model look at
+ * them, and `release` removes them.
+ */
+export declare function readDocumentForBook(filePath: string, options: {
+    scratchDir: string;
+    maxFileSizeBytes?: number;
+    reader?: DocumentReaderSettings;
+    describeImages?: DescribeImages;
+    /**
+     * Take the pictures out as well. Off for a read that only compares
+     * text: a scanned book is a picture a page, a gigabyte of them decoded.
+     * @default true
+     */
+    pictures?: boolean;
+    /** Stops the read at the next page or chapter; the read throws. */
+    signal?: AbortSignal;
+    onProgress?: (progress: ReadProgress) => void;
+    /** Lines for the log: what the decoder warned about, a picture asked for twice. */
+    onNote?: (line: string) => void;
+}): Promise<BookDocument>;
+/**
+ * Have the vision model describe a book's pictures: each description is kept
+ * with its picture and becomes the alt text where the text shows it, so a
+ * search for what a figure shows finds the page it is on. Resolves with how
+ * many were described and how many could have been.
+ */
+export declare function describeBookPictures(book: BookDocument, describeImages: DescribeImages, options: {
+    documentName: string;
+    limit?: number;
+}): Promise<{
+    described: number;
+    candidates: number;
+}>;
 export declare function createDocumentExtractExecutor(options?: DocumentExtractExecutorOptions): ExtractDocumentExecutor;

package/dist/extensions/tools/librarian-tools.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The librarian's tools: everything that changes the Library.
+ *
+ * They come with the `librarian` skill, which says how the work is done:
+ * check whether a book is already here before adding it, ask the user when
+ * it is another edition, put it on the shelf it belongs on. The tools keep
+ * the rules that must hold whoever is asking: nothing is added over a book
+ * that looks the same without being told to, and nothing is deleted, only
+ * moved to the trash.
+ */
+import { type AgentTool } from "@cerebriline/shared";
+import { type BookDocument } from "./executors/document-extract";
+import { type CreateLibraryToolsOptions } from "./library-tools";
+export declare const LIBRARIAN_TOOL_NAMES: readonly ["library_check", "library_add", "library_organize", "library_transfer", "web_scrape", "library_web_book"];
+export interface ReadSource {
+    file: string;
+    name: string;
+    sha256: string;
+    document: BookDocument;
+    isbn?: string;
+    fingerprint: number[];
+    /** The lines on most of its pages: which document it is, see running-heads.ts. */
+    runningHeads: string[];
+}
+/** An ISBN printed in the first pages, when there is one. */
+export declare function findIsbn(markdown: string): string | undefined;
+export declare function compareBatch(sources: readonly ReadSource[]): Map<string, string[]>;
+/**
+ * The librarian's tools. The two web tools are there only when a scraping
+ * endpoint is configured and the session's profile allows it.
+ */
+export declare function createLibrarianTools(options: CreateLibraryToolsOptions): AgentTool[];

package/dist/extensions/tools/library-import-run.d.ts

@@ -0,0 +1,79 @@
+/**
+ * One librarian call that reads files, as the person watching sees it.
+ *
+ * Reading a book is minutes: every page of a PDF, every scanned page through
+ * recognition. A row that sits unchanged for that long reads as a hang, and
+ * a real hang looks the same. So the call says where it is, file by file,
+ * and says so when a file has stopped moving; it can be cancelled from its
+ * row; and however it ends, the model is told what was read, what was left
+ * out and why, a line for each.
+ */
+import type { AgentToolContext } from "@cerebriline/shared";
+import type { ReadProgress } from "./executors/document/formats";
+/**
+ * Cancels every librarian call that is reading files. Each one ends as a
+ * failed tool call whose error is its full report.
+ * @returns how many were cancelled
+ */
+export declare function cancelLibraryImports(): number;
+/** Whether a librarian call is reading files right now. */
+export declare function hasActiveLibraryImports(): boolean;
+export declare class LibraryImportCancelled extends Error {
+    constructor(reason: string);
+}
+export declare class LibraryImportRun {
+    private readonly what;
+    private readonly context;
+    private readonly log?;
+    private readonly entries;
+    private readonly controller;
+    private readonly startedAt;
+    private readonly timer;
+    private readonly onOuterAbort;
+    private lastEmit;
+    private lastLog;
+    private pendingEmit;
+    private cancelReason;
+    private closed;
+    private rejectOnCancel;
+    private readonly cancelled;
+    constructor(what: string, files: readonly string[], context: AgentToolContext | undefined, log?: ((message: string) => void) | undefined, 
+    /** What an item is called on its line. @default the file's name */
+    label?: (item: string) => string);
+    /** Handed to the reader: it stops at the next page or chapter. */
+    get signal(): AbortSignal;
+    get isCancelled(): boolean;
+    /** @returns false when it was already cancelled or over */
+    cancel(reason: string): boolean;
+    /**
+     * The work, or the cancellation, whichever is first. A reader notices a
+     * cancellation at its next page; one that is waiting on something that
+     * never answers does not, and the call must still end.
+     */
+    guard<T>(work: Promise<T>): Promise<T>;
+    private entry;
+    start(file: string): void;
+    progress(file: string, progress: ReadProgress): void;
+    /** A line about a file for the log alone. */
+    note(file: string, line: string): void;
+    /** What a file is doing after it was read: "describing pictures". */
+    stage(file: string, stage: string | undefined): void;
+    done(file: string, outcome: string, problems?: readonly string[]): void;
+    fail(file: string, why: string): void;
+    private line;
+    private counts;
+    /** The row's text: a line of totals, then a line a file. */
+    statusText(): string;
+    /** Where the files in progress are, for the log and for a cancellation. */
+    private standing;
+    private tick;
+    private emit;
+    /**
+     * What happened to every file, for the model: read or not, how far, and
+     * every page and picture that was left out, with the reason.
+     */
+    report(): string[];
+    /** The error a cancelled call ends with: why, and the whole report. */
+    cancellation(extra?: readonly string[]): Error;
+    close(): void;
+}

package/dist/extensions/tools/library-tools.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The Library's tools: what the model sees of it.
+ *
+ * `search_library` finds passages in the books the user has collected and
+ * `list_library` says what is there, shelf by shelf. Both are offered
+ * whenever the Library is on. Everything that changes the Library is the
+ * librarian's (`librarian-tools.ts`), and offered only with that skill.
+ *
+ * They work on keywords alone; an embedding model and a reranker, when the
+ * user has configured them, make the search better and change nothing else.
+ */
+import { type AgentTool, type LibrarySettings } from "@cerebriline/shared";
+import type { Catalogue, LibraryBook, LibraryShelf } from "../../services/retrieval/catalogue";
+import type { RetrievalEndpoint } from "../../services/retrieval/embedding-client";
+import type { ScrapeEndpoint } from "../../services/retrieval/firecrawl";
+import { type Library } from "../../services/retrieval/library";
+import type { RetrieveResult } from "../../services/retrieval/retrieve";
+import type { DocumentReaderSettings } from "./executors/document/ocr";
+import type { DescribeImages } from "./executors/document/recognition";
+export declare const LIBRARY_TOOL_NAMES: readonly ["search_library", "list_library"];
+export type LibraryToolName = (typeof LIBRARY_TOOL_NAMES)[number];
+/** The built-in skill that brings the librarian's tools with it. */
+export declare const LIBRARIAN_SKILL_NAME = "librarian";
+export interface LibraryScrapeConfig extends ScrapeEndpoint {
+    /** Pages one crawl reads, at most. */
+    maxPages: number;
+    /** How many links deep a crawl follows. */
+    maxDepth: number;
+}
+export interface LibraryToolsConfig {
+    settings: LibrarySettings;
+    /** The embedding model, when the user has set one. */
+    embedding?: RetrievalEndpoint;
+    /** The reranking model, when the user has set one. */
+    reranker?: RetrievalEndpoint;
+    documentReader?: DocumentReaderSettings;
+    /**
+     * The scraping endpoint, when it is set up under Features and the
+     * session's profile allows it. Without it the librarian has no web tools.
+     */
+    scrape?: LibraryScrapeConfig;
+}
+export interface CreateLibraryToolsOptions {
+    cwd: string;
+    /**
+     * Read on every call: the settings can change mid-session. Undefined, or
+     * settings with `enabled` off, means the Library is off.
+     */
+    getConfig: () => LibraryToolsConfig | undefined;
+    /** @default the shared Library of the data folder */
+    library?: Library;
+    /**
+     * The model that describes a book's pictures, read when a book is added.
+     * May take a moment: a host can ask a server whether a model reads images.
+     */
+    getDescribeImages?: () => DescribeImages | undefined | Promise<DescribeImages | undefined>;
+    /** Whether the librarian's tools are offered. @default the librarian skill is on */
+    librarian?: boolean;
+    onError?: (message: string, error: unknown) => void;
+    log?: (message: string) => void;
+}
+export declare const LIBRARY_OFF = "The Library is turned off. The user turns it on under Settings > Library; do not call this again in this task.";
+export declare function errorText(error: unknown): string;
+export declare function strings(value: unknown): string[];
+export declare function text(value: unknown): string;
+export declare function activeConfig(options: CreateLibraryToolsOptions): LibraryToolsConfig | undefined;
+export declare function plural(count: number, one: string, many?: string): string;
+/** What is on the shelves, as the model is shown it. */
+export declare function describeShelves(catalogue: Catalogue): string;
+/**
+ * A shelf as the model names it: "Section / Shelf", or the shelf's name
+ * alone when only one shelf has it.
+ */
+export declare function resolveShelf(catalogue: Catalogue, reference: string, section?: string): (LibraryShelf & {
+    section: string;
+}) | undefined;
+export declare function describeBookLine(book: LibraryBook): string;
+export declare function describeSearch(query: string, result: RetrieveResult, collectionName: (id: number) => string): string;
+/** One book in full: what it is, what it was made from, its pictures. */
+export declare function describeBook(catalogue: Catalogue, book: LibraryBook): string;
+/** Whether the user has the librarian skill turned on. */
+export declare function isLibrarianEnabled(): boolean;
+/**
+ * The Library's tools, when the Library is on at session start. Whether it
+ * is on is read again on every call, so turning it off mid-session stops the
+ * tools answering without a restart.
+ */
+export declare function createLibraryTools(options: CreateLibraryToolsOptions): AgentTool[];

package/dist/extensions/tools/memory-tools.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Memory's tools: `remember`, `recall` and `forget`.
+ *
+ * What the model keeps from one task to the next. The store works on
+ * keywords alone; the embedding and reranking models of the Embedding tab,
+ * when set, make a recall find a note by what it means.
+ *
+ * Which memories a session uses is the user's choice per workspace, made in
+ * the Memory panel: one memory new notes are kept in, and the memories that
+ * are searched. The tools take no memory name: a model cannot store to, or
+ * read from, a memory the user did not allow this workspace.
+ */
+import { type AgentTool, type MemorySettings } from "@cerebriline/shared";
+import { type Memory, type MemoryEndpoints } from "../../services/retrieval/memory";
+export declare const MEMORY_TOOL_NAMES: readonly ["remember", "recall", "forget"];
+export type MemoryToolName = (typeof MEMORY_TOOL_NAMES)[number];
+export interface MemoryToolsConfig extends MemoryEndpoints {
+    settings: MemorySettings;
+}
+export interface CreateMemoryToolsOptions {
+    /** The workspace, which is what the user's choice of memories is filed under. */
+    cwd: string;
+    /** Read on every call. Undefined, or `enabled` off, means Memory is off. */
+    getConfig: () => MemoryToolsConfig | undefined;
+    /** @default the shared Memory of the data folder */
+    memory?: Memory;
+    onError?: (message: string, error: unknown) => void;
+    log?: (message: string) => void;
+}
+/**
+ * The memories this workspace uses, held to the ones that exist: a memory
+ * deleted after it was picked is left out of the search, and notes go to
+ * the main memory rather than nowhere.
+ */
+export declare function resolveMemoryAccess(memory: Memory, settings: MemorySettings, cwd: string): {
+    store: string;
+    recall: string[];
+    storeFellBack?: string;
+};
+/** Memory's tools, when Memory is on at session start. */
+export declare function createMemoryTools(options: CreateMemoryToolsOptions): AgentTool[];