@better-fs-tools/read 0.2.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
@@ -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 }),
@@ -375,8 +389,9 @@ A classifier only decides what a file is. A converter changes the content.
 `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,
@@ -388,7 +403,8 @@ 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()],
@@ -453,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 }),
 });
@@ -471,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] })],
 });
@@ -513,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
 
@@ -542,15 +560,17 @@ 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:..."
@@ -569,10 +589,14 @@ 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 formats the result with `lineNumberFormatter()` and adds no note.
@@ -609,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:
 
@@ -676,16 +700,16 @@ 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.
@@ -697,15 +721,18 @@ Your dependencies can narrow access. They cannot widen it.
 - 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`, and `write`. |
-| [`@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.
 
@@ -730,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,
@@ -751,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/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/result.d.ts

@@ -150,4 +150,14 @@ export interface ReadObservation {
     readonly observedAt: string;
     /** True when offset is 1, nothing was truncated or clamped, and no hook edited the view. */
     readonly wholeFileVisible: boolean;
+    /**
+     * The source lines that the view showed in full. null when the view showed no
+     * line, clamped a line, came from a converter, or was edited by a hook.
+     */
+    readonly visibleLines: ReadLineRange | null;
+}
+/** An inclusive range of 1-based source line numbers. */
+export interface ReadLineRange {
+    readonly start: number;
+    readonly end: number;
 }

package/dist/contract/state.d.ts

@@ -1,3 +1,4 @@
+import type { ReadLineRange } from "./result.ts";
 /**
  * Session state for read observations. A store is a cache: a failed store call
  * never fails a read.
@@ -26,7 +27,16 @@ export interface ReadRecord {
     /** For a write record: equal to contentId. */
     readonly viewId: string;
     readonly observedAt: string;
+    /**
+     * True when one read showed the whole file, or when the reads of this
+     * contentId together showed every line.
+     */
     readonly wholeFileVisible: boolean;
+    /**
+     * The lines of this contentId that reads showed in full, sorted and joined.
+     * Empty for a write record.
+     */
+    readonly seenLines: readonly ReadLineRange[];
     readonly totalsExact: boolean;
     /** The read range. null for a write record. */
     readonly request: {

package/dist/core/convert.js

@@ -126,6 +126,7 @@ function mediaOutcome(input, classification, parts, notes, source) {
             observedAt: deps.clock().toISOString(),
             // Media is not source text, so it cannot back a text edit.
             wholeFileVisible: false,
+            visibleLines: null,
         }),
         notes,
     };

package/dist/core/create-read-tool.d.ts

@@ -1,7 +1,7 @@
 import type { ReadTool } from "../contract/context.ts";
-import type { ReadToolDeps, StateNeedsDigest } from "../contract/deps.ts";
+import type { ReadToolOptions, StateNeedsDigest } from "../contract/deps.ts";
 /**
- * Creates the read tool. Throws TypeError on an unknown or malformed dependency,
+ * Creates the read tool. Throws TypeError on an unknown or malformed option,
  * a missing `fs`, an empty `classifiers` list, or a `state` without a `digest`.
  */
-export declare function createReadTool<THost = undefined>(deps: ReadToolDeps<THost> & StateNeedsDigest): ReadTool<THost>;
+export declare function createReadTool<THost = undefined>(options: ReadToolOptions<THost> & StateNeedsDigest): ReadTool<THost>;

package/dist/core/create-read-tool.js

@@ -2,11 +2,11 @@ import { resolveDependencies } from "./deps.js";
 import { isRecord } from "./input.js";
 import { runRead } from "./pipeline.js";
 /**
- * Creates the read tool. Throws TypeError on an unknown or malformed dependency,
+ * Creates the read tool. Throws TypeError on an unknown or malformed option,
  * a missing `fs`, an empty `classifiers` list, or a `state` without a `digest`.
  */
-export function createReadTool(deps) {
-    const resolved = resolveDependencies(deps);
+export function createReadTool(options) {
+    const resolved = resolveDependencies(options);
     const read = async (input, ctx) => {
         if (ctx !== undefined && !isRecord(ctx)) {
             throw new TypeError("read context must be an object");

package/dist/core/deps.d.ts

@@ -1,6 +1,6 @@
 import type { FileSystem } from "@better-fs-tools/fs";
-import type { ReadDependencies, ReadToolDeps } from "../contract/deps.ts";
+import type { ReadDependencies, ReadToolOptions } from "../contract/deps.ts";
 import type { ReadStateStore } from "../contract/state.ts";
-export declare function resolveDependencies<THost>(deps: ReadToolDeps<THost>): ReadDependencies<THost>;
+export declare function resolveDependencies<THost>(deps: ReadToolOptions<THost>): ReadDependencies<THost>;
 export declare function isFileSystem(value: unknown): value is FileSystem;
 export declare function isStateStore(value: unknown): value is ReadStateStore;

package/dist/core/deps.js

@@ -1,10 +1,12 @@
 import { defaultClassifiers } from "../classifiers/index.js";
+import { imageConverter } from "../converters/index.js";
+import { sha256Digest } from "../digest/sha256.js";
 import { lineNumberFormatter } from "../formatters/index.js";
 import { defaultSuggest } from "../suggest/index.js";
 import { isRecord } from "./input.js";
 import { resolveReadLimits } from "./limits.js";
 import { resolveReadMessages } from "./messages.js";
-const KNOWN_DEPENDENCY_KEYS = new Set([
+const KNOWN_OPTION_KEYS = new Set([
     "fs",
     "limits",
     "messages",
@@ -22,10 +24,10 @@ const KNOWN_DEPENDENCY_KEYS = new Set([
 ]);
 export function resolveDependencies(deps) {
     if (!isRecord(deps))
-        throw new TypeError("read tool dependencies must be an object");
+        throw new TypeError("read tool options must be an object");
     for (const key of Object.keys(deps)) {
-        if (!KNOWN_DEPENDENCY_KEYS.has(key))
-            throw new TypeError(`Unknown read tool dependency: ${key}`);
+        if (!KNOWN_OPTION_KEYS.has(key))
+            throw new TypeError(`Unknown read tool option: ${key}`);
     }
     const { fs } = deps;
     if (typeof fs !== "function" && !isFileSystem(fs)) {
@@ -51,7 +53,7 @@ export function resolveDependencies(deps) {
     if (authorize !== null && (!isRecord(authorize) || typeof authorize.authorize !== "function")) {
         throw new TypeError("authorize must be an authorizer or null");
     }
-    const converters = deps.converters === undefined ? [] : deps.converters;
+    const converters = deps.converters === undefined ? [imageConverter()] : deps.converters;
     if (!Array.isArray(converters) || !converters.every(isConverter)) {
         throw new TypeError("converters must be an array of file and directory converters");
     }
@@ -70,7 +72,10 @@ export function resolveDependencies(deps) {
     if (state !== null && typeof state !== "function" && !isStateStore(state)) {
         throw new TypeError("state must be a store, a function that returns one, or null");
     }
-    const digest = deps.digest ?? null;
+    const digest = deps.digest === undefined ? sha256Digest() : deps.digest;
+    if (digest !== null && !isDigest(digest)) {
+        throw new TypeError("digest must have an id, create, and hash, or be null");
+    }
     if (state !== null && digest === null) {
         throw new TypeError("state needs a digest: records name the digest that made them");
     }
@@ -113,6 +118,12 @@ function isViewBudget(value) {
 function isHook(value) {
     return isRecord(value) && typeof value.id === "string" && typeof value.afterRead === "function";
 }
+function isDigest(value) {
+    return (isRecord(value) &&
+        typeof value.id === "string" &&
+        typeof value.create === "function" &&
+        typeof value.hash === "function");
+}
 export function isStateStore(value) {
     return (isRecord(value) &&
         typeof value.get === "function" &&

package/dist/core/observation.d.ts

@@ -1,11 +1,12 @@
 import type { Digest } from "../contract/digest.ts";
-import type { ContentPart, FileInfo, ReadObservation } from "../contract/result.ts";
+import type { ContentPart, FileInfo, ReadLineRange, ReadObservation } from "../contract/result.ts";
 export interface ObservationInput {
     readonly file: FileInfo;
     readonly contentId: string | null;
     readonly view: string | readonly ContentPart[];
     readonly observedAt: string;
     readonly wholeFileVisible: boolean;
+    readonly visibleLines: ReadLineRange | null;
 }
 export declare function buildObservation(digest: Digest | null, input: ObservationInput): ReadObservation | null;
 export declare function withEditedView(digest: Digest, observation: ReadObservation, view: string | readonly ContentPart[]): ReadObservation;

package/dist/core/observation.js

@@ -16,6 +16,7 @@ export function buildObservation(digest, input) {
         viewId,
         observedAt: input.observedAt,
         wholeFileVisible: input.wholeFileVisible,
+        visibleLines: input.visibleLines,
     };
 }
 export function withEditedView(digest, observation, view) {
@@ -25,6 +26,7 @@ export function withEditedView(digest, observation, view) {
         id: observationId(digest, observation.statId, observation.contentId, viewId),
         viewId,
         wholeFileVisible: false,
+        visibleLines: null,
     };
 }
 function viewIdOf(digest, view) {

package/dist/core/record.js

@@ -1,3 +1,10 @@
+import { isRecord } from "./input.js";
+import { coversLines, joinLineRanges, storedLineRanges } from "./seen-lines.js";
+/**
+ * The record step of each read waits for the step before it on the same store
+ * and key, so parallel ranged reads of one file all join the stored ranges.
+ */
+const pending = new WeakMap();
 export async function recordOutcome(scope, outcome) {
     if (outcome.status !== "ok" && outcome.status !== "media")
         return;
@@ -8,16 +15,62 @@ export async function recordOutcome(scope, outcome) {
     const store = scope.stateStore();
     if (store === null)
         return;
+    const key = outcome.file.resolvedPath;
+    await inTurn(store, key, async () => {
+        try {
+            const previous = await sameContentRecord(store, key, digest.id, observation.contentId);
+            await store.put(key, toRecord(outcome, observation, digest.id, previous));
+        }
+        catch {
+            // Session state is a cache: a failing store never fails the read.
+        }
+    });
+}
+async function inTurn(store, key, step) {
+    let keys = pending.get(store);
+    if (keys === undefined) {
+        keys = new Map();
+        pending.set(store, keys);
+    }
+    const before = keys.get(key) ?? Promise.resolve();
+    const current = before.then(step);
+    keys.set(key, current);
+    try {
+        await current;
+    }
+    finally {
+        if (keys.get(key) === current)
+            keys.delete(key);
+    }
+}
+/** The stored record, when it describes the same bytes with the same digest. */
+async function sameContentRecord(store, key, digest, contentId) {
+    if (contentId === null)
+        return null;
+    let record;
     try {
-        await store.put(outcome.file.resolvedPath, toRecord(outcome, observation, digest.id));
+        record = await store.get(key);
     }
     catch {
-        // Session state is a cache: a failing store never fails the read.
+        return null;
     }
+    if (!isRecord(record) || record.schema !== 2 || record.digest !== digest)
+        return null;
+    return record.contentId === contentId ? record : null;
 }
 /** Copies fields one by one so nothing from the host `call` reaches the store. */
-function toRecord(outcome, observation, digest) {
+function toRecord(outcome, observation, digest, previous) {
     const { file, request } = outcome;
+    const seenLines = joinLineRanges([
+        ...storedLineRanges(previous?.seenLines),
+        ...(observation.visibleLines === null ? [] : [observation.visibleLines]),
+    ]);
+    // Media is only returned from a whole source, so its source totals are exact.
+    const totalsExact = outcome.status === "ok" ? outcome.totals.exact : true;
+    const totalLines = outcome.status === "ok" ? outcome.totals.lines : null;
+    const wholeFileVisible = observation.wholeFileVisible ||
+        previous?.wholeFileVisible === true ||
+        (totalsExact && totalLines !== null && coversLines(seenLines, totalLines));
     return {
         schema: 2,
         origin: "read",
@@ -29,9 +82,9 @@ function toRecord(outcome, observation, digest) {
         contentId: observation.contentId,
         viewId: observation.viewId,
         observedAt: observation.observedAt,
-        wholeFileVisible: observation.wholeFileVisible,
-        // Media is only returned from a whole source, so its source totals are exact.
-        totalsExact: outcome.status === "ok" ? outcome.totals.exact : true,
+        wholeFileVisible,
+        seenLines,
+        totalsExact,
         request: { offset: request.offset, limit: request.limit },
     };
 }

package/dist/core/seen-lines.d.ts

@@ -0,0 +1,7 @@
+import type { ReadLineRange } from "../contract/result.ts";
+/** Sorts the ranges and joins ranges that overlap or touch. */
+export declare function joinLineRanges(ranges: readonly ReadLineRange[]): ReadLineRange[];
+/** True when joined ranges show every line from 1 to totalLines. */
+export declare function coversLines(joined: readonly ReadLineRange[], totalLines: number): boolean;
+/** Reads ranges from a stored record. Anything malformed counts as no range. */
+export declare function storedLineRanges(value: unknown): ReadLineRange[];

package/dist/core/seen-lines.js

@@ -0,0 +1,39 @@
+/** Sorts the ranges and joins ranges that overlap or touch. */
+export function joinLineRanges(ranges) {
+    const sorted = [...ranges].sort((a, b) => a.start - b.start || a.end - b.end);
+    const joined = [];
+    for (const range of sorted) {
+        const last = joined.at(-1);
+        if (last !== undefined && range.start <= last.end + 1) {
+            joined[joined.length - 1] = { start: last.start, end: Math.max(last.end, range.end) };
+        }
+        else {
+            joined.push({ start: range.start, end: range.end });
+        }
+    }
+    return joined;
+}
+/** True when joined ranges show every line from 1 to totalLines. */
+export function coversLines(joined, totalLines) {
+    if (totalLines === 0)
+        return true;
+    const first = joined[0];
+    return first !== undefined && first.start <= 1 && first.end >= totalLines;
+}
+/** Reads ranges from a stored record. Anything malformed counts as no range. */
+export function storedLineRanges(value) {
+    if (!Array.isArray(value))
+        return [];
+    const ranges = [];
+    for (const item of value) {
+        if (item === null || typeof item !== "object")
+            return [];
+        const { start, end } = item;
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end))
+            return [];
+        if (start < 1 || end < start)
+            return [];
+        ranges.push({ start: start, end: end });
+    }
+    return ranges;
+}

package/dist/core/text-outcome.js

@@ -19,6 +19,11 @@ export function textOutcome(input) {
         !continuationAvailable &&
         !scanCapped &&
         scanner.clampedLines.length === 0;
+    const endLine = scanner.lines.length === 0 ? request.offset - 1 : request.offset + scanner.lines.length - 1;
+    // Converted lines are not source lines, so they cannot join a range of the source.
+    const visibleLines = conversion === null && scanner.lines.length > 0 && scanner.clampedLines.length === 0
+        ? { start: request.offset, end: endLine }
+        : null;
     return {
         tool: "read",
         status: "ok",
@@ -29,7 +34,7 @@ export function textOutcome(input) {
         view: {
             lines: scanner.lines,
             startLine: request.offset,
-            endLine: scanner.lines.length === 0 ? request.offset - 1 : request.offset + scanner.lines.length - 1,
+            endLine,
             bytes: scanner.viewBytes,
             partial: request.offset !== 1 || continuationAvailable || reasons.length > 0,
         },
@@ -54,6 +59,7 @@ export function textOutcome(input) {
                 view: scanner.viewText,
                 observedAt: deps.clock().toISOString(),
                 wholeFileVisible,
+                visibleLines,
             }),
         notes: [
             ...buildViewNotes({

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export type { Classification, ClassificationSample, Classifier } from "./contract/classify.ts";
 export type { BuiltInUnsupportedCode, DefaultClassifierOptions, NoteContext, NoteOverride, TextClassification, UnsupportedClassification, } from "./contract/classify.ts";
-export type { AccessDecision, AccessTarget, Note, SignatureDocs, ToolAuthorizer, ToolCallContext, ToolError, ToolHookContext, ToolMessages, ToolName, ToolResolveContext, ToolSignature, } from "./contract/base.ts";
+export type { AccessDecision, AccessTarget, Note, SignatureDocs, ToolAuthorizer, ToolCallContext, ToolDefinition, ToolError, ToolHookContext, ToolMessages, ToolName, ToolResolveContext, ToolSignature, } from "./contract/base.ts";
 export type { ReadContext, ReadTool } from "./contract/context.ts";
-export type { ReadDependencies, ReadToolDeps, StateNeedsDigest, StateNeedsDigestOrDefault, } from "./contract/deps.ts";
+export type { ReadToolOptions, StateNeedsDigest } from "./contract/deps.ts";
 export type { Clock, Digest, DigestStream } from "./contract/digest.ts";
 export type { AfterReadContext, Converter, ConverterMatch, ConvertOutcome, DirectoryConverter, DirectoryConvertInput, FileConverter, FileConvertInput, PathResolver, ReadAuthorizeDecision, ReadAuthorizer, ReadAuthorizeTarget, ReadHook, ReadHookContext, ReadResolveContext, ResolveOutcome, Suggest, SuggestContext, ViewBudget, } from "./contract/extensions.ts";
 export type { ReadFormatContext, ReadFormatter } from "./contract/format.ts";
@@ -10,7 +10,7 @@ export type { ReadInput, ReadRequest } from "./contract/input.ts";
 export type { JsonObject, JsonValue } from "./contract/json.ts";
 export type { ReadLimits } from "./contract/limits.ts";
 export type { ReadMessageCatalog, ReadPhase } from "./contract/messages.ts";
-export type { ClassificationInfo, Confidence, ContentPart, ConversionInfo, FileInfo, MediaPart, ReadContinuation, ReadError, ReadErrorCode, ReadFailure, ReadLine, ReadMedia, ReadNote, ReadObservation, ReadOk, ReadReport, ReadResult, ReadTotals, ReadTruncation, ReadUnsupported, ReadView, TextPart, TruncationReason, } from "./contract/result.ts";
+export type { ClassificationInfo, Confidence, ContentPart, ConversionInfo, FileInfo, MediaPart, ReadContinuation, ReadError, ReadErrorCode, ReadFailure, ReadLine, ReadLineRange, ReadMedia, ReadNote, ReadObservation, ReadOk, ReadReport, ReadResult, ReadTotals, ReadTruncation, ReadUnsupported, ReadView, TextPart, TruncationReason, } from "./contract/result.ts";
 export type { ReadRecord, ReadStateStore } from "./contract/state.ts";
 export { createReadTool } from "./core/create-read-tool.ts";
 export { parseReadInput } from "./core/input.ts";

package/dist/signature/definition.d.ts

@@ -0,0 +1,30 @@
+import type { ToolDefinition } from "../contract/base.ts";
+import type { ReadToolOptions, StateNeedsDigest } from "../contract/deps.ts";
+import type { Digest } from "../contract/digest.ts";
+import type { ReadFormatter } from "../contract/format.ts";
+import type { ReadInput } from "../contract/input.ts";
+import type { ReadLimits } from "../contract/limits.ts";
+import type { ReadResult } from "../contract/result.ts";
+import type { ReadParam, ReadSignature } from "./contract.ts";
+/** The read tool's options, plus the signature the model sees. */
+export type ReadToolDefinitionOptions<THost = undefined> = ReadToolOptions<THost> & StateNeedsDigest & {
+    /** Default defaultReadSignature(). */
+    readonly signature?: ReadSignature;
+};
+/**
+ * The read tool bound to its signature. `limits`, `formatter`, and `digest`
+ * are the ones the tool uses, for a host that formats the result again.
+ */
+export interface ReadToolDefinition<THost = undefined> extends ToolDefinition<ReadInput, ReadResult, THost, ReadParam> {
+    readonly signature: ReadSignature;
+    readonly limits: Readonly<ReadLimits>;
+    readonly formatter: ReadFormatter<THost>;
+    readonly digest: Digest | null;
+}
+/**
+ * Creates the read tool and binds it to a signature, default
+ * defaultReadSignature(). The signature's retry text goes under
+ * `options.messages`, so a host message still wins. Throws TypeError where
+ * createReadTool() does.
+ */
+export declare function readToolDefinition<THost = undefined>(options: ReadToolDefinitionOptions<THost>): ReadToolDefinition<THost>;

package/dist/signature/definition.js

@@ -0,0 +1,48 @@
+import { createReadTool } from "../core/create-read-tool.js";
+import { parseReadInput } from "../core/input.js";
+import { resolveReadLimits } from "../core/limits.js";
+import { sha256Digest } from "../digest/sha256.js";
+import { lineNumberFormatter } from "../formatters/index.js";
+import { readSignatureMessages } from "./messages.js";
+import { defaultReadSignature } from "./offset-limit.js";
+/**
+ * Creates the read tool and binds it to a signature, default
+ * defaultReadSignature(). The signature's retry text goes under
+ * `options.messages`, so a host message still wins. Throws TypeError where
+ * createReadTool() does.
+ */
+export function readToolDefinition(options) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("readToolDefinition options must be an object");
+    }
+    const { signature = defaultReadSignature(), ...rest } = options;
+    const limits = resolveReadLimits(rest.limits);
+    const formatter = rest.formatter ?? lineNumberFormatter();
+    const digest = rest.digest === undefined ? sha256Digest() : rest.digest;
+    const read = createReadTool({
+        ...rest,
+        limits,
+        formatter,
+        digest,
+        messages: { ...readSignatureMessages(signature), ...rest.messages },
+    });
+    return bindReadTool(signature, read, { limits, formatter, digest });
+}
+function bindReadTool(signature, read, resolved) {
+    return Object.freeze({
+        name: signature.name,
+        description: signature.description,
+        inputSchema: signature.schema,
+        ...(signature.grammar === undefined ? {} : { grammar: signature.grammar }),
+        signature,
+        limits: resolved.limits,
+        formatter: resolved.formatter,
+        digest: resolved.digest,
+        validate(modelInput) {
+            const input = signature.toInput(modelInput);
+            parseReadInput(input, resolved.limits);
+            return input;
+        },
+        execute: async (modelInput, ctx) => read(signature.toInput(modelInput), ctx),
+    });
+}

package/dist/signature/index.d.ts

@@ -1,4 +1,6 @@
 export type { DefaultReadModelInput, LineRangeParam, ReadParam, ReadSignature, } from "./contract.ts";
+export { readToolDefinition } from "./definition.ts";
+export type { ReadToolDefinition, ReadToolDefinitionOptions } from "./definition.ts";
 export { lineRangeSignature } from "./line-range.ts";
 export { readSignatureMessages } from "./messages.ts";
 export { defaultReadSignature } from "./offset-limit.ts";

package/dist/signature/index.js

@@ -1,3 +1,4 @@
+export { readToolDefinition } from "./definition.js";
 export { lineRangeSignature } from "./line-range.js";
 export { readSignatureMessages } from "./messages.js";
 export { defaultReadSignature } from "./offset-limit.js";

package/dist/state/index.d.ts

@@ -5,7 +5,7 @@ export interface MemoryStoreOptions {
     readonly maxEntries?: number;
     /** Default 30 minutes. */
     readonly ttlMs?: number;
-    /** The same clock type as the tools' `clock` dependency. Default the time now. */
+    /** The same clock type as the tools' `clock` option. Default the time now. */
     readonly clock?: Clock;
 }
 /**

package/dist/suggest/suggest-file-names.d.ts

@@ -1,2 +1,6 @@
-/** Up to `maximum` names close to `requested`: same stem, a shared prefix, or a small edit distance. */
+/**
+ * Up to `maximum` names close to `requested`, closest first. The match ignores case.
+ * The rank is: the same name in another case, then the same stem, then a shared prefix,
+ * then an edit distance of 3 or less. Names with the same rank sort by name.
+ */
 export declare function suggestFileNames(requested: string, names: readonly string[], maximum: number): readonly string[];

package/dist/suggest/suggest-file-names.js

@@ -1,4 +1,8 @@
-/** Up to `maximum` names close to `requested`: same stem, a shared prefix, or a small edit distance. */
+/**
+ * Up to `maximum` names close to `requested`, closest first. The match ignores case.
+ * The rank is: the same name in another case, then the same stem, then a shared prefix,
+ * then an edit distance of 3 or less. Names with the same rank sort by name.
+ */
 export function suggestFileNames(requested, names, maximum) {
     const requestedLower = requested.toLowerCase();
     const requestedStem = stem(requestedLower);

package/docs/architecture.md

@@ -39,7 +39,7 @@ formatter.format(outcome, { mode: "model", call, ... }) ─▶ content
 ReadResult
 ```
 
-| Stage               | Phase          | Dependency                   | What happens                                                                                                                                                                                                                                         |
+| Stage               | Phase          | Option                       | What happens                                                                                                                                                                                                                                         |
 | ------------------- | -------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Input               | `input`        | `limits`                     | `parseReadInput` accepts only `path`, `offset`, and `limit`. The path must be a non-blank string with no NUL. `offset` and `limit` must be positive safe integers. `limit` is clamped to `limits.maxLines`, and the tool adds a `clamped` info note. |
 | Filesystem          | `open`         | `fs`                         | A `FileSystem`, or a factory of the call context. The factory runs once for each read.                                                                                                                                                               |
@@ -54,7 +54,7 @@ ReadResult
 | Record              | none           | `state`, `digest`            | Stores the observation. A store failure does not fail the read.                                                                                                                                                                                      |
 | Format              | none           | `formatter`, `messages`      | Turns the outcome into content parts.                                                                                                                                                                                                                |
 
-The core owns line scanning, view selection, clamping, the byte limit, continuation arithmetic, change detection, and note assembly. That list is the reason the package exists. Everything else is a dependency.
+The core owns line scanning, view selection, clamping, the byte limit, continuation arithmetic, change detection, and note assembly. That list is the reason the package exists. Everything else is an option.
 
 ### What open() fetches before authorize
 
@@ -65,7 +65,7 @@ The core owns line scanning, view selection, clamping, the byte limit, continuat
 | Path                                                                                                        | Role                                                                                                        |
 | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | `src/contract/`                                                                                             | The public types, one file for each area. No runtime code. `base.ts` holds the tool-neutral types           |
-| `src/core/create-read-tool.ts`, `core/deps.ts`                                                              | Checks and resolves the dependencies once, synchronously                                                    |
+| `src/core/create-read-tool.ts`, `core/deps.ts`                                                              | Checks and resolves the options once, synchronously                                                         |
 | `src/core/pipeline.ts`                                                                                      | The stage order, and nothing else                                                                           |
 | `src/core/call-scope.ts`                                                                                    | Per-read state: the call object, the phase, `fs(call)`, `state(call)`, the listing budget, and abort checks |
 | `src/core/resolve.ts`, `open.ts`, `suggest.ts`, `authorize.ts`                                              | Resolve, open, suggestions on a miss, and the authorize checks                                              |
@@ -179,15 +179,16 @@ Hooks are host code. The model cannot choose which files a hook reads, so a hook
 
 An observation exists when there is a `digest`:
 
-| Field              | Value                                                                                            |
-| ------------------ | ------------------------------------------------------------------------------------------------ |
-| `statId`           | Hash of the resolved path, identity, size, and modification time                                 |
-| `contentId`        | Hash of the source bytes. `null` when the scan stopped before the end.                           |
-| `viewId`           | Hash of what the model saw: the view text, or the media parts                                    |
-| `id`               | Hash of `statId`, `contentId`, and `viewId`                                                      |
-| `wholeFileVisible` | `true` only when the offset is 1, nothing was truncated or clamped, and no hook changed the view |
+| Field              | Value                                                                                                                                                   |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `statId`           | Hash of the resolved path, identity, size, and modification time                                                                                        |
+| `contentId`        | Hash of the source bytes. `null` when the scan stopped before the end.                                                                                  |
+| `viewId`           | Hash of what the model saw: the view text, or the media parts                                                                                           |
+| `id`               | Hash of `statId`, `contentId`, and `viewId`                                                                                                             |
+| `wholeFileVisible` | `true` only when the offset is 1, nothing was truncated or clamped, and no hook changed the view                                                        |
+| `visibleLines`     | The source lines that the view showed in full. `null` when no line was shown, a line was clamped, a converter made the text, or a hook changed the view |
 
-The record stores these fields with the request range, under the key `file.resolvedPath`. It is schema 2: it also has `origin: "read"`, the backend `version`, and the `digest` id. The write tools store records with `origin: "write"` and `request: null` in the same store, so a later edit knows what the model has seen. The hook runner treats a record of another schema as absent, and `repeatReadGuard` ignores a write record. `record` builds it field by field from the outcome, so nothing from `call` reaches the store. A store whose `get` or `put` fails does not fail the read. A `state` factory that throws does.
+The record stores these fields with the request range, under the key `file.resolvedPath`. Before it stores a record, the core reads the stored record. When that record has the same `digest` and the same non-null `contentId`, the core joins its `seenLines` with this view's `visibleLines`. The record's `wholeFileVisible` is then `true` when this read showed the whole file, when the stored record was whole, or when the joined ranges run from line 1 to the last line and the totals are exact. So a model that reads a file in ranges can still `write` it. Records for one store and key are written one at a time inside the process, so parallel ranged reads all join. Two processes that share a store can still lose a range. It is schema 2: it also has `origin: "read"`, the backend `version`, and the `digest` id. The write tools store records with `origin: "write"` and `request: null` in the same store, so a later edit knows what the model has seen. The hook runner treats a record of another schema as absent, and `repeatReadGuard` ignores a write record. `record` builds it field by field from the outcome, so nothing from `call` reaches the store. A store whose `get` or `put` fails does not fail the read. A `state` factory that throws does.
 
 ## Errors
 
@@ -213,7 +214,7 @@ The core makes the other failures itself:
 - `CHANGED_DURING_READ` from the size check or `verify()`.
 - `UNSUPPORTED_BACKEND` when no classifier had an opinion.
 - `IO_ERROR` when a filesystem method or the byte stream throws.
-- `EXTENSION_FAILED` when host code throws or breaks a rule. `data.extension` names the dependency (`fs`, `state`, `resolve`, `suggest`, `authorize`, `converters`, `budget`, or `hooks`), `data.phase` names the stage, and `data.id` names the extension object when it has one.
+- `EXTENSION_FAILED` when host code throws or breaks a rule. `data.extension` names the option (`fs`, `state`, `resolve`, `suggest`, `authorize`, `converters`, `budget`, or `hooks`), `data.phase` names the stage, and `data.id` names the extension object when it has one.
 
 A formatter that throws, or returns neither a string nor an array, does not reject the call. The core formats the result with `lineNumberFormatter()` and adds no note. The status stays as it was.
 
@@ -242,7 +243,7 @@ The AI SDK adapter passes `ToolExecutionOptions` as `host`. The Pi adapter passe
 ## Deliberate omissions
 
 - **No alias repair.** The core accepts `path`, `offset`, and `limit` only. Other names belong to a signature.
-- **No Node defaults in the core.** `fs` is required and `digest` defaults to `null`. `createNodeReadTool()` in `@better-fs-tools/node` gives the local defaults. A Workers build cannot pull in `node:fs` by mistake.
+- **No Node defaults in the core.** `fs` is required, and `digest` defaults to `sha256Digest()`, which is plain JavaScript. The integrations keep the same defaults. A Workers build cannot pull in `node:fs` by mistake.
 - **No converter path access.** A converter gets the capped stream, never the path.
 - **No nested reads from hooks.** A hook that needs another file reads it with host code.
 - **No write guard.** The precondition check belongs with the write tool that uses the record.

package/docs/result-schema.md

@@ -50,7 +50,7 @@ The outcome is plain data. Only media parts hold bytes, as `Uint8Array`. Nothing
   truncation: { truncated, reasons, primary },
   continuation: { available, next },
   totals: { lines, exact, bytes },
-  observation: { id, statId, contentId, viewId, observedAt, wholeFileVisible } | null,
+  observation: { id, statId, contentId, viewId, observedAt, wholeFileVisible, visibleLines } | null,
   notes: [...],
   content: [{ type: "text", text: "1|..." }]
 }
@@ -70,7 +70,7 @@ Field notes:
 - `truncation.reasons` can hold `lines`, `bytes`, `budget`, `scan-limit`, and `line-length`, in that order. `primary` is the first, or `null`.
 - `continuation.next` is a complete canonical input, `{ path, offset, limit }`. Send it again to continue. It uses canonical names even when the tool uses a renamed signature.
 - `totals.lines` is `null` and `totals.exact` is `false` when the scan limit stopped counting. `totals.bytes` is the scanned byte count when the scan reached the end, and the file size otherwise. For converted text, it is the size of the converted text that was scanned.
-- `observation` is `null` with no `digest`, and for directories. `contentId` is `null` when the scan stopped before the end. For converted text it is still the hash of the source bytes. `wholeFileVisible` is `true` only when the offset is 1, nothing was truncated or clamped, and no hook changed the view.
+- `observation` is `null` with no `digest`, and for directories. `contentId` is `null` when the scan stopped before the end. For converted text it is still the hash of the source bytes. `wholeFileVisible` is `true` only when the offset is 1, nothing was truncated or clamped, and no hook changed the view. `visibleLines` is `{ start, end }`, the source lines that the view showed in full. It is `null` when no line was shown, a line was clamped, a converter made the text, or a hook changed the view.
 
 ## `media`
 
@@ -211,11 +211,14 @@ With a `state` store and a `digest`, an `ok` or `media` result is stored under `
   schema: 2,
   origin: "read",
   observationId, resolvedPath, identity, version, digest,
-  contentId, viewId, observedAt, wholeFileVisible, totalsExact,
+  contentId, viewId, observedAt, wholeFileVisible, seenLines, totalsExact,
   request: { offset, limit }
 }
 ```
 
+- `seenLines` is a sorted list of `{ start, end }` ranges that reads of this `contentId` showed in full. A read joins its `visibleLines` to the ranges of a stored record with the same `digest` and `contentId`. A record for other content starts again from this read.
+- `wholeFileVisible` is `true` when this read showed the whole file, when the stored record for the same content was whole, or when `seenLines` runs from line 1 to the last line and the totals are exact.
+
 - `version` is `file.version`. `digest` is the `Digest.id` that made `contentId` and `viewId`.
 - A write tool stores a record with `origin: "write"` after a commit. Its `viewId` equals its `contentId`, and its `request` is `null`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-fs-tools/read",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A bounded file reader for TypeScript agent tools.",
   "license": "MIT",
   "repository": {
@@ -46,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@better-fs-tools/fs": "^0.2.0"
+    "@better-fs-tools/fs": "^0.3.0"
   },
   "devDependencies": {
     "typebox": "^1.3.16"