@nathapp/nax-agent 0.1.0

package/dist/tools/read-continuation.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Ranged-read limit-stop footer (US-001) and cap footer / cap cut (US-002).
+ *
+ * A ranged `Read` whose `limit` ended before the file's known line count
+ * appends a single trailer line that names both the count of unseen lines
+ * and the offset to call back with. Without it, a model that asked for the
+ * first five lines of a fifty-line file would have no in-band signal that
+ * the file continues or how to ask for the next slice — every continuation
+ * had to be inferred by trial and error.
+ *
+ * The trailer is composed deterministically by `limitStopFooter` from three
+ * inputs the tool already has on hand: the slice's last line number, the
+ * floor or true total from the ranged read, and whether that total is a
+ * floor (the read stopped at its I/O bound — `maxFileBytes` on this path).
+ *
+ * The exact predicate that gates the footer lives here as well: a limit
+ * was supplied AND the slice ends before the last line the tool can see.
+ * That second clause is what suppresses the footer in the two ACs where
+ * it would be wrong — `endLine == totalLines`, and the offset-past-last-read
+ * case where the floor header already proves nothing more is reachable
+ * within the byte budget.
+ *
+ * US-002 — the cap footer replaces the limit-stop footer when a Read
+ * result overflows either model-facing budget. `applyCapCut` is the
+ * fit-check → overlong-line → cap-cut → no-k-fits state machine; the cut
+ * keeps the largest `k` such that the header, the first `k` body lines,
+ * and the cap footer fit both budgets.
+ *
+ * The overlong-line step (US-001 of the spill-marker story) is what keeps a
+ * single enormous line from hiding the file's tail: a whole-line cut can
+ * neither shorten such a line nor skip it, so stopping just before it drops
+ * every line after it — including the last output line of a spilled command,
+ * which is often the only signal in the body. See its comment in
+ * `applyCapCut`.
+ *
+ * File-local on purpose. These helpers are properties of the `Read`
+ * composition, nothing else composes them, and `src/tools` does not
+ * export them from its barrel — `read.ts` imports them by relative path.
+ */
+/** Inputs the ranged branch already has on hand. */
+export interface LimitStopFooterInput {
+    /** The offset to continue from: `endLine + 1`. */
+    readonly nextOffset: number;
+    /** True iff the read stopped at the I/O bound (`maxFileBytes` here). */
+    readonly totalIsFloor: boolean;
+    /** The slice's last line number — call it `b` in the spec. */
+    readonly endLine: number;
+    /** The total the ranged branch reported (the `T` of `R = T - b`). */
+    readonly totalLines: number;
+}
+/**
+ * Compose the single trailer line that names the continuation offset.
+ *
+ * `R = totalLines - endLine`, with a trailing `+` exactly when the total
+ * is a floor — the read stopped at its I/O bound and the model cannot
+ * know how many more lines the file really has. The footer is the result's
+ * LAST line: the ranged `Read` joins the body and the footer with `\n`
+ * and writes nothing after the footer.
+ *
+ * The "should the footer be appended at all" check is
+ * `shouldAppendLimitStopFooter` — callers decide first, then ask this helper
+ * to compose the trailer. Splitting the gate from the composition keeps the
+ * no-footer case a pure body with no trailing delimiter to manage.
+ */
+export declare function limitStopFooter(input: LimitStopFooterInput): string;
+/**
+ * True iff the ranged branch should append the limit-stop footer. Two
+ * conditions, both required:
+ *
+ *   1. `limit` was supplied. Without a limit the slice already runs to
+ *      the end of what the tool can read, so there is nothing to name.
+ *   2. `endLine < totalLines`. When the slice's last line IS the last line
+ *      the tool can see, the model cannot ask for anything more — the
+ *      floor header already names that ceiling. Appending a footer that
+ *      points back inside the slice would mislead the model into reading
+ *      the same lines twice.
+ *
+ * Hides the predicate behind a function so the `read.ts` call site reads
+ * as the spec, not as the arithmetic.
+ */
+export declare function shouldAppendLimitStopFooter(hasLimit: boolean, endLine: number, totalLines: number): boolean;
+/** Inputs to compose a single cap footer line. */
+export interface CapFooterInput {
+    /** First selected line number: 1 on the whole-file path, `offset` on the ranged path. */
+    readonly firstLine: number;
+    /** Last selected line number in the cut. The cap footer names `firstLine..lastLine`. */
+    readonly lastLine: number;
+    /**
+     * Pre-formatted total label: `1500` when the read saw the whole file,
+     * `6+` when the read stopped at its I/O bound (the `readCeiling` floor on
+     * the whole-file path, `maxFileBytes` floor on the ranged path). The
+     * trailing `+` is the caller's responsibility; the helper does not
+     * re-derive the floor because it does not know which I/O bound was used.
+     */
+    readonly totalLabel: string;
+}
+/**
+ * The cap footer: `[Showing lines a-b of T. Use offset=X to continue.]`,
+ * where `X = b + 1`. Same text the limit-stop footer uses for `X`; the
+ * difference is the rest of the message — the cap footer names the
+ * delivered range, the limit-stop footer names the unseen count.
+ *
+ * The footer is the result's last line. `read.ts` joins it to the body
+ * with `\n` and writes nothing after it.
+ */
+export declare function capFooter(input: CapFooterInput): string;
+/** Inputs to `applyCapCut` — the tool's two paths pass them in their own shape. */
+export interface ApplyCapCutInput {
+    /** Header line, already composed: `[1500 lines]`, `[6+ lines]`, `[lines 100-1299 of 1500]`. */
+    readonly header: string;
+    /** Selected lines, already split by `\n`. Whole-file: every line of the prefix; ranged: `offset..endLine`. */
+    readonly lines: readonly string[];
+    /** First selected line number (1 on whole-file, `offset` on ranged). */
+    readonly firstLine: number;
+    /** Pre-formatted total label with the floor `+` if applicable. */
+    readonly totalLabel: string;
+    /** Limit-stop footer text if rule 1 applied, otherwise `""`. Replaced by the cap footer on a cut. */
+    readonly limitStopFooter: string;
+    /** Today's unshaped body — returned verbatim when no `k >= 1` fits. */
+    readonly unshapedBody: string;
+    /** Model-facing byte ceiling (`ctx.maxBytes`). */
+    readonly maxBytes: number;
+    /** Model-facing line ceiling (`MODEL_MAX_LINES`). */
+    readonly maxLines: number;
+}
+/** Output of `applyCapCut`. */
+export interface ApplyCapCutResult {
+    /** The composed result content. */
+    readonly content: string;
+}
+/**
+ * Compose the final result: fit the candidate if it fits, else cut at the
+ * largest `k >= 1` such that `header + first k lines + cap footer` fits
+ * both budgets, else return the unshaped body.
+ *
+ * The byte budget is measured over the WHOLE result (header and footer
+ * included); the line budget counts the whole result's lines (the same
+ * `MODEL_MAX_LINES` the after_tool policy uses). The cap footer is the
+ * last line and replaces the limit-stop footer when it fires.
+ *
+ * On no-`k`-fits, the limit-stop footer (if rule 1 produced one) is
+ * appended to today's unshaped body — the spec's "today's result, plus
+ * the limit-stop footer from rule 1 if it applied" — so an over-the-cap
+ * read that the tool cannot even trim by one line still tells the model
+ * how to continue. The after_tool policy then shapes the bytes.
+ */
+export declare function applyCapCut(input: ApplyCapCutInput): ApplyCapCutResult;

package/dist/tools/read-continuation.js

@@ -0,0 +1,176 @@
+/**
+ * Ranged-read limit-stop footer (US-001) and cap footer / cap cut (US-002).
+ *
+ * A ranged `Read` whose `limit` ended before the file's known line count
+ * appends a single trailer line that names both the count of unseen lines
+ * and the offset to call back with. Without it, a model that asked for the
+ * first five lines of a fifty-line file would have no in-band signal that
+ * the file continues or how to ask for the next slice — every continuation
+ * had to be inferred by trial and error.
+ *
+ * The trailer is composed deterministically by `limitStopFooter` from three
+ * inputs the tool already has on hand: the slice's last line number, the
+ * floor or true total from the ranged read, and whether that total is a
+ * floor (the read stopped at its I/O bound — `maxFileBytes` on this path).
+ *
+ * The exact predicate that gates the footer lives here as well: a limit
+ * was supplied AND the slice ends before the last line the tool can see.
+ * That second clause is what suppresses the footer in the two ACs where
+ * it would be wrong — `endLine == totalLines`, and the offset-past-last-read
+ * case where the floor header already proves nothing more is reachable
+ * within the byte budget.
+ *
+ * US-002 — the cap footer replaces the limit-stop footer when a Read
+ * result overflows either model-facing budget. `applyCapCut` is the
+ * fit-check → overlong-line → cap-cut → no-k-fits state machine; the cut
+ * keeps the largest `k` such that the header, the first `k` body lines,
+ * and the cap footer fit both budgets.
+ *
+ * The overlong-line step (US-001 of the spill-marker story) is what keeps a
+ * single enormous line from hiding the file's tail: a whole-line cut can
+ * neither shorten such a line nor skip it, so stopping just before it drops
+ * every line after it — including the last output line of a spilled command,
+ * which is often the only signal in the body. See its comment in
+ * `applyCapCut`.
+ *
+ * File-local on purpose. These helpers are properties of the `Read`
+ * composition, nothing else composes them, and `src/tools` does not
+ * export them from its barrel — `read.ts` imports them by relative path.
+ */
+import { splitModelLines } from "./truncate.js";
+/**
+ * Compose the single trailer line that names the continuation offset.
+ *
+ * `R = totalLines - endLine`, with a trailing `+` exactly when the total
+ * is a floor — the read stopped at its I/O bound and the model cannot
+ * know how many more lines the file really has. The footer is the result's
+ * LAST line: the ranged `Read` joins the body and the footer with `\n`
+ * and writes nothing after the footer.
+ *
+ * The "should the footer be appended at all" check is
+ * `shouldAppendLimitStopFooter` — callers decide first, then ask this helper
+ * to compose the trailer. Splitting the gate from the composition keeps the
+ * no-footer case a pure body with no trailing delimiter to manage.
+ */
+export function limitStopFooter(input) {
+    const { nextOffset, totalIsFloor, endLine, totalLines } = input;
+    const remaining = Math.max(0, totalLines - endLine);
+    const countLabel = totalIsFloor ? `${remaining}+` : `${remaining}`;
+    return `[${countLabel} more lines in file. Use offset=${nextOffset} to continue.]`;
+}
+/**
+ * True iff the ranged branch should append the limit-stop footer. Two
+ * conditions, both required:
+ *
+ *   1. `limit` was supplied. Without a limit the slice already runs to
+ *      the end of what the tool can read, so there is nothing to name.
+ *   2. `endLine < totalLines`. When the slice's last line IS the last line
+ *      the tool can see, the model cannot ask for anything more — the
+ *      floor header already names that ceiling. Appending a footer that
+ *      points back inside the slice would mislead the model into reading
+ *      the same lines twice.
+ *
+ * Hides the predicate behind a function so the `read.ts` call site reads
+ * as the spec, not as the arithmetic.
+ */
+export function shouldAppendLimitStopFooter(hasLimit, endLine, totalLines) {
+    return hasLimit && endLine < totalLines;
+}
+/**
+ * The cap footer: `[Showing lines a-b of T. Use offset=X to continue.]`,
+ * where `X = b + 1`. Same text the limit-stop footer uses for `X`; the
+ * difference is the rest of the message — the cap footer names the
+ * delivered range, the limit-stop footer names the unseen count.
+ *
+ * The footer is the result's last line. `read.ts` joins it to the body
+ * with `\n` and writes nothing after it.
+ */
+export function capFooter(input) {
+    const { firstLine, lastLine, totalLabel } = input;
+    return `[Showing lines ${firstLine}-${lastLine} of ${totalLabel}. Use offset=${lastLine + 1} to continue.]`;
+}
+/**
+ * Compose the final result: fit the candidate if it fits, else cut at the
+ * largest `k >= 1` such that `header + first k lines + cap footer` fits
+ * both budgets, else return the unshaped body.
+ *
+ * The byte budget is measured over the WHOLE result (header and footer
+ * included); the line budget counts the whole result's lines (the same
+ * `MODEL_MAX_LINES` the after_tool policy uses). The cap footer is the
+ * last line and replaces the limit-stop footer when it fires.
+ *
+ * On no-`k`-fits, the limit-stop footer (if rule 1 produced one) is
+ * appended to today's unshaped body — the spec's "today's result, plus
+ * the limit-stop footer from rule 1 if it applied" — so an over-the-cap
+ * read that the tool cannot even trim by one line still tells the model
+ * how to continue. The after_tool policy then shapes the bytes.
+ */
+export function applyCapCut(input) {
+    const { header, lines, firstLine, totalLabel, limitStopFooter, unshapedBody, maxBytes, maxLines } = input;
+    // Rule 1's candidate: today's body, plus the limit-stop footer if it
+    // applied. The fit check decides whether this form is what the model
+    // sees (returning it unchanged when it fits) or whether the cap cut
+    // has to fire.
+    const candidate = limitStopFooter === "" ? unshapedBody : `${unshapedBody}\n${limitStopFooter}`;
+    // Step 1 — fit check. If today's candidate fits both the line cap and
+    // the byte cap, return it unchanged. The after_tool policy then sees a
+    // within-cap result and is a no-op on it.
+    //
+    // The line count uses `splitModelLines`, the same helper the cut path
+    // and the after_tool policy use, so the cap matches across all three
+    // seams. A raw `split("\n")` would count the trailing newline as a
+    // phantom empty line and reject a candidate that is exactly at the
+    // cap (e.g. header + 999 body lines + "\n" reports as 1001 lines via
+    // raw split but 1000 via `splitModelLines`).
+    if (splitModelLines(candidate).length <= maxLines && Buffer.byteLength(candidate, "utf8") <= maxBytes) {
+        return { content: candidate };
+    }
+    // Step 2 — overlong line: hand the body to the after_tool policy.
+    //
+    // A line whose own bytes exceed the WHOLE model-facing byte budget can
+    // never be delivered by this cut, whatever precedes it: the cut is
+    // whole-line, so it can neither shorten such a line nor skip it. Cutting
+    // just before it would therefore spend the result on the short lines in
+    // front of it and drop every line behind it — including the LAST line of a
+    // spilled command's output, which is exactly the line a caller reaches for.
+    // (`[3 lines] / exit 0 / <160 KB blob> / LAST LINE` cut to the 68 bytes
+    // before the blob is the shape this rules out.)
+    //
+    // So the candidate passes through unshaped, exactly as the no-k-fits case
+    // below does, and the after_tool policy shapes it: that policy caps an
+    // overlong line at the per-line ceiling instead of evicting the lines
+    // around it, and spills what it cuts, so the tail stays reachable.
+    if (lines.some((line) => Buffer.byteLength(line, "utf8") > maxBytes)) {
+        return { content: candidate };
+    }
+    // Step 3 — cap cut. Try k from largest to smallest; the first one that
+    // fits both budgets is the cut. Walking largest-first is what guarantees
+    // the result holds the most whole lines that can fit — picking a smaller
+    // k would leave whole lines on the floor that could have been delivered.
+    //
+    // The upper bound is min(lines.length, maxLines - 2): the line cap
+    // already bars any `k` greater than `maxLines - 2`, so iterating higher
+    // would only hit the `continue` guard. For a 2 MB ceiling of 1-byte lines
+    // (`lines.length` ≈ 1 000 000) the unconstrained start wastes ~998 000
+    // pointless iterations before reaching the meaningful range.
+    for (let k = Math.min(lines.length, maxLines - 2); k >= 1; k -= 1) {
+        // Line budget: header + k body lines + cap footer line.
+        if (1 + k + 1 > maxLines)
+            continue;
+        const lastLine = firstLine + k - 1;
+        const footer = capFooter({ firstLine, lastLine, totalLabel });
+        // Compose: header\n + (k lines joined by \n) + \n + footer.
+        // No trailing newline — the cap footer is the last line, with
+        // nothing after it. A cut result never ends with a newline.
+        const bodyJoined = lines.slice(0, k).join("\n");
+        const cut = `${header}\n${bodyJoined}\n${footer}`;
+        if (Buffer.byteLength(cut, "utf8") <= maxBytes) {
+            return { content: cut };
+        }
+    }
+    // Step 4 — no k fits: today's candidate passes through unchanged. The
+    // cap footer is absent here — the rule is "no line fits with the header
+    // and cap footer", so neither can be appended. The after_tool policy
+    // is the backstop for these cases.
+    return { content: candidate };
+}

package/dist/tools/read-file.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared ranged file-read core — US-001.
+ *
+ * A single implementation that backs both `readTool` and (under US-003)
+ * `ScratchpadRead`. The `readCeiling` parameter is the tool-layer I/O bound,
+ * distinct from `maxFileBytes` which remains the whole-file Edit/Write cap.
+ */
+export interface ReadFileSliceOptions {
+    /** Tool-layer I/O bound. Omit to default to `READ_CEILING`. */
+    readonly readCeiling?: number;
+    /** 1-based line number to start reading from. Omit to start at the first line. */
+    readonly offset?: number;
+    /** Maximum number of lines to return. Omit to read until the end of the file. */
+    readonly limit?: number;
+}
+export interface ReadFileSliceResult {
+    /** The slice body (empty string when the offset is past the end). */
+    readonly content: string;
+    /** True when the file is larger than the supplied `readCeiling`. */
+    readonly bounded: boolean;
+    /** Total number of lines the file holds (a floor when `bounded` is true). */
+    readonly totalLines: number;
+}
+/**
+ * Read a ranged slice of a UTF-8 file.
+ *
+ * Honours the trailing-newline convention: a body ending in "\n" has that
+ * newline TERMINATE the last line rather than open an empty one, so the
+ * returned `totalLines` agrees with `readTool`'s `[N lines]` header and the
+ * model's mental model of a file. An empty body has zero lines.
+ */
+export declare function readFileSlice(target: string, opts?: ReadFileSliceOptions): Promise<ReadFileSliceResult>;

package/dist/tools/read-file.js

@@ -0,0 +1,85 @@
+/**
+ * Shared ranged file-read core — US-001.
+ *
+ * A single implementation that backs both `readTool` and (under US-003)
+ * `ScratchpadRead`. The `readCeiling` parameter is the tool-layer I/O bound,
+ * distinct from `maxFileBytes` which remains the whole-file Edit/Write cap.
+ */
+import { open } from "node:fs/promises";
+import { NaxError } from "#src/infra/index";
+import { fileSizeOrZero } from "#src/internal/file-size";
+import { cutBufferToByteCap, READ_CEILING } from "./truncate.js";
+/** Reject offset/limit values that would silently drift to the file's last line. */
+function validateRange(opts) {
+    if (opts.offset !== undefined && (!Number.isInteger(opts.offset) || opts.offset <= 0)) {
+        throw new NaxError(`offset must be a positive integer (1-based); got ${JSON.stringify(opts.offset)}`, "READ_RANGE_INVALID", { stage: "tools", offset: opts.offset });
+    }
+    if (opts.limit !== undefined && (!Number.isInteger(opts.limit) || opts.limit <= 0)) {
+        throw new NaxError(`limit must be a positive integer; got ${JSON.stringify(opts.limit)}`, "READ_RANGE_INVALID", {
+            stage: "tools",
+            limit: opts.limit,
+        });
+    }
+}
+/**
+ * Read a ranged slice of a UTF-8 file.
+ *
+ * Honours the trailing-newline convention: a body ending in "\n" has that
+ * newline TERMINATE the last line rather than open an empty one, so the
+ * returned `totalLines` agrees with `readTool`'s `[N lines]` header and the
+ * model's mental model of a file. An empty body has zero lines.
+ */
+export async function readFileSlice(target, opts = {}) {
+    validateRange(opts);
+    const ceiling = opts.readCeiling ?? READ_CEILING;
+    // Probe the file size with `fileSizeOrZero(target)` so we know whether the
+    // file exceeds the ceiling without reading past it. That stat is also why
+    // this reads exactly `ceiling` bytes rather than `readPrefix`'s
+    // ceiling-plus-one: the overshoot exists to infer "there was more" from the
+    // read itself, and here the stat already answers that — so the extra byte
+    // would only carry the read past the bound it is meant to enforce.
+    const fileSize = fileSizeOrZero(target);
+    const readBudget = Math.min(ceiling, fileSize);
+    const handle = await open(target, "r");
+    let body = "";
+    try {
+        const buffer = Buffer.alloc(readBudget);
+        const { bytesRead } = await handle.read(buffer, 0, readBudget, 0);
+        // The bound can land inside a codepoint, and a partial tail decodes to
+        // U+FFFD (3 bytes) — which would put the returned body back over the
+        // ceiling it was just capped at. Trim to a clean boundary so the byte
+        // budget holds for the caller.
+        body = cutBufferToByteCap(buffer.subarray(0, bytesRead), ceiling).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+    const bounded = fileSize > ceiling;
+    // Trailing-newline convention: strip the trailing "\n" before splitting,
+    // so "a\nb\n" yields two lines, not three.
+    const trailingNewline = body.endsWith("\n");
+    const lines = trailingNewline ? body.slice(0, -1).split("\n") : body === "" ? [] : body.split("\n");
+    // When bounded, we read exactly `ceiling` bytes — there are more lines past
+    // what we observed. The "lines.length + 1" floor captures that: a bounded
+    // file's last visible line either is truncated (a partial line continuing
+    // past the ceiling) or ended with the trailing "\n" we already stripped, so
+    // at least one more line lives beyond what we read.
+    const totalLines = bounded ? lines.length + 1 : lines.length;
+    // Offset/limit slicing.
+    if (opts.offset !== undefined && opts.offset > totalLines) {
+        return { content: "", bounded, totalLines };
+    }
+    if (opts.offset === undefined && opts.limit === undefined) {
+        // Whole-file path: return the read body verbatim so callers see the
+        // same trailing newline the file holds.
+        return { content: body, bounded, totalLines };
+    }
+    const startIndex = (opts.offset ?? 1) - 1;
+    const endLine = opts.limit === undefined ? lines.length : Math.min(startIndex + opts.limit, lines.length);
+    // Joined with no synthesised terminator, mirroring `readTool`'s offset/limit
+    // path (src/tools/read.ts): a caller asking for lines 3-4 gets lines 3 and 4,
+    // not a newline it did not ask for. The whole-file path above stays verbatim,
+    // trailing newline included, because there the caller asked for the file.
+    const content = lines.slice(startIndex, endLine).join("\n");
+    return { content, bounded, totalLines };
+}

package/dist/tools/read.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Read one file, already resolved and approved by the policy.
+ *
+ * The tool never resolves a path itself: it uses ctx.resolvedPaths, which the
+ * policy produced. That is what keeps containment in one seam.
+ *
+ * offset/limit (#1923): models constantly ask for a line range under six
+ * different invented spellings, and every one of them was silently discarded
+ * because `run`'s input parameter was unused. offset/limit is the spelling
+ * they reach for most (144 of 187 observed range arguments), so that is the
+ * only shape honoured -- every other spelling is rejected by name rather than
+ * silently dropped, the same principle policy.ts uses for a denied argv: name
+ * the supported forms instead of a bare refusal.
+ *
+ * Self-cap at whole-line model caps (US-002): when today's body overflows the
+ * line or byte ceiling, the tool cuts at the largest whole-line boundary that
+ * still fits and appends a single trailer naming the delivered range. The
+ * after_tool policy (`applyModelTruncationPolicy`) is the unconditional
+ * backstop — a result that already fits every cap passes through it untouched
+ * (its within-cap contract), so no spill file is written for it. The cap
+ * footer replaces the limit-stop footer when it fires; a result never carries
+ * both.
+ */
+import type { CodingTool } from "./registry.ts";
+export declare const readTool: CodingTool;

package/dist/tools/read.js

@@ -0,0 +1,182 @@
+/**
+ * Read one file, already resolved and approved by the policy.
+ *
+ * The tool never resolves a path itself: it uses ctx.resolvedPaths, which the
+ * policy produced. That is what keeps containment in one seam.
+ *
+ * offset/limit (#1923): models constantly ask for a line range under six
+ * different invented spellings, and every one of them was silently discarded
+ * because `run`'s input parameter was unused. offset/limit is the spelling
+ * they reach for most (144 of 187 observed range arguments), so that is the
+ * only shape honoured -- every other spelling is rejected by name rather than
+ * silently dropped, the same principle policy.ts uses for a denied argv: name
+ * the supported forms instead of a bare refusal.
+ *
+ * Self-cap at whole-line model caps (US-002): when today's body overflows the
+ * line or byte ceiling, the tool cuts at the largest whole-line boundary that
+ * still fits and appends a single trailer naming the delivered range. The
+ * after_tool policy (`applyModelTruncationPolicy`) is the unconditional
+ * backstop — a result that already fits every cap passes through it untouched
+ * (its within-cap contract), so no spill file is written for it. The cap
+ * footer replaces the limit-stop footer when it fires; a result never carries
+ * both.
+ */
+import { readPrefix } from "#src/internal/bounded-io";
+import { applyCapCut, limitStopFooter, shouldAppendLimitStopFooter } from "./read-continuation.js";
+import { MODEL_MAX_BYTES, MODEL_MAX_LINES, READ_CEILING, splitModelLines } from "./truncate.js";
+/** Range arguments models invent instead of offset/limit -- rejected by name, never silently dropped. */
+const UNSUPPORTED_RANGE_ALIASES = ["start_line", "end_line", "start", "end", "line", "lineEnd", "size"];
+/** A positive integer, or an error string naming which constraint failed. */
+function parsePositiveInt(value, field) {
+    if (typeof value !== "number" || !Number.isInteger(value))
+        return `${field} must be an integer`;
+    if (value < 1)
+        return `${field} must be >= 1`;
+    return value;
+}
+/** Count lines in a UTF-8 string. Empty string returns 0. Trailing newline is not a line. */
+function countLines(prefix) {
+    if (prefix === "")
+        return 0;
+    const trimmed = prefix.endsWith("\n") ? prefix.slice(0, -1) : prefix;
+    return trimmed.split("\n").length;
+}
+export const readTool = {
+    name: "Read",
+    description: "Read a UTF-8 text file from the repository. Paths are relative to the repository root. " +
+        "Optionally pass offset (1-based line number to start from) and/or limit (maximum number of " +
+        "lines to return) to read a slice instead of the whole file. " +
+        "Use Read to examine files instead of cat, sed, head, tail or awk in Bash. " +
+        "A read that stops before the end of the file ends with a line naming the offset to continue from. " +
+        "For a large file, read the part you need with offset/limit; when you need the whole file, continue with offset until complete. " +
+        `Output is capped at ${MODEL_MAX_LINES} lines or ${MODEL_MAX_BYTES} bytes.`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "Path relative to the repository root" },
+            offset: { type: "integer", minimum: 1, description: "1-based line number to start reading from" },
+            limit: { type: "integer", minimum: 1, description: "Maximum number of lines to return" },
+        },
+        required: ["path"],
+    },
+    scope: { pathFields: ["path"] },
+    async run(input, ctx) {
+        const [target] = ctx.resolvedPaths;
+        if (target === undefined)
+            return { content: "no path supplied", isError: true };
+        const usedAlias = UNSUPPORTED_RANGE_ALIASES.find((alias) => input[alias] !== undefined);
+        if (usedAlias !== undefined) {
+            return {
+                content: `"${usedAlias}" is not a supported Read argument -- use offset (1-based line number) and/or limit (line count) instead`,
+                isError: true,
+            };
+        }
+        const hasOffset = input.offset !== undefined;
+        const hasLimit = input.limit !== undefined;
+        try {
+            if (!hasOffset && !hasLimit) {
+                // Leading [N lines] header so an agent has a way to count the lines it
+                // is reading. The count comes from the maxBytes prefix, not a second,
+                // larger read: readPrefix asks for maxBytes + 1 and the overshoot byte
+                // is what tells us the prefix hit the ceiling -- in that case the count
+                // is a floor and we mark it with '+'. The ranged branch reads with
+                // maxFileBytes and compares against maxFileBytes for the same reason.
+                const readCeiling = ctx.readCeiling ?? READ_CEILING;
+                const prefix = await readPrefix(target, readCeiling);
+                const bounded = Buffer.byteLength(prefix, "utf8") > readCeiling;
+                const lineCount = countLines(prefix);
+                const totalLabel = bounded ? `${lineCount}+` : `${lineCount}`;
+                const header = `[${totalLabel} lines]`;
+                // US-002: the whole-file prefix is shaped at the model-facing caps
+                // before being handed to the runtime. Today's unshaped body is
+                // `header + (prefix when non-empty)`. The cap cut tries the largest
+                // k such that `header + first k lines + cap footer` fits both budgets;
+                // when no k fits, today's body passes through unchanged and the
+                // after_tool policy shapes it.
+                const unshaped = prefix === "" ? header : `${header}\n${prefix}`;
+                const result = applyCapCut({
+                    header,
+                    lines: splitModelLines(prefix),
+                    firstLine: 1,
+                    totalLabel,
+                    limitStopFooter: "",
+                    unshapedBody: unshaped,
+                    maxBytes: ctx.maxBytes,
+                    maxLines: MODEL_MAX_LINES,
+                });
+                return { content: result.content };
+            }
+            let offset = 1;
+            if (hasOffset) {
+                const parsed = parsePositiveInt(input.offset, "offset");
+                if (typeof parsed === "string")
+                    return { content: parsed, isError: true };
+                offset = parsed;
+            }
+            let limit;
+            if (hasLimit) {
+                const parsed = parsePositiveInt(input.limit, "limit");
+                if (typeof parsed === "string")
+                    return { content: parsed, isError: true };
+                limit = parsed;
+            }
+            // Read up to maxFileBytes, not maxBytes: the requested range may start
+            // past the display ceiling, and we still need to reach it to slice.
+            const body = await readPrefix(target, ctx.maxFileBytes);
+            // readPrefix asks for maxFileBytes + 1, so overshooting the ceiling is how
+            // we know the file continues past what we read. The line count is then a
+            // floor, not a total, and must not be reported as one -- claiming a false
+            // total to the model is the same class of defect #1923 is fixing.
+            const bounded = Buffer.byteLength(body, "utf8") > ctx.maxFileBytes;
+            const totalLines = countLines(body);
+            const totalLabel = bounded ? `${totalLines}+` : `${totalLines}`;
+            if (offset > totalLines) {
+                return {
+                    content: bounded
+                        ? `offset ${offset} is past the first ${totalLines} lines, which is all that could be read within the ${ctx.maxFileBytes}-byte ceiling`
+                        : `offset ${offset} is past the end of the file -- it has ${totalLines} lines`,
+                };
+            }
+            const lines = splitModelLines(body);
+            const startIndex = offset - 1;
+            const endLine = limit === undefined ? totalLines : Math.min(startIndex + limit, totalLines);
+            const selected = lines.slice(startIndex, endLine).join("\n");
+            const headerLine = `[lines ${offset}-${endLine} of ${totalLabel}]`;
+            // US-001: when a `limit` cut the slice short of the file's known line
+            // count, append a single trailer that names the continuation offset.
+            // The helper hides the predicate (limit given AND endLine < totalLines)
+            // and the `+`-on-floor rule, both of which are easy to drift apart from
+            // the header if inlined.
+            const limitStop = shouldAppendLimitStopFooter(limit !== undefined, endLine, totalLines)
+                ? limitStopFooter({
+                    nextOffset: endLine + 1,
+                    totalIsFloor: bounded,
+                    endLine,
+                    totalLines,
+                })
+                : "";
+            // US-002: shape today's body at the model-facing caps. The cap cut
+            // replaces the limit-stop footer when it fires; when no whole line
+            // fits with the header and cap footer, today's body is returned
+            // unchanged (plus the limit-stop footer from rule 1 if it applied),
+            // and the after_tool policy then shapes it.
+            const unshapedBody = `${headerLine}\n${selected}`;
+            const result = applyCapCut({
+                header: headerLine,
+                lines: lines.slice(startIndex, endLine),
+                firstLine: offset,
+                totalLabel,
+                limitStopFooter: limitStop,
+                unshapedBody,
+                maxBytes: ctx.maxBytes,
+                maxLines: MODEL_MAX_LINES,
+            });
+            return { content: result.content };
+        }
+        catch (err) {
+            // An unreadable file is a tool ERROR the model can react to, never a
+            // denial: the policy already said yes.
+            return { content: err instanceof Error ? err.message : String(err), isError: true };
+        }
+    },
+};