@cerebriline/core 4.100.240 → 4.100.241

package/assets/skills/tdd-wizard/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: tdd-wizard
+description: >-
+  Guides the user into test-driven development from the start: learns about
+  the project, takes an existing specification or writes one with the user
+  through questions about goals and scope, then develops the test cases with
+  them, generates the tests, validates them and writes them to the project.
+  Ends by offering to carry on with the implementation, test run and coverage
+  phases or to leave those to the user. Use when the user wants to start a
+  project or a feature test-first, asks for a TDD wizard, or wants a
+  specification turned into tests.
+disabled: true
+---
+
+# Skill: TDD Wizard
+
+Takes the user from an idea to a specification and a set of tests that describe it, ready for the code to be written against them. It is a guided conversation: the user decides, this skill asks, proposes, writes and checks.
+
+Part of the TDD set: `tdd-gen` (implements from tests), `tdd-test` (runs them), `tdd-coverage` (finds what is untested). The wizard works when those are off.
+
+## How to conduct it
+
+- **One stage at a time, and stop at each gate.** Every stage ends with something the user confirms before the next begins. Do not run ahead.
+- **Ask one question at a time**, or a small group about one topic. Where the likely answers are few, offer them as choices, with your recommendation first. Never send a questionnaire.
+- **Do not ask what the repo can answer.** Read first.
+- **Propose, do not interrogate.** When the user is unsure, suggest a concrete answer for them to accept or change.
+- **Write no implementation code** in this skill. Its output is the specification and the tests.
+- If the user wants to skip a stage or already has its result, take what they have and move on.
+
+Say at the start, in two or three lines, what the stages are and that they can stop after any of them.
+
+## Stage 1: The project
+
+Read before asking: the README, the manifest (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `*.csproj`, ...), the folder layout, the existing tests and their config.
+
+Establish:
+
+- **new or existing:** an empty or near-empty repo, or a feature for a project that already has code;
+- **language and test framework.** Existing project: the ones it uses, and how its tests are named, placed and written. New project: ask for the language, then propose the framework that is the default for it (Vitest for TypeScript or JavaScript, pytest for Python, the built-in runner for Go and Rust, xUnit for .NET, JUnit for Java);
+- **where tests go**, by the project's convention or the framework's;
+- **what this session is about:** the whole project, or one feature of it.
+
+**Gate:** state what you found in a few lines and have the user confirm or correct it.
+
+## Stage 2: The specification
+
+Ask first: **is there a specification already?** A file in the repo, a document to paste, an issue or a ticket.
+
+**There is one.** Read it. Check it against the list below and ask only about what is missing or ambiguous. Offer to save an updated copy; do not rewrite the user's document unasked.
+
+**There is none.** Build it with the user, a topic at a time:
+
+1. **Goal:** what this is for, in a sentence or two. Who or what uses it.
+2. **Scope:** what it does. Get this as concrete behaviours ("a user can reset a password by email"), not qualities ("secure", "fast").
+3. **Out of scope:** what it deliberately does not do. This is as valuable as the scope; ask for it explicitly.
+4. **Interfaces:** how it is used: functions, a command line, HTTP endpoints, a screen. The inputs and outputs of each.
+5. **Rules:** validation, limits, calculations, states and what moves between them.
+6. **Errors:** what can go wrong, and what must happen when it does.
+7. **Constraints:** platform, dependencies it must or must not use, performance or data limits that are real requirements.
+
+Do not go deeper than the user's project needs: a small utility has a short specification.
+
+Then write the specification file. Default path `docs/SPEC.md`, or beside the feature for a single feature; ask if the repo suggests another place. Use this shape:
+
+```markdown
+# <Project or feature>: Specification
+
+## Goal
+## Scope
+## Out of scope
+## Interfaces
+## Requirements
+- **R1** <one behaviour, stated so that a test can prove it>
+- **R2** ...
+## Errors
+- **E1** <condition> → <what must happen>
+## Constraints
+## Open questions
+```
+
+Each requirement:
+
+- is one behaviour, not several joined by "and";
+- is **testable**: it names an input or situation and an observable result. "Handles large files well" is not a requirement; "reads a 1 GB file without holding it in memory" is;
+- has an id (`R1`, `E1`) that the tests will refer to.
+
+Anything the user could not decide goes under **Open questions**, not into a requirement as a guess.
+
+**Gate:** show the specification and have the user approve it or change it. Tests are written against the approved text.
+
+## Stage 3: The test cases
+
+Derive the cases from the specification, not from imagined code. For each requirement and each error:
+
+- the **normal case**: typical input, the expected result;
+- the **boundaries**: empty, zero, one, the maximum, the first and the last, exactly at a limit and just past it;
+- the **invalid input** and the **error path** the specification names;
+- for anything with state: the order of operations, and doing the same thing twice.
+
+Present them as a table before writing any test code:
+
+| ID | Requirement | Case | Input / situation | Expected |
+|---|---|---|---|---|
+| T1 | R1 | valid data | name and email given | user returned with an id |
+| T2 | R1 | empty name | name is `""` | rejected: "Name is required" |
+
+Then go through it with the user: is a case missing, is one wrong, is one not worth having? Ask in particular about expected values you had to assume, such as an exact error message, a rounding rule or an ordering. A specification gap found here goes back into the specification file.
+
+Also settle with the user:
+
+- **the interface the tests will call:** the names and signatures of the functions, classes or endpoints. The tests fix these, so they are a design decision; propose them and let the user adjust;
+- **what is faked:** the clock, the network, the database, the file system. Prefer passing dependencies in over patching them.
+
+**Gate:** the user approves the table and the interface.
+
+## Stage 4: Generate the tests
+
+Write the tests in the project's framework and in the style of its existing tests.
+
+- One test per row of the table, named for the behaviour ("rejects an empty name"), with the requirement id in the name or in a comment so each test traces back to the specification.
+- **Test behaviour through the public interface.** Assert on results and on what a caller can observe, never on private fields or on how the code is built inside.
+- Arrange, act, assert; one behaviour per test. Rows that differ only in data become one table-driven or parameterised test.
+- **Deterministic:** no sleeping, no real clock, no real network, no dependence on test order or on the machine.
+- Import from where the implementation will live, following the project's layout. The file need not exist yet.
+- Do not write the implementation, and do not write tests for behaviour the specification does not contain.
+
+## Stage 5: Validate, then write
+
+Before calling the tests done, check them:
+
+1. **Trace:** every requirement and every error in the specification has at least one test; every test points to a requirement. List anything uncovered.
+2. **They load:** run the test command (the `tdd-test` skill if it is enabled, else the framework's run-once form). The tests must be found and counted. A syntax error, a wrong import of the test framework itself or a config error is a defect in the tests: fix it.
+3. **They fail for the right reason.** With no implementation, each test should fail because the code under test is missing or does not yet do the thing. That is the correct result here, and it is the "red" that test-driven development starts from.
+4. **None passes already.** A test that passes with nothing implemented asserts nothing, or tests the wrong thing. Fix or remove it. (In an existing project a test may pass because the behaviour is already there; say which, and keep it.)
+5. **Expected values match the specification**, row by row. Do not validate tests by adjusting them until they agree with something else.
+
+In some languages the test file cannot even compile until the names it uses exist (Go, Rust, Java, C#, TypeScript with type-checking in the test run). Then say so, and ask before creating the minimum that lets it compile: the declarations with bodies that only raise "not implemented". That is scaffolding, not implementation.
+
+If a framework has to be installed or configured first, say what will be added and ask before changing the project.
+
+Write the test files, then report:
+
+- the specification file;
+- the test files, with the number of tests in each;
+- the trace: requirements to tests, and anything left open;
+- the result of the run: how many were found, and that they fail because the implementation is missing.
+
+## Stage 6: What next
+
+Offer the choice plainly:
+
+1. **Continue now:** implement against these tests (`tdd-gen`), run the whole suite (`tdd-test`), then check coverage (`tdd-coverage`). Stop after each for the user to look, unless they say to go straight through.
+2. **Take it from here themselves:** give the commands for each phase, so they can run them when they choose: implement from a test file with `tdd-gen` on that file, run tests with `tdd-test`, check coverage with `tdd-coverage`.
+3. **Stop here:** the specification and the tests are the deliverable.
+
+If the user continues and one of those skills is not enabled, do the phase directly by the same rules: write the least code that makes the tests pass **without changing the tests**, run them until green, tidy up on green, then measure coverage and propose tests for what is below 80%.
+
+When requirements change later, the order stays the same: the specification first, then the tests, then the code.
+
+## Credits
+
+Written for Cerebriline, as the front end to the workflow described in "[Test-Driven Development with Claude Code: Practical Guide](https://aiskill.market/blog/tdd-with-claude-code)" by Duke Harewood (aiskill.market, January 28, 2026), whose `/tdd`, `/test` and `/coverage` commands are the basis of `tdd-gen`, `tdd-test` and `tdd-coverage`. The test-writing guidance in Stage 4 (behaviour over implementation, table-driven cases, injected dependencies, no timing) follows that article's patterns.

package/dist/extensions/config/bundled-skills.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The skills that ship with the product.
+ *
+ * They live in core's `assets/skills/`, one folder per skill, and are found
+ * beside the bundle first, where the extension's build copies them as
+ * `bundled-skills/`; then beside the executable, which is where the CLI's
+ * build puts them, since a compiled binary's modules have no folder on disk;
+ * and then in core's own `assets/`, by walking up from this module, which is
+ * the case for tests and for core used from `node_modules`.
+ *
+ * A bundled skill is replaced by every update, so nothing is ever written to
+ * its file. Whether it is on is a setting (`bundledSkills` in the global
+ * settings); the `disabled` field in its frontmatter is only the default.
+ */
+/** The folder name beside a bundle. */
+export declare const BUNDLED_SKILLS_DIRECTORY_NAME = "bundled-skills";
+export declare function resolveBundledSkillsDirectory(besideDir?: string): string | undefined;
+export declare function isBundledSkillPath(filePath: string, bundledDirectory?: string | undefined): boolean;
+/**
+ * Whether a bundled skill is on: the user's choice if they made one, and
+ * otherwise what the skill's own frontmatter says.
+ */
+export declare function isBundledSkillEnabled(name: string, enabledByDefault: boolean): boolean;
+export declare function setBundledSkillEnabled(name: string, enabled: boolean): void;

package/dist/extensions/config/index.d.ts

@@ -1,4 +1,5 @@
 export { getBuiltinPromptTemplateSource, getBuiltinPromptTemplates, } from "./builtin-templates";
+export { BUNDLED_SKILLS_DIRECTORY_NAME, isBundledSkillPath, resolveBundledSkillsDirectory, setBundledSkillEnabled, } from "./bundled-skills";
 export { auditCompactionSections, BUILTIN_COMPACTION_PROMPTS, buildCompactionTranslationRequest, type CompactionPromptSources, resolveCompactionPromptSources, stripCompactionSections, } from "./prompt-template-compaction";
 export { createPromptTemplateHooks, type PromptTemplateHooksOptions, } from "./prompt-template-hooks";
 export { loadPromptTemplates, loadPromptTemplatesFromDirectory, PROMPT_TEMPLATES_DIRECTORY_NAME, type PromptTemplateDirectory, type PromptTemplateFileWarnings, type PromptTemplateLoadError, type PromptTemplateLoadResult, resolvePromptTemplateDirectories, } from "./prompt-template-loader";
@@ -10,6 +11,6 @@ export { getShippedToolCallSignatures, HOST_TOOL_INPUT_SCHEMAS, } from "./shippe
 export type { UnifiedConfigDefinition, UnifiedConfigFileCandidate, UnifiedConfigFileContext, UnifiedConfigRecord, UnifiedConfigWatcherEvent, UnifiedConfigWatcherOptions, } from "./unified-config-file-watcher";
 export { UnifiedConfigFileWatcher } from "./unified-config-file-watcher";
 export type { CreateInstructionWatcherOptions, CreateRulesConfigDefinitionOptions, CreateSkillsConfigDefinitionOptions, CreateWorkflowsConfigDefinitionOptions, ParseMarkdownFrontmatterResult, RuleConfig, SkillConfig, UserInstructionConfig, UserInstructionConfigType, WorkflowConfig, } from "./user-instruction-config-loader";
-export { createRulesConfigDefinition, createSkillsConfigDefinition, createWorkflowsConfigDefinition, parseRuleConfigFromMarkdown, parseSkillConfigFromMarkdown, parseWorkflowConfigFromMarkdown, RULES_CONFIG_DIRECTORY_NAME, resolveRulesConfigSearchPaths, resolveSkillsConfigSearchPaths, resolveWorkflowsConfigSearchPaths, SKILLS_CONFIG_DIRECTORY_NAME, WORKFLOWS_CONFIG_DIRECTORY_NAME, } from "./user-instruction-config-loader";
+export { createRulesConfigDefinition, createSkillsConfigDefinition, createWorkflowsConfigDefinition, parseRuleConfigFromMarkdown, parseSkillConfigFromMarkdown, parseWorkflowConfigFromMarkdown, RULES_CONFIG_DIRECTORY_NAME, resolveRulesConfigSearchPaths, resolveSkillsConfigSearchPaths, resolveWorkflowsConfigSearchPaths, SKILLS_CONFIG_DIRECTORY_NAME, setBundledSkillEnabledByPath, WORKFLOWS_CONFIG_DIRECTORY_NAME, } from "./user-instruction-config-loader";
 export type { CreateUserInstructionConfigServiceOptions, UserInstructionConfigRecord, UserInstructionConfigService, } from "./user-instruction-service";
 export { combineUserInstructionConfigServices, createUserInstructionConfigService, } from "./user-instruction-service";

package/dist/extensions/config/unified-config-file-watcher.d.ts

@@ -13,6 +13,18 @@ export interface UnifiedConfigFileCandidate {
 export interface UnifiedConfigDefinition<TType extends string = string, TItem = unknown> {
     type: TType;
     directories: ReadonlyArray<string>;
+    /**
+     * Directories that are read and never watched, with everything under
+     * them: files that ship with the program and change only when it is
+     * replaced.
+     *
+     * A watcher is an open handle on the directory, and on Windows a folder
+     * with an open handle anywhere inside it cannot be renamed. The bundled
+     * skills live inside the VS Code extension's own folder, so watching them
+     * made every reinstall of the running version fail with `EPERM: rename`
+     * and "Please restart VS Code before reinstalling".
+     */
+    unwatchedDirectories?: ReadonlyArray<string>;
     discoverFiles?: (directoryPath: string) => Promise<ReadonlyArray<UnifiedConfigFileCandidate>>;
     includeFile?: (fileName: string, filePath: string) => boolean;
     parseFile: (context: UnifiedConfigFileContext<TType>) => TItem;
@@ -52,6 +64,8 @@ export declare class UnifiedConfigFileWatcher<TType extends string = string, TIt
     private readonly baseTypesByDirectory;
     private watchedTypesByDirectory;
     private readonly discoveredDirectoriesByType;
+    /** Read, never watched: see `UnifiedConfigDefinition.unwatchedDirectories`. */
+    private readonly unwatchedRoots;
     private readonly definitionsByType;
     private readonly pendingTypes;
     private flushTimer;
@@ -72,6 +86,7 @@ export declare class UnifiedConfigFileWatcher<TType extends string = string, TIt
     private scheduleFlush;
     private refreshTypeInternal;
     private loadDefinition;
+    private isUnwatched;
     private buildDesiredTypesByDirectory;
     private readDirectoryFileCandidates;
 }

package/dist/extensions/config/user-instruction-config-loader.d.ts

@@ -14,6 +14,11 @@ export interface SkillConfig {
     disabled?: boolean;
     instructions: string;
     frontmatter: Record<string, unknown>;
+    /**
+     * Shipped with the product. Its file is never written: `disabled` here is
+     * the user's setting, or the frontmatter's default where they made none.
+     */
+    bundled?: boolean;
     source?: {
         type: "agent-plugin";
         pluginName: string;
@@ -45,6 +50,11 @@ export interface CreateInstructionWatcherOptions {
 }
 export interface CreateSkillsConfigDefinitionOptions {
     directories?: ReadonlyArray<string>;
+    /**
+     * Where the skills shipped with the product are. Undefined means core's
+     * own; `false` leaves them out. Not used when `directories` is given.
+     */
+    bundledSkillsDirectory?: string | false;
     workspacePath?: string;
     includePluginSkills?: boolean;
     pluginSkillDirectories?: ReadonlyArray<string>;
@@ -60,6 +70,11 @@ export interface CreateWorkflowsConfigDefinitionOptions {
     directories?: ReadonlyArray<string>;
     workspacePath?: string;
 }
+/**
+ * Turn a bundled skill on or off, given its `SKILL.md`. False when the path
+ * is not a bundled skill's, so a caller can fall back to the frontmatter.
+ */
+export declare function setBundledSkillEnabledByPath(filePath: string, enabled: boolean): Promise<boolean>;
 export declare function parseSkillConfigFromMarkdown(content: string, fallbackName: string): SkillConfig;
 export declare function parseRuleConfigFromMarkdown(content: string, fallbackName: string): RuleConfig;
 export declare function parseWorkflowConfigFromMarkdown(content: string, fallbackName: string): WorkflowConfig;

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

@@ -8,4 +8,14 @@
  * `destroy()` deletes the directory.
  */
 import type { DocumentFormat, DocumentReadResult, ReadOptions } from "./formats";
+/**
+ * Why an EPUB cannot be opened as the ZIP it is, or nothing when it can.
+ *
+ * A ZIP's index is at its end, so a file cut short while it was copied,
+ * downloaded or unpacked has its first entries and no index. lingo-reader
+ * does not survive that: its loader drops the ZIP reader's error and the
+ * promise it returned never settles, so the read would wait until the tool's
+ * limit with nothing to say.
+ */
+export declare function epubZipFault(data: Uint8Array): string | undefined;
 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

@@ -36,6 +36,31 @@ export interface ReadOptions {
      * recognition is off; resolves undefined for a page it did not read.
      */
     recognize?: (page: number, images: readonly PageImage[]) => Promise<RecognizedText | undefined>;
+    /** Stops the read at the next page or chapter; the read throws. */
+    signal?: AbortSignal;
+    /** Called as the read moves: once a page or chapter, and around recognition. */
+    onProgress?: (progress: ReadProgress) => void;
+    /**
+     * Everything the read left out, a line each: a picture that could not be
+     * taken out, and why. The reader appends; nothing is left out silently.
+     */
+    problems?: string[];
+    /**
+     * Lines for the log, not for the reader of the document: what the PDF
+     * decoder warned about, a picture that needed asking for twice.
+     */
+    onNote?: (line: string) => void;
+}
+/** Where a read is. */
+export interface ReadProgress {
+    unit: UnitName;
+    /** The page or chapter being read, from 1. */
+    at: number;
+    total: number;
+    /** Pictures taken out so far. */
+    pictures: number;
+    /** What it is doing there, when that is more than reading: "recognizing text". */
+    activity?: string;
 }
 /** A picture a scanned page is drawn from, as a PNG. */
 export interface PageImage {

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

@@ -57,6 +57,9 @@ export declare class OcrLanguageMissingError extends Error {
 export declare class TesseractReader {
     private readonly worker;
     readonly languages: readonly string[];
+    private readonly failure;
+    /** Why the worker is gone, once it is: nothing more is asked of it. */
+    private dead;
     private constructor();
     static open(languages: readonly string[], dataDir?: string): Promise<TesseractReader>;
     recognize(png: Uint8Array): Promise<{

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.
@@ -61,6 +72,11 @@ export interface PictureToDescribe {
  * Descriptions of a document's pictures, one request each, in order.
  * `undefined` for any the vision model could not describe.
  */
+/**
+ * One picture described, or the reason it was not. For a caller that has to
+ * say why: `describePictures` keeps the answers and drops the reasons.
+ */
+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`. */
@@ -52,4 +53,94 @@ 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, with their bytes; the markdown links them as `images/<file>`. */
+    images: {
+        file: string;
+        data: Uint8Array;
+        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[];
+}
+/**
+ * A document as the Library keeps a book: its text and its pictures.
+ * Nothing is written anywhere; the caller puts the pictures where the book
+ * is kept, and `describeBookPictures` has a vision model look at 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,35 @@
+/**
+ * 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[];
+}
+/** An ISBN printed in the first pages, when there is one. */
+export declare function findIsbn(markdown: string): string | undefined;
+/**
+ * What the files of one batch have to do with each other: a folder of ebooks
+ * often holds the same book twice, and the Library cannot say so about files
+ * it does not hold yet.
+ */
+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;
+}