@better-fs-tools/read 0.1.0 → 0.3.0

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

@@ -3,7 +3,6 @@ import { ConvertSource } from "./convert-source.js";
 import { checkConvertOutcome, firstMediaType, mediaBytes, refusedOutcome, scanConvertedText, tooLarge, } from "./converted.js";
 import { AbortReadError, raceAbort } from "./cursor.js";
 import { extensionId } from "./extension-error.js";
-import { capabilityNotes } from "./notes.js";
 import { buildObservation } from "./observation.js";
 import { ReadStop } from "./outcomes.js";
 import { textOutcome } from "./text-outcome.js";
@@ -111,7 +110,7 @@ async function drainAndVerify(source, handle, input, throwIfSourceFailed) {
     await verifyHandle(handle, deps.messages, request, file, scope);
 }
 function mediaOutcome(input, classification, parts, notes, source) {
-    const { deps, fs, request, file, converter } = input;
+    const { deps, request, file, converter } = input;
     return {
         tool: "read",
         status: "media",
@@ -127,7 +126,8 @@ 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: [...notes, ...capabilityNotes(fs, deps.messages)],
+        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/format.js

@@ -1,5 +1,4 @@
 import { lineNumberFormatter } from "../formatters/index.js";
-import { extensionId } from "./extension-error.js";
 export function formatResult(deps, call, outcome) {
     const ctx = {
         digest: deps.digest,
@@ -14,20 +13,7 @@ export function formatResult(deps, call, outcome) {
     catch { }
     if (content !== null)
         return { ...outcome, content };
-    const id = extensionId(deps.formatter);
-    const failed = {
-        ...outcome,
-        notes: [
-            ...outcome.notes,
-            {
-                code: "extension-failed",
-                severity: "warning",
-                message: deps.messages.formatterFailed({ formatter: id ?? "formatter" }),
-                data: id === null ? { extension: "formatter" } : { extension: "formatter", id },
-            },
-        ],
-    };
-    return { ...failed, content: toContent(lineNumberFormatter().format(failed, ctx)) ?? [] };
+    return { ...outcome, content: toContent(lineNumberFormatter().format(outcome, ctx)) ?? [] };
 }
 function toContent(output) {
     if (typeof output === "string")

package/dist/core/limits.js

@@ -1,7 +1,7 @@
 /** The default read limits. They are not ceilings: a host may raise any of them. */
 export const defaultReadLimits = Object.freeze({
     maxLines: 2_000,
-    maxViewBytes: 128 * 1_024,
+    maxViewBytes: 50 * 1_024,
     maxCharsPerLine: 2_000,
     maxScanBytes: 64 * 1_024 * 1_024,
     sampleBytes: 8_192,

package/dist/core/messages.js

@@ -6,14 +6,14 @@ const catalog = {
     offsetUnreached: ({ request, reachedLine, retry }) => `Scanning stopped before line ${request.offset} was reached. Retry from line ${reachedLine} with ${retry}.`,
     lineClamped: ({ lines, total, maxChars }) => `Source line${total === 1 ? "" : "s"} ${lines.join(", ")}${total > lines.length ? ", …" : ""} exceeded ${maxChars} characters and ${total === 1 ? "was" : "were"} clamped.`,
     limitClamped: ({ requested, max }) => `The requested line count of ${requested} is over the maximum, so at most ${max} lines are shown.`,
-    scanLimit: ({ maxScanBytes }) => `Scanning stopped at ${maxScanBytes} bytes; total lines and raw content identity are unknown.`,
+    scanLimit: ({ maxScanBytes }) => `Scanning stopped at ${maxScanBytes} bytes, so the total line count is unknown.`,
     empty: ({ path }) => `${path} is empty (0 bytes); no retry is needed.`,
     notFound: ({ request, suggestions }) => suggestions.length === 0
         ? `${request.path} was not found.`
         : `${request.path} was not found. Nearby names: ${quoted(suggestions)}.`,
     pathRepaired: ({ from, to }) => `The requested filename ${JSON.stringify(from)} was repaired to the unique Unicode-equivalent path ${JSON.stringify(to)}.`,
-    notAFile: ({ request, kind }) => `${request.path} is a ${kindLabel(kind)}; directories, FIFOs, sockets, and devices are refused before any content read.`,
-    dangerousPath: ({ request, detail }) => `${request.path} belongs to a refused policy class${detail === null ? "" : ` (${detail})`}.`,
+    notAFile: ({ request, kind }) => `${request.path} is a ${kindLabel(kind)}.`,
+    dangerousPath: ({ request, detail }) => `${request.path} is refused by policy${detail === null ? "" : ` (${detail})`}. Choose another path.`,
     outsideAllowedRoots: ({ request }) => `${request.path} is outside every configured allowed root.`,
     permissionDenied: ({ request }) => `Permission was denied for ${request.path}.`,
     denied: ({ path, detail }) => `${path} was refused by policy${detail === null ? "" : ` (${detail})`}.`,
@@ -26,15 +26,12 @@ const catalog = {
             : `The media converted from ${request.path} is larger than the ${limit}-byte media limit, so it was not returned.`;
     },
     changedDuringRead: ({ request, retry }) => `${request.path} changed while it was being read. Read it again with ${retry} before relying on this result.`,
-    aborted: ({ phase }) => `The read was aborted during the ${phase} phase; no observation was recorded.`,
+    aborted: ({ phase }) => `The read was aborted during the ${phase} phase, so nothing was read.`,
     invalidInput: ({ detail }) => `The read input was rejected: ${detail}`,
     extensionFailed: ({ request, extension, phase }) => `The ${extension} extension failed during the ${phase} phase while reading ${request.path}; this is a host problem rather than a property of the file.`,
     ioError: ({ request }) => `The backend failed while reading ${request === null ? "the requested path" : request.path}.`,
-    unsupportedBackend: ({ request, detail }) => `No classifier had an opinion about ${request.path}${detail === null ? "" : ` (${detail})`}; this is a configuration problem rather than a property of the file.`,
+    unsupportedBackend: ({ request, detail }) => `This host cannot read ${request.path}${detail === null ? "" : ` (${detail})`}. Do not retry.`,
     viewModified: ({ hook }) => `The ${hook} hook changed this view, so it is not the exact file text.`,
-    weakIdentity: ({ backend }) => `The ${backend} backend has no stable identity, so this observation cannot back a write precondition.`,
-    bufferedBackend: ({ backend }) => `The ${backend} backend buffers whole objects instead of streaming them.`,
-    formatterFailed: ({ formatter }) => `The ${formatter} formatter failed, so the default formatter formatted this result.`,
 };
 /** The default wording of every read message. */
 export const defaultReadMessages = Object.freeze(catalog);

package/dist/core/notes.d.ts

@@ -1,4 +1,3 @@
-import type { FileSystem } from "@better-fs-tools/fs";
 import type { ReadRequest } from "../contract/input.ts";
 import type { ReadLimits } from "../contract/limits.ts";
 import type { ReadMessageCatalog } from "../contract/messages.ts";
@@ -13,4 +12,3 @@ export interface ViewNoteContext {
 }
 export declare function buildViewNotes(context: ViewNoteContext): ReadNote[];
 export declare function emptyNote(messages: Readonly<ReadMessageCatalog>, path: string): ReadNote;
-export declare function capabilityNotes(fs: FileSystem, messages: Readonly<ReadMessageCatalog>): ReadNote[];

package/dist/core/notes.js

@@ -89,26 +89,6 @@ export function buildViewNotes(context) {
 export function emptyNote(messages, path) {
     return { code: "empty", severity: "info", message: messages.empty({ path }) };
 }
-export function capabilityNotes(fs, messages) {
-    const notes = [];
-    if (!fs.capabilities.identity) {
-        notes.push({
-            code: "weak-identity",
-            severity: "info",
-            message: messages.weakIdentity({ backend: fs.id }),
-            data: { backend: fs.id },
-        });
-    }
-    if (!fs.capabilities.streaming) {
-        notes.push({
-            code: "buffered-backend",
-            severity: "info",
-            message: messages.bufferedBackend({ backend: fs.id }),
-            data: { backend: fs.id },
-        });
-    }
-    return notes;
-}
 function retryFrom(request, offset) {
     return { path: request.path, offset, limit: request.limit };
 }

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

@@ -1,4 +1,4 @@
-import { buildViewNotes, capabilityNotes, emptyNote } from "./notes.js";
+import { buildViewNotes, emptyNote } from "./notes.js";
 import { buildObservation } from "./observation.js";
 export function textOutcome(input) {
     const { deps, fs, request, file, classification, conversion, scan } = input;
@@ -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({
@@ -67,7 +73,6 @@ export function textOutcome(input) {
             ...(conversion === null && reachedEof && scannedBytes === 0
                 ? [emptyNote(deps.messages, file.displayPath)]
                 : []),
-            ...(fs === null ? [] : capabilityNotes(fs, deps.messages)),
         ],
     };
 }

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);