@better-fs-tools/read 0.1.0 → 0.3.0

package/README.md

@@ -18,7 +18,7 @@ Most hosts also install one adapter package. Each adapter lists its own peers:
 | -------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
 | `@better-fs-tools/read`                | The core, the helpers, and the `./signature` and `./formats` subpaths    | `npm install @better-fs-tools/read`                                                             |
 | `@better-fs-tools/fs`                  | The `FileSystem` contract, `memoryFileSystem`, and the conformance suite | `npm install @better-fs-tools/fs`                                                               |
-| `@better-fs-tools/node`                | Local reads on Node 24 or Bun, and `createNodeReadTool()`                | `npm install @better-fs-tools/node @better-fs-tools/read`                                       |
+| `@better-fs-tools/node`                | The local filesystem on Node 24 or Bun, and `nodeDigest()`               | `npm install @better-fs-tools/node @better-fs-tools/read`                                       |
 | `@better-fs-tools/ai-sdk`              | An AI SDK 7 tool                                                         | `npm install @better-fs-tools/ai-sdk @better-fs-tools/read ai`                                  |
 | `@better-fs-tools/pi`                  | A Pi tool and a Pi extension                                             | `npm install @better-fs-tools/pi @better-fs-tools/read @earendil-works/pi-coding-agent typebox` |
 | `@better-fs-tools/cloudflare-shell`    | A filesystem over a Cloudflare Shell Workspace                           | `npm install @better-fs-tools/cloudflare-shell @better-fs-tools/read`                           |
@@ -29,14 +29,14 @@ All packages have the same version. Install matching versions.
 
 ## Quick start
 
-On Node or Bun, `createNodeReadTool()` gives a working local reader with no options:
+On Node or Bun, give `createReadTool()` a `nodeFileSystem()`:
 
 ```ts
-import { createNodeReadTool } from "@better-fs-tools/node";
-import { textOf } from "@better-fs-tools/read";
+import { nodeFileSystem } from "@better-fs-tools/node";
+import { createReadTool, textOf } from "@better-fs-tools/read";
 
 // Rooted at process.cwd(), with SHA-256 observations.
-const read = createNodeReadTool();
+const read = createReadTool({ fs: nodeFileSystem({ allowedRoots: [process.cwd()] }) });
 
 const result = await read({ path: "package.json", limit: 2 });
 console.log(result.status); // "ok"
@@ -47,8 +47,6 @@ console.log(textOf(result));
 // [read:continue] Output stopped at the line limit. Continue with {"path":"package.json","offset":3,"limit":2}.
 ```
 
-`createNodeReadTool()` uses `nodeFileSystem` rooted at `process.cwd()`, and `nodeDigest()` for content hashes. It passes every other option to `createReadTool()`.
-
 `createReadTool()` is the core. It needs a filesystem, and it works with any `FileSystem`:
 
 ```ts
@@ -107,7 +105,7 @@ read({ path, offset, limit }, ctx)
   │     ├─ on a miss: suggest  one bounded listing, names only
   │     └─ on a directory .... a directory converter lists it, else NOT_A_FILE
   │  authorize ............... host policy on the open file, before the core reads content
-  │  sample + classifiers .... text, image, PDF, notebook, binary, ...
+  │  sample + classifiers .... text, image, PDF, Office, binary, ...
   │  converters .............. other formats to text or media parts
   │  scan .................... lines, clamping, view bytes, token budget, scan limit
   │  verify .................. size check and change detection
@@ -118,38 +116,39 @@ read({ path, offset, limit }, ctx)
 ReadResult
 ```
 
-You cannot remove the input validation, the scan, the limits, the type check, or change detection. Every other step is a dependency that you can replace. [docs/architecture.md](docs/architecture.md) explains each stage.
+You cannot remove the input validation, the scan, the limits, the type check, or change detection. Every other step is an option that you can replace. [docs/architecture.md](docs/architecture.md) explains each stage.
 
 ## What you can change
 
-Pass dependencies to `createReadTool()`, `createNodeReadTool()`, or an adapter factory (`createAiSdkReadTool()`, `createPiReadTool()`). The adapter passes them to the core.
-
-| Dimension                                              | Dependency                  | Default                                                                                           |
-| ------------------------------------------------------ | --------------------------- | ------------------------------------------------------------------------------------------------- |
-| Tool name, parameters, range model, descriptions       | `signature` (adapters only) | `defaultReadSignature()`: `read` with `path`, `offset`, `limit`                                   |
-| Filesystem, allowed roots, deny roots, symlinks        | `fs`                        | Required. `createNodeReadTool()` uses `nodeFileSystem` over `process.cwd()`                       |
-| Path rewrites (`~`, `file://`, `@`, Unicode repair)    | `resolve`                   | `null` (the path is used as given)                                                                |
-| Names to suggest when a file is missing                | `suggest`                   | `defaultSuggest()`                                                                                |
-| Per-path policy, size ceiling, user approval           | `authorize`                 | `null` (allow)                                                                                    |
-| Binary and format detection                            | `classifiers`               | `defaultClassifiers()`                                                                            |
-| File conversion, images, directories                   | `converters`                | `[]`                                                                                              |
-| Line, byte, scan, conversion, and media limits         | `limits`                    | `defaultReadLimits`                                                                               |
-| Token limit                                            | `budget`                    | `null`                                                                                            |
-| Redaction, repeat-read guard, your own after-read code | `hooks`                     | `[]`                                                                                              |
-| Output text or content parts                           | `formatter`                 | `lineNumberFormatter()`                                                                           |
-| Note and message wording                               | `messages`                  | `defaultReadMessages`                                                                             |
-| Read records for later tools                           | `state`                     | `null`                                                                                            |
-| Content hashes and observations                        | `digest`                    | `null`. `createNodeReadTool()` and the Pi tool use `nodeDigest()`. `sha256Digest()` runs anywhere |
-| Timestamps                                             | `clock`                     | `() => new Date()`                                                                                |
-
-`limits` and `messages` merge over their defaults key by key. Every other dependency replaces its default. To add to a list, include the default yourself:
+Pass options to `createReadTool()`, `readToolDefinition()`, or an integration factory (`createAiSdkReadTool()`, `createPiReadTool()`, `createAgentCoreReadTool()`). Every integration takes the same options with the same defaults, and passes them to the core.
+
+| Dimension                                              | Option                      | Default                                                                                      |
+| ------------------------------------------------------ | --------------------------- | -------------------------------------------------------------------------------------------- |
+| Tool name, parameters, range model, descriptions       | `signature` (adapters only) | `defaultReadSignature()`: `read` with `path`, `offset`, `limit`                              |
+| Filesystem, allowed roots, deny roots, symlinks        | `fs`                        | Required. `nodeFileSystem()` from `@better-fs-tools/node` reads the local disk               |
+| Path rewrites (`~`, `file://`, `@`, Unicode repair)    | `resolve`                   | `null` (the path is used as given)                                                           |
+| Names to suggest when a file is missing                | `suggest`                   | `defaultSuggest()`                                                                           |
+| Per-path policy, size ceiling, user approval           | `authorize`                 | `null` (allow)                                                                               |
+| Binary and format detection                            | `classifiers`               | `defaultClassifiers()`                                                                       |
+| File conversion, images, directories                   | `converters`                | `[imageConverter()]`: an image becomes a media part. `[]` turns images off                   |
+| Line, byte, scan, conversion, and media limits         | `limits`                    | `defaultReadLimits`                                                                          |
+| Token limit                                            | `budget`                    | `null`                                                                                       |
+| Redaction, repeat-read guard, your own after-read code | `hooks`                     | `[]`                                                                                         |
+| Output text or content parts                           | `formatter`                 | `lineNumberFormatter()`                                                                      |
+| Note and message wording                               | `messages`                  | `defaultReadMessages`                                                                        |
+| Read records for later tools                           | `state`                     | `null`                                                                                       |
+| Content hashes and observations                        | `digest`                    | `sha256Digest()`, which runs anywhere. `nodeDigest()` is faster on Node. `null` turns it off |
+| Timestamps                                             | `clock`                     | `() => new Date()`                                                                           |
+
+`limits` and `messages` merge over their defaults key by key. Every other option replaces its default. To add to a list, include the default yourself:
 
 ```ts
-import { createNodeReadTool } from "@better-fs-tools/node";
-import { defaultClassifiers, extensionClassifier } from "@better-fs-tools/read";
+import { nodeFileSystem } from "@better-fs-tools/node";
+import { createReadTool, defaultClassifiers, extensionClassifier } from "@better-fs-tools/read";
 
-export const read = createNodeReadTool({
-  // A list dependency replaces the default. Include the default to add to it.
+export const read = createReadTool({
+  fs: nodeFileSystem({ allowedRoots: [process.cwd()] }),
+  // A list option replaces the default. Include the default to add to it.
   classifiers: [
     extensionClassifier({ unsupported: { ".parquet": { code: "BINARY" } } }),
     ...defaultClassifiers(),
@@ -160,7 +159,7 @@ export const read = createNodeReadTool({
 });
 ```
 
-`createReadTool()` checks the dependencies once, when you call it. An unknown key, an empty classifier list, a limit that is not a positive safe integer, or a message that is not a function throws `TypeError`.
+`createReadTool()` checks the options once, when you call it. An unknown key, an empty classifier list, a limit that is not a positive safe integer, or a message that is not a function throws `TypeError`.
 
 ## Tool signature and docs
 
@@ -172,7 +171,7 @@ The model sees a tool name, a description, a parameter schema, and parameter des
 - `param(name)` gives the host name of a canonical parameter, or `""` when the signature has none.
 - `fromInput(retry)` maps a canonical retry back to the model's names. Notes use it when they tell the model how to continue. Only the read signature has it.
 
-Two builders cover the common cases. Both take the shared `SignatureDocs` options: `name`, `description`, `describe`, and `names`. `describe` and `names` use the builder's own parameter names as keys.
+Two builders make the signature. `defaultReadSignature()` gives `read({ path, offset?, limit? })`. `lineRangeSignature()` gives `read({ path, start?, end? })`, with one-based and inclusive lines. Both take the shared `SignatureDocs` options: `name`, `description`, `describe`, and `names`. `describe` and `names` use the builder's own parameter names as keys.
 
 ```ts
 import { defaultReadSignature, lineRangeSignature } from "@better-fs-tools/read/signature";
@@ -196,7 +195,9 @@ export const lineRange = lineRangeSignature({
 });
 ```
 
-With `lineRangeSignature`, a truncated read tells the model to continue with `{"file_path":"src/a.ts","start_line":101,"end_line":200}`. The structured result stays canonical: `result.continuation.next` is still `{ path, offset, limit }`.
+With `renamed`, a truncated read tells the model to continue with `{"file_path":"src/a.ts","start":101,"max_lines":100}`. With `lineRange`, it says `{"file_path":"src/a.ts","start_line":101,"end_line":200}`. The structured result stays canonical: `result.continuation.next` is still `{ path, offset, limit }`.
+
+For another input shape, write your own `ReadSignature`. It needs `name`, `description`, `schema`, `toInput`, `param`, and `fromInput`.
 
 `createAiSdkReadTool()` and `createPiReadTool()` wire the retry wording for you with `readSignatureMessages(signature)`. If you call the core yourself behind a signature, pass `messages: readSignatureMessages(signature)`. Otherwise the retry text uses `path`, `offset`, and `limit`.
 
@@ -210,13 +211,19 @@ The tool reads one path for each call. For multi-file reads or globs, call the c
 
 ```ts
 import { homedir } from "node:os";
-import { createNodeReadTool, nodeFileSystem } from "@better-fs-tools/node";
-import { expandHome, pathResolvers, stripPrefixes, unicodeRepair } from "@better-fs-tools/read";
+import { nodeFileSystem } from "@better-fs-tools/node";
+import {
+  createReadTool,
+  expandHome,
+  pathResolvers,
+  stripPrefixes,
+  unicodeRepair,
+} from "@better-fs-tools/read";
 
 const cwd = process.cwd();
 const home = homedir();
 
-export const read = createNodeReadTool({
+export const read = createReadTool({
   fs: nodeFileSystem({ cwd, allowedRoots: [cwd, `${home}/.config/app`] }),
   resolve: pathResolvers(
     stripPrefixes(), // "file:///x" and "@src/x"
@@ -285,13 +292,20 @@ The filesystem owns the root policy: allowed roots, deny roots, and symlinks. `a
 What `open()` has fetched before `authorize` runs depends on the backend. `@better-fs-tools/cloudflare-shell` and `@better-fs-tools/just-bash` buffer the whole file inside `open()`, so those bytes have left the backend. `@better-fs-tools/cloudflare-computer` does not buffer: its `open()` starts a `readFile` stream, so the request reaches the backend, but it reads no chunk before `authorize`. `nodeFileSystem` streams, and `memoryFileSystem` already holds the bytes. In every case the core passes no byte to a classifier, a converter, or the model until `authorize` allows it. If a denied read must not reach the backend, refuse the path in the filesystem with a deny root, or leave it out of the allowed roots.
 
 ```ts
-import { createNodeReadTool } from "@better-fs-tools/node";
-import { askUser, readAuthorizers, denyPaths, sizeCeiling } from "@better-fs-tools/read";
+import { nodeFileSystem } from "@better-fs-tools/node";
+import {
+  askUser,
+  createReadTool,
+  denyPaths,
+  readAuthorizers,
+  sizeCeiling,
+} from "@better-fs-tools/read";
 
 // Your own prompt, for example a dialog in your UI.
 declare function confirmInUi(question: string): Promise<boolean>;
 
-export const read = createNodeReadTool({
+export const read = createReadTool({
+  fs: nodeFileSystem({ allowedRoots: [process.cwd()] }),
   authorize: readAuthorizers(
     denyPaths(["**/.env", "**/.env.*", "**/*.pem"]),
     sizeCeiling({ maxBytes: 256 * 1024, unrangedOnly: true }),
@@ -343,7 +357,9 @@ While a prompt waits, the file stays open. If the file changes during the wait,
 
 `classifiers` is an ordered list. Each classifier sees a bounded sample of the file (`limits.sampleBytes`). The first classifier with an opinion wins.
 
-The default chain detects images, PDFs, Office documents, notebooks, binary content, and text encodings. It returns these `unsupported` codes: `IMAGE`, `PDF`, `OFFICE_DOCUMENT`, `NOTEBOOK`, `BINARY`, and `UNKNOWN_ENCODING`. Each refusal has a note with code `unsupported-<code>`, for example `unsupported-pdf`.
+The default chain detects images, PDFs, Office documents, binary content, and text encodings. It returns these `unsupported` codes: `IMAGE`, `PDF`, `OFFICE_DOCUMENT`, `BINARY`, and `UNKNOWN_ENCODING`. Each refusal has a note with code `unsupported-<code>`, for example `unsupported-pdf`.
+
+A Jupyter notebook is JSON, so the default chain reads it as text. `notebookClassifier()` is exported but not in the chain. Put it first, as `classifiers: [notebookClassifier(), ...defaultClassifiers()]`, to refuse notebooks with code `NOTEBOOK`, or to convert them with `notebookConverter()`. The write tools use the same classifiers, so the same list makes them refuse a notebook too.
 
 To detect by extension, or to change a refusal message:
 
@@ -370,13 +386,16 @@ A classifier only decides what a file is. A converter changes the content.
 
 ## File conversion, images, and directories
 
-`converters` is a list. It runs after classification. The first file converter whose `accepts` returns `true` handles the file. The first directory converter handles directories. With no converters, text is read, other formats are `unsupported`, and a directory gives `NOT_A_FILE`.
+`converters` is a list. It runs after classification. The first file converter whose `accepts` returns `true` handles the file. The first directory converter handles directories. With no converters, text is read, other formats are `unsupported`, and a directory gives `NOT_A_FILE`. The core has no converters by default. The Pi and AI SDK hosts add `imageConverter()` when you pass no `converters`.
 
 ```ts
-import { createNodeReadTool } from "@better-fs-tools/node";
+import { nodeFileSystem } from "@better-fs-tools/node";
 import {
+  createReadTool,
+  defaultClassifiers,
   directoryListing,
   imageConverter,
+  notebookClassifier,
   notebookConverter,
   textConverter,
 } from "@better-fs-tools/read";
@@ -384,7 +403,11 @@ import {
 // Your own PDF extraction, for example a pdftotext process that reads stdin.
 declare function pdfToText(source: AsyncIterable<Uint8Array>): AsyncIterable<string>;
 
-export const read = createNodeReadTool({
+export const read = createReadTool({
+  fs: nodeFileSystem({ allowedRoots: [process.cwd()] }),
+  // The default chain reads a notebook as JSON text. notebookClassifier()
+  // marks it NOTEBOOK, so notebookConverter() can take it.
+  classifiers: [notebookClassifier(), ...defaultClassifiers()],
   converters: [
     imageConverter(),
     notebookConverter({ outputs: false }),
@@ -400,12 +423,12 @@ export const read = createNodeReadTool({
 });
 ```
 
-| Converter                                       | Result                                                                                                                                 |
-| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `imageConverter({ transform })`                 | Accepts code `IMAGE`. Gives a `media` result with the image as one content part. `transform` can resize it.                            |
-| `notebookConverter({ outputs })`                | Accepts code `NOTEBOOK`. Gives the cells as text. `outputs` defaults to `true`. Broken notebook JSON is refused as `INVALID_NOTEBOOK`. |
-| `textConverter({ id, accepts, mimeType, run })` | Builds a text converter from a stream function, for example `pdftotext`, `pandoc`, or `markitdown` in your host.                       |
-| `directoryListing({ trailingSlash, sort })`     | A directory becomes text, one entry for each line. `sort` is `"name"` (the default) or `"type-then-name"`.                             |
+| Converter                                       | Result                                                                                                                                                                     |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `imageConverter({ transform })`                 | Accepts code `IMAGE`. Gives a `media` result with the image as one content part. `transform` can resize it.                                                                |
+| `notebookConverter({ outputs })`                | Accepts code `NOTEBOOK`, so it needs `notebookClassifier()`. Gives the cells as text. `outputs` defaults to `true`. Broken notebook JSON is refused as `INVALID_NOTEBOOK`. |
+| `textConverter({ id, accepts, mimeType, run })` | Builds a text converter from a stream function, for example `pdftotext`, `pandoc`, or `markitdown` in your host.                                                           |
+| `directoryListing({ trailingSlash, sort })`     | A directory becomes text, one entry for each line. `sort` is `"name"` (the default) or `"type-then-name"`.                                                                 |
 
 A converter returns one of these outcomes:
 
@@ -428,7 +451,7 @@ Conversion runs again on each continuation read. Cache inside your converter if
 | Limit                 | Default | Meaning                                               |
 | --------------------- | ------- | ----------------------------------------------------- |
 | `maxLines`            | 2,000   | Lines in the view. Also the ceiling for `limit`.      |
-| `maxViewBytes`        | 128 KiB | UTF-8 bytes of source text in the view                |
+| `maxViewBytes`        | 50 KiB  | UTF-8 bytes of source text in the view                |
 | `maxCharsPerLine`     | 2,000   | Characters in one line before it is clamped           |
 | `maxScanBytes`        | 64 MiB  | Bytes scanned before totals and content identity stop |
 | `sampleBytes`         | 8 KiB   | Bytes given to classifiers. At most `maxScanBytes`.   |
@@ -446,10 +469,11 @@ Every tool has one parse helper with the same pattern: `parseReadInput`, `parseE
 For a token limit, set `budget`. The scanner stops at the last whole line that fits, and the result has a normal continuation. The truncation reason is `"budget"`.
 
 ```ts
-import { createNodeReadTool } from "@better-fs-tools/node";
-import { charsPerToken } from "@better-fs-tools/read";
+import { nodeFileSystem } from "@better-fs-tools/node";
+import { charsPerToken, createReadTool } from "@better-fs-tools/read";
 
-export const read = createNodeReadTool({
+export const read = createReadTool({
+  fs: nodeFileSystem({ allowedRoots: [process.cwd()] }),
   limits: { maxLines: 1_000, maxViewBytes: 64 * 1024 },
   budget: charsPerToken({ ratio: 4, max: 25_000 }),
 });
@@ -464,11 +488,12 @@ For a size ceiling that refuses a whole file, use the `sizeCeiling` authorizer.
 `hooks` is an ordered list of `afterRead` functions. They run after the scan and change detection, and before the result is recorded and formatted.
 
 ```ts
-import { createNodeReadTool } from "@better-fs-tools/node";
-import { memoryStore, redact, repeatReadGuard } from "@better-fs-tools/read";
+import { nodeFileSystem } from "@better-fs-tools/node";
+import { createReadTool, memoryStore, redact, repeatReadGuard } from "@better-fs-tools/read";
 
-// createNodeReadTool sets digest to nodeDigest(), which repeatReadGuard needs.
-export const read = createNodeReadTool({
+// repeatReadGuard needs a digest: the default sha256Digest() is one.
+export const read = createReadTool({
+  fs: nodeFileSystem({ allowedRoots: [process.cwd()] }),
   state: memoryStore(),
   hooks: [repeatReadGuard(), redact({ patterns: [/AKIA[0-9A-Z]{16}/g] })],
 });
@@ -506,7 +531,7 @@ export const agentsNote: ReadHook<unknown> = {
 };
 ```
 
-A repeat read that the guard empties is recorded as it was shown, with `wholeFileVisible: false`. Redaction works line by line, so a secret split across two lines is not matched.
+A repeat read that the guard empties has `observation.wholeFileVisible: false`. The stored record keeps the earlier read's `wholeFileVisible` and line ranges when the content is the same. Redaction works line by line, so a secret split across two lines is not matched.
 
 ## Output format
 
@@ -535,20 +560,22 @@ Its options:
 Helpers for common formats:
 
 ```ts
-import { createNodeReadTool } from "@better-fs-tools/node";
+import { nodeFileSystem } from "@better-fs-tools/node";
 import {
+  createReadTool,
   eofFooter,
   fileHashHeader,
   hashlineGutter,
   lineNumberFormatter,
 } from "@better-fs-tools/read";
 
-export const read = createNodeReadTool({
+export const read = createReadTool({
+  fs: nodeFileSystem({ allowedRoots: [process.cwd()] }),
   formatter: lineNumberFormatter({
     gutter: hashlineGutter({ width: 2 }), // "12:a3|text"
     header: fileHashHeader(), // "file-hash: sha256:..."
     footer: eofFooter((n) => `(End of file - total ${n} lines)`),
-    notes: (note) => (note.code === "weak-identity" ? null : note),
+    notes: (note) => (note.severity === "info" ? null : note),
   }),
 });
 ```
@@ -562,13 +589,17 @@ export const read = createNodeReadTool({
 Presets that copy the read output of other harnesses are in `@better-fs-tools/read/formats`: `opencodeFormat()`, `deepAgentsFormat()`, `hashlineFormat()`, and `hermesFormat()`. They take no options.
 
 ```ts
-import { createNodeReadTool } from "@better-fs-tools/node";
+import { nodeFileSystem } from "@better-fs-tools/node";
+import { createReadTool } from "@better-fs-tools/read";
 import { opencodeFormat } from "@better-fs-tools/read/formats";
 
-export const read = createNodeReadTool({ formatter: opencodeFormat() });
+export const read = createReadTool({
+  fs: nodeFileSystem({ allowedRoots: [process.cwd()] }),
+  formatter: opencodeFormat(),
+});
 ```
 
-A custom formatter implements `format(outcome, ctx)`. It is synchronous and pure over the outcome. `ctx` has the `digest`, the `limits`, the `call`, and a `mode`. The mode is `"model"` for model output and `"view"` for the body only, with no notes, header, or footer. The Pi adapter uses `"view"` for its truncation details. If your formatter returns parts in `"view"` mode, Pi leaves those details out. A formatter sees only the finished outcome. It cannot read the file. If the formatter throws or returns neither a string nor an array, the call still succeeds: the core adds an `extension-failed` warning and formats the result with `lineNumberFormatter()`.
+A custom formatter implements `format(outcome, ctx)`. It is synchronous and pure over the outcome. `ctx` has the `digest`, the `limits`, the `call`, and a `mode`. The mode is `"model"` for model output and `"view"` for the body only, with no notes, header, or footer. The Pi adapter uses `"view"` for its truncation details. If your formatter returns parts in `"view"` mode, Pi leaves those details out. A formatter sees only the finished outcome. It cannot read the file. If the formatter throws or returns neither a string nor an array, the call still succeeds: the core formats the result with `lineNumberFormatter()` and adds no note.
 
 ## Messages and notes
 
@@ -602,7 +633,7 @@ No default message names `offset` or `limit`. Every message that suggests a retr
 | `unsupported` | A classifier or converter refused the format. `code` is open, for example `PDF` or `TOO_LARGE`. |
 | `error`       | `error.code` is one of thirteen `ReadErrorCode` values.                                         |
 
-The error codes are `INVALID_INPUT`, `NOT_FOUND`, `NOT_A_FILE`, `DANGEROUS_PATH`, `OUTSIDE_ALLOWED_ROOTS`, `PERMISSION_DENIED`, `DENIED`, `TOO_LARGE`, `CHANGED_DURING_READ`, `ABORTED`, `UNSUPPORTED_BACKEND`, `EXTENSION_FAILED`, and `IO_ERROR`. `TOO_LARGE` is an `error` when a backend byte ceiling refuses the file, and an `unsupported` code when a converter or media limit stops it. `EXTENSION_FAILED` means that host code threw or broke a rule. Its note data names the dependency and the stage, for example `{ extension: "hooks", phase: "hooks", id: "redact" }`.
+The error codes are `INVALID_INPUT`, `NOT_FOUND`, `NOT_A_FILE`, `DANGEROUS_PATH`, `OUTSIDE_ALLOWED_ROOTS`, `PERMISSION_DENIED`, `DENIED`, `TOO_LARGE`, `CHANGED_DURING_READ`, `ABORTED`, `UNSUPPORTED_BACKEND`, `EXTENSION_FAILED`, and `IO_ERROR`. `TOO_LARGE` is an `error` when a backend byte ceiling refuses the file, and an `unsupported` code when a converter or media limit stops it. `EXTENSION_FAILED` means that host code threw or broke a rule. Its note data names the option and the stage, for example `{ extension: "hooks", phase: "hooks", id: "redact" }`.
 
 An `ok` result has structured lines, and an `error` result has its error:
 
@@ -669,36 +700,39 @@ await read({ path: "/a.txt" }, { host: session, callId: "call-1" });
 
 - `fs` can be a function of the call. It runs once for each read, before `resolve`. Use it to choose a backend for each call.
 - `sha256Digest()` is SHA-256 in plain JavaScript. It is synchronous and needs no Node module, so it works in a Cloudflare Worker. Its id and its values (`sha256:<hex>`) are the same as `nodeDigest()`, so records from either one match.
-- `state` needs a `digest`, because a record names the digest that made it. `createReadTool` throws `TypeError` for a `state` without a `digest`, and the dependency type (`StateNeedsDigest`) refuses it at compile time. `StateNeedsDigestOrDefault` is the same rule for a factory with its own default digest, such as the Node and Pi factories: leave `digest` out for the default, or pass `digest: null` with no `state`. The bundles (`createFsTools()` and the host bundles that wrap it) always have a digest, so they need neither.
+- `state` needs a `digest`, because a record names the digest that made it. `digest` defaults to `sha256Digest()`, so a `state` alone works. `createReadTool` throws `TypeError` for a `state` with `digest: null`, and the options type (`StateNeedsDigest`) refuses it at compile time.
 - `state` can be a function of the call. It runs at most once for each read, and only when the core needs the store. Return `null` for no store. A factory that throws gives `EXTENSION_FAILED`. A store whose `get` or `put` fails never fails the read.
-- The record key is `file.resolvedPath`. A read stores a `ReadRecord` with `schema: 2` and `origin: "read"`. It holds the backend `version`, the `digest` id, the content and view ids, and the read range. The write tools store records with `origin: "write"` and `request: null` after a commit. A record of another schema counts as absent.
+- The record key is `file.resolvedPath`. A read stores a `ReadRecord` with `schema: 2` and `origin: "read"`. It holds the backend `version`, the `digest` id, the content and view ids, the read range, and `seenLines`. `seenLines` joins the ranges that reads of the same content showed in full. When they run from line 1 to the last line, the record is `wholeFileVisible`, so reads in ranges count as a read of the whole file. The write tools store records with `origin: "write"` and `request: null` after a commit. A record of another schema counts as absent.
 - `result.file.version` is the backend's change token from `open()`, or `null`. It is kept when the backend has no identity capability.
 - `memoryStore()` from `@better-fs-tools/read` keeps records in memory, with a size cap and a TTL. Its `clock` option is the same `Clock` (`() => Date`) that the tools take, so one fake clock fits both. It sits on the root of the package that owns `ReadStateStore`, as `memoryLocks()` sits on the root of `@better-fs-tools/write`, which owns `LockManager`.
 - The helpers in this package are typed with `unknown` for the host, so they fit a tool with any host type. `askUser`, `imageConverter`, and `textConverter` can take your host type, as `askUser<Session>` does above.
 
 ## Security guarantees
 
-Your dependencies can narrow access. They cannot widen it.
+Your options can narrow access. They cannot widen it.
 
 - The filesystem is the only place that grants access. It checks roots, deny roots, the realpath, and the type in one `open()` call. `resolve` runs before it and `authorize` runs after it.
 - Each read opens at most one file. A resolver only changes the path that goes into that open.
 - `nodeFileSystem` opens files with `O_NOFOLLOW | O_NONBLOCK` and checks the type first. It refuses directories, FIFOs, sockets, and devices before any content read. It refuses `/dev`, `/proc`, and `/sys` before it touches the filesystem.
-- The core reads no content byte before `authorize` allows it, so no content reaches a classifier, a converter, or the model. `@better-fs-tools/cloudflare-shell` and `@better-fs-tools/just-bash` (a result with a `buffered-backend` note) have already fetched the whole file in `open()`. `@better-fs-tools/cloudflare-computer` has started a `readFile` stream but read no chunk. If a denied read must not reach the backend, use a deny root, or leave the path out of the filesystem's allowed roots.
+- The core reads no content byte before `authorize` allows it, so no content reaches a classifier, a converter, or the model. `@better-fs-tools/cloudflare-shell` and `@better-fs-tools/just-bash` have already fetched the whole file in `open()`. `@better-fs-tools/cloudflare-computer` has started a `readFile` stream but read no chunk. If a denied read must not reach the backend, use a deny root, or leave the path out of the filesystem's allowed roots.
 - The scan is bounded. Converters get a capped stream from the open file, never a path.
 - Change detection runs after the scan and after conversion. A file that changed returns `CHANGED_DURING_READ`.
 - A suggested name is never opened.
 - A hook cannot turn a failure into a success. A hook that changes the view marks the observation as partial.
 - A `DENIED` result does not show the file behind the path.
 
-## Host adapters
+## Integrations
+
+Each integration takes the options of `readToolDefinition()`: every core option, with the same default, plus `signature`. `fs` is required in every one. The integration owns abort forwarding and the mapping from `result.content` to the framework's content types.
 
-Each adapter owns the signature, abort forwarding, and the mapping from `result.content` to the framework's content types. The adapters accept every core dependency and pass it through.
+| Package                                                                                    | Factory                                                | Notes                                                                                                              |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| [`@better-fs-tools/ai-sdk`](https://www.npmjs.com/package/@better-fs-tools/ai-sdk)         | `createAiSdkReadTool(options)`                         | `execute` returns the whole `ReadResult`. `toModelOutput` maps media parts to AI SDK `file` parts.                 |
+| [`@better-fs-tools/pi`](https://www.npmjs.com/package/@better-fs-tools/pi)                 | `createPiReadTool(options)`                            | Adds the Pi prompt options. `piCwdFileSystem()` from `@better-fs-tools/pi/node` roots each call at Pi's `ctx.cwd`. |
+| [`@better-fs-tools/pi`](https://www.npmjs.com/package/@better-fs-tools/pi)                 | `createAgentCoreReadTool(options)` from `./agent-core` | An `AgentTool` for `@earendil-works/pi-agent-core`.                                                                |
+| [`@better-fs-tools/pi-durable`](https://www.npmjs.com/package/@better-fs-tools/pi-durable) | `createDurableFsTools(options)`                        | A bundle only: the tools register inside a pi-durable extension.                                                   |
 
-| Package                                                                            | Factory                        | Notes                                                                                                                                                                 |
-| ---------------------------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`@better-fs-tools/ai-sdk`](https://www.npmjs.com/package/@better-fs-tools/ai-sdk) | `createAiSdkReadTool(options)` | `execute` returns the whole `ReadResult`. `toModelOutput` maps media parts to AI SDK `file` parts. You pass `fs`.                                                     |
-| [`@better-fs-tools/pi`](https://www.npmjs.com/package/@better-fs-tools/pi)         | `createPiReadTool(options)`    | Each call is confined to Pi's `ctx.cwd`. `fs`, `cwd`, and `allowedRoots` are refused. The `pi.extensions` entry registers `read`, `edit`, `write`, and `apply_patch`. |
-| [`@better-fs-tools/node`](https://www.npmjs.com/package/@better-fs-tools/node)     | `createNodeReadTool(options?)` | The core with Node defaults, for your own tool.                                                                                                                       |
+For your own framework, call `readToolDefinition()` from `./signature`. It returns the name, description, and JSON Schema to declare, a `validate` for model input, and an `execute` that maps model input and runs the tool.
 
 Cloudflare Agents hosts use `@better-fs-tools/ai-sdk` with `cloudflareShellFileSystem` from [`@better-fs-tools/cloudflare-shell`](https://www.npmjs.com/package/@better-fs-tools/cloudflare-shell). [`@better-fs-tools/cloudflare-computer`](https://www.npmjs.com/package/@better-fs-tools/cloudflare-computer) and [`@better-fs-tools/just-bash`](https://www.npmjs.com/package/@better-fs-tools/just-bash) are filesystems. Use them with `createReadTool()` or with an adapter.
 
@@ -723,7 +757,8 @@ This Pi host sets most dimensions. You will usually need only a few of these opt
 ```ts
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { createPiReadTool } from "@better-fs-tools/pi";
-import { lineRangeSignature } from "@better-fs-tools/read/signature";
+import { piCwdFileSystem } from "@better-fs-tools/pi/node";
+import { defaultReadSignature } from "@better-fs-tools/read/signature";
 import {
   askUser,
   denyPaths,
@@ -744,9 +779,9 @@ import {
 const stores = new Map<string, ReturnType<typeof memoryStore>>();
 
 export const read = createPiReadTool({
-  signature: lineRangeSignature({
-    name: "read",
-    names: { path: "file_path", start: "start_line", end: "end_line" },
+  fs: piCwdFileSystem(),
+  signature: defaultReadSignature({
+    names: { path: "file_path", offset: "start_line", limit: "max_lines" },
   }),
   resolve: pathResolvers(stripPrefixes(), unicodeRepair({ note: false })),
   authorize: readAuthorizers(

package/dist/classifiers/index.d.ts

@@ -8,8 +8,9 @@ export { officeClassifier } from "./office.ts";
 export { pdfClassifier } from "./pdf.ts";
 export { utf8Classifier } from "./utf8.ts";
 /**
- * The built-in chain in evaluation order: image, pdf, office, notebook,
- * binary, utf8. The first classifier with an opinion wins. utf8Classifier
- * runs last and is the one that returns text.
+ * The built-in chain in evaluation order: image, pdf, office, binary, utf8.
+ * The first classifier with an opinion wins. utf8Classifier runs last and is
+ * the one that returns text. A notebook is JSON text here. Put
+ * notebookClassifier() before the chain to refuse or convert notebooks.
  */
 export declare function defaultClassifiers(options?: DefaultClassifierOptions): Classifier[];

package/dist/classifiers/index.js

@@ -1,6 +1,5 @@
 import { binaryClassifier } from "./binary.js";
 import { imageClassifier } from "./image.js";
-import { notebookClassifier } from "./notebook.js";
 import { officeClassifier } from "./office.js";
 import { pdfClassifier } from "./pdf.js";
 import { utf8Classifier } from "./utf8.js";
@@ -12,9 +11,10 @@ export { officeClassifier } from "./office.js";
 export { pdfClassifier } from "./pdf.js";
 export { utf8Classifier } from "./utf8.js";
 /**
- * The built-in chain in evaluation order: image, pdf, office, notebook,
- * binary, utf8. The first classifier with an opinion wins. utf8Classifier
- * runs last and is the one that returns text.
+ * The built-in chain in evaluation order: image, pdf, office, binary, utf8.
+ * The first classifier with an opinion wins. utf8Classifier runs last and is
+ * the one that returns text. A notebook is JSON text here. Put
+ * notebookClassifier() before the chain to refuse or convert notebooks.
  */
 export function defaultClassifiers(options = {}) {
     const notes = options.notes ?? {};
@@ -22,7 +22,6 @@ export function defaultClassifiers(options = {}) {
         imageClassifier(withNote(notes.IMAGE)),
         pdfClassifier(withNote(notes.PDF)),
         officeClassifier(withNote(notes.OFFICE_DOCUMENT)),
-        notebookClassifier(withNote(notes.NOTEBOOK)),
         binaryClassifier(withNote(notes.BINARY)),
         utf8Classifier(withNote(notes.UNKNOWN_ENCODING)),
     ];

package/dist/contract/base.d.ts

@@ -107,15 +107,43 @@ export interface ToolSignature<TInput, TParam extends string = string> {
      * that names it.
      */
     param(name: TParam): string;
-    /** Set on freeform signatures. Hosts that support grammar tools use it. */
+    /** A Lark grammar for hosts with grammar tools. freeformPatchSignature() sets CODEX_PATCH_GRAMMAR. */
     readonly grammar?: {
         readonly lark: string;
     };
 }
 /**
- * The options every signature preset takes. `TParam` is the preset's own
+ * A core tool bound to a signature: what a framework adapter needs to declare
+ * the tool and run it. The xxxToolDefinition() helpers in each `./signature`
+ * subpath build one, and every integration uses them.
+ */
+export interface ToolDefinition<TInput, TResult, THost = undefined, TParam extends string = string> {
+    /** The tool name the model sees: `signature.name`. */
+    readonly name: string;
+    readonly description: string;
+    /** Plain JSON Schema of the model input: `signature.schema`. */
+    readonly inputSchema: JsonObject;
+    /** Set when the signature has a grammar. */
+    readonly grammar?: {
+        readonly lark: string;
+    };
+    readonly signature: ToolSignature<TInput, TParam>;
+    /**
+     * Checks model input with the signature and with the core input check at the
+     * tool's limits, and returns the canonical input. Throws TypeError that names
+     * the signature's parameters.
+     */
+    validate(modelInput: unknown): TInput;
+    /**
+     * Maps model input with `signature.toInput` and runs the core tool. Bad input
+     * rejects with TypeError. A tool error is a result, not a rejection.
+     */
+    execute(modelInput: unknown, ctx: ToolCallContext<THost>): Promise<TResult>;
+}
+/**
+ * The options every default signature takes. `TParam` is the signature's own
  * parameter names. `names` gives a parameter another name in the schema, and
- * `describe` replaces its description. Both are keyed by the preset's names.
+ * `describe` replaces its description. Both are keyed by the signature's names.
  */
 export interface SignatureDocs<TParam extends string> {
     /** The tool name. */

package/dist/contract/deps.d.ts

@@ -20,7 +20,10 @@ export interface ReadDependencies<THost = undefined> {
     readonly suggest: Suggest<THost> | null;
     /** Host access policy for the opened file ("read") and before every listing ("list"). null allows everything. */
     readonly authorize: ReadAuthorizer<THost> | null;
-    /** File converters in order: the first that accepts runs. The first directory converter lists directories. */
+    /**
+     * File converters in order: the first that accepts runs. The first directory
+     * converter lists directories. Default [imageConverter()]. [] turns images off.
+     */
     readonly converters: readonly Converter<THost>[];
     /** Stops the view early, at a line boundary, when the next line would pass `max`. null has no budget. */
     readonly budget: ViewBudget | null;
@@ -28,32 +31,24 @@ export interface ReadDependencies<THost = undefined> {
     readonly hooks: readonly ReadHook<THost>[];
     /** A store, or a factory called at most once for each read, and only when needed. Needs `digest`. */
     readonly state: ReadStateStore | ((call: ReadContext<THost>) => ReadStateStore | null) | null;
+    /** Names content for the read state and the observations. Default sha256Digest(). null turns both off. */
     readonly digest: Digest | null;
     readonly clock: Clock;
     readonly formatter: ReadFormatter<THost>;
 }
 /**
  * `state` needs a `digest`, because a stored record names the digest that made
- * it. `state` without `digest` does not type-check, and throws TypeError at run
- * time.
+ * it. Leave `digest` out to get sha256Digest(). `digest: null` turns it off,
+ * and then `state` must be left out or null. A `state` with `digest: null`
+ * does not type-check, and throws TypeError at run time.
  */
 export type StateNeedsDigest = {
     readonly state?: null;
-} | {
-    readonly digest: Digest;
-};
-/**
- * The same pairing for a factory with its own default digest, such as the
- * Node and Pi factories. Leave `digest` out to get the default. `digest: null`
- * turns it off, and then `state` must be left out or null.
- */
-export type StateNeedsDigestOrDefault = {
-    readonly state?: null;
     readonly digest: null;
 } | {
     readonly digest?: Digest;
 };
-export type ReadToolDeps<THost = undefined> = {
+export type ReadToolOptions<THost = undefined> = {
     readonly fs: ReadDependencies<THost>["fs"];
     readonly limits?: Partial<ReadLimits>;
     readonly messages?: Partial<ReadMessageCatalog>;

package/dist/contract/limits.d.ts

@@ -1,7 +1,7 @@
 export interface ReadLimits {
     /** Lines in the view. Default 2_000. */
     readonly maxLines: number;
-    /** UTF-8 bytes of source text in the view. Default 128 KiB. */
+    /** UTF-8 bytes of source text in the view. Default 50 KiB (51 200). */
     readonly maxViewBytes: number;
     /** Characters per line before clamping. Default 2_000. */
     readonly maxCharsPerLine: number;

package/dist/contract/messages.d.ts

@@ -107,14 +107,4 @@ export interface ReadMessageCatalog extends ToolMessages {
     viewModified(c: {
         hook: string;
     }): string;
-    weakIdentity(c: {
-        backend: string;
-    }): string;
-    bufferedBackend(c: {
-        backend: string;
-    }): string;
-    /** The formatter threw or returned neither a string nor an array. */
-    formatterFailed(c: {
-        formatter: string;
-    }): string;
 }