mixdog 0.7.1

package/src/agent/orchestrator/tools/builtin/path-utils.mjs

@@ -0,0 +1,201 @@
+import { homedir } from 'os';
+import { isAbsolute, relative, resolve } from 'path';
+import { realpathSync } from 'node:fs';
+
+// Restore the on-disk casing of a path (win32 only). rg relativizes candidate
+// paths against its process cwd with a CASE-SENSITIVE prefix strip before
+// matching slash-anchored --glob overrides; a casing mismatch between the
+// spawn cwd and the walked root silently defeats every anchored glob.
+// realpathSync.native resolves the real casing; non-existent paths (and any
+// resolution failure) fall back to the input unchanged.
+export function trueCasePath(p) {
+    if (process.platform !== 'win32' || typeof p !== 'string' || !p) return p;
+    try { return realpathSync.native(p); } catch { return p; }
+}
+
+export function posixPathToWindowsPath(posixPath) {
+    if (process.platform !== 'win32') return posixPath;
+    if (typeof posixPath !== 'string') return posixPath;
+    const cyg = posixPath.match(/^\/cygdrive\/([a-zA-Z])\//);
+    if (cyg) return `${cyg[1]}:\\${posixPath.slice(11).replace(/\//g, '\\')}`;
+    // WSL drive mount: /mnt/c/... → C:\... (Windows drives surface under
+    // /mnt/<letter> inside WSL). Mirrors the /cygdrive/ mapping.
+    const wsl = posixPath.match(/^\/mnt\/([a-zA-Z])\//);
+    if (wsl) return `${wsl[1]}:\\${posixPath.slice(7).replace(/\//g, '\\')}`;
+    const m = posixPath.match(/^\/([a-zA-Z])\//);
+    if (m) return `${m[1]}:\\${posixPath.slice(3).replace(/\//g, '\\')}`;
+    if (posixPath.startsWith('//')) return posixPath.replace(/\//g, '\\');
+    return posixPath;
+}
+
+export function normalizeInputPath(p) {
+    if (typeof p !== 'string') return p;
+    // Trim leading/trailing whitespace — LLMs intermittently emit paths with
+    // stray spaces inside tool_args, which would otherwise hit ENOENT, force
+    // a self-correction turn, and silently invalidate the cache prefix on
+    // subsequent iterations (measured as single-iter cold cache misses).
+    // Also strip embedded ASCII control chars (\x00-\x1F, \x7F) — interpolation
+    // bugs sometimes inject \t/\f/\r/\n mid-path; trim() only touches the ends.
+    // Literal SP (0x20) is preserved so paths like "Program Files" still work.
+    let out = p.trim().replace(/[\x00-\x1F\x7F]/g, '');
+    if (out === '~' || out.startsWith('~/') || out.startsWith('~\\')) {
+        out = homedir() + out.slice(1);
+    }
+    if (process.platform === 'win32') {
+        const looksPosixDrive = /^\/[a-zA-Z]\//.test(out);
+        const looksCygdrive = /^\/cygdrive\/[a-zA-Z]\//.test(out);
+        const looksWsl = /^\/mnt\/[a-zA-Z]\//.test(out);
+        const looksUnc = out.startsWith('//');
+        if (looksPosixDrive || looksCygdrive || looksWsl || looksUnc) {
+            out = posixPathToWindowsPath(out);
+        }
+    }
+    try { out = out.normalize('NFC'); } catch {}
+    return out;
+}
+
+export function normalizeSearchPattern(p) {
+    if (typeof p !== 'string') return p;
+    try { return p.normalize('NFC'); } catch { return p; }
+}
+
+// Glob filters fed to ripgrep (`--glob`) use forward slashes as the path
+// separator on every platform. A Windows-trained agent naturally writes
+// `**\*.ts`, which ripgrep treats as an escape sequence rather than a path
+// separator, so the pattern silently matches nothing. Canonicalize `\`→`/`
+// so backslash globs match. Gated to win32 only — on POSIX a backslash in a
+// glob is a legitimate escape character and must be preserved.
+export function canonicalizeGlobSlashes(p) {
+    if (typeof p !== 'string') return p;
+    if (process.platform !== 'win32') return p;
+    return p.replace(/\\/g, '/');
+}
+
+function firstPresentArg(args, names) {
+    for (const name of names) {
+        if (!args || args[name] === undefined || args[name] === null || args[name] === '') continue;
+        return args[name];
+    }
+    return undefined;
+}
+
+export function normalizeGrepArgs(args) {
+    if (!args || typeof args !== 'object') return args;
+    if (args.pattern === undefined || args.pattern === null || args.pattern === '') {
+        const alias = firstPresentArg(args, ['query', 'regex', 'regexp', 'needle', 'search', 'literal']);
+        if (alias !== undefined) args.pattern = alias;
+    }
+    if (args.glob === undefined || args.glob === null || args.glob === '') {
+        const alias = firstPresentArg(args, ['file_pattern', 'filePattern', 'include', 'includes', 'files']);
+        if (alias !== undefined) args.glob = alias;
+    }
+    if (args.path === undefined || args.path === null || args.path === '') {
+        const alias = firstPresentArg(args, ['root', 'directory', 'dir']);
+        if (alias !== undefined) args.path = alias;
+    }
+    if ((args.output_mode === undefined || args.output_mode === null || args.output_mode === '') && typeof args.mode === 'string') {
+        const mode = args.mode.trim();
+        if (['files_with_matches', 'content', 'count'].includes(mode)) args.output_mode = mode;
+    }
+    return args;
+}
+
+export function normalizeGlobArgs(args) {
+    if (!args || typeof args !== 'object') return args;
+    if (args.pattern === undefined || args.pattern === null || args.pattern === '') {
+        const alias = firstPresentArg(args, ['glob', 'file_pattern', 'filePattern', 'name', 'include', 'includes', 'files']);
+        if (alias !== undefined) args.pattern = alias;
+    }
+    if (args.path === undefined || args.path === null || args.path === '') {
+        const alias = firstPresentArg(args, ['root', 'directory', 'dir']);
+        if (alias !== undefined) args.path = alias;
+    }
+    // Internal-only passthrough: `_extraIgnoreDirs` is an array of basenames
+    // appended as `!**/<name>/**` ignore globs by executeGlobTool for the
+    // duration of one invocation. Not exposed in tools.json. Sanitize to a
+    // string[] of non-empty basenames so executeGlobTool can trust it.
+    if (args._extraIgnoreDirs !== undefined) {
+        const raw = Array.isArray(args._extraIgnoreDirs) ? args._extraIgnoreDirs : [];
+        const sanitized = raw
+            .filter((n) => typeof n === 'string')
+            .map((n) => n.trim())
+            .filter((n) => n.length > 0 && !/[\\/]/.test(n));
+        args._extraIgnoreDirs = sanitized;
+    }
+    return args;
+}
+
+export function normalizeOutputPath(p) {
+    if (typeof p !== 'string') return p;
+    if (process.platform !== 'win32') return p;
+    return p.replace(/\\/g, '/').replace(/^([a-z]):/, (_, d) => d.toUpperCase() + ':');
+}
+
+export function resolveAgainstCwd(filePath, cwd) {
+    return resolve(cwd, filePath);
+}
+
+export function cwdRelativePath(fullPath, workDir) {
+    try {
+        const rel = relative(workDir, fullPath);
+        if (!rel || rel.startsWith('..') || isAbsolute(rel)) return fullPath;
+        return rel;
+    } catch { return fullPath; }
+}
+
+export function extractGlobBaseDirectory(pattern) {
+    const wildcardIdx = pattern.search(/[\*\?\[\{]/);
+    const staticPrefix = wildcardIdx === -1 ? pattern : pattern.slice(0, wildcardIdx);
+    const lastSep = Math.max(
+        staticPrefix.lastIndexOf('/'),
+        staticPrefix.lastIndexOf('\\'),
+    );
+    if (lastSep === -1) return { baseDir: null, relativePattern: pattern };
+    let baseDir = staticPrefix.slice(0, lastSep);
+    const remainder = pattern.slice(lastSep + 1);
+    const relativePattern = remainder.startsWith('/') ? remainder : '/' + remainder;
+    if (process.platform === 'win32' && /^[A-Za-z]:$/.test(baseDir)) {
+        baseDir = baseDir + '\\';
+    }
+    return { baseDir: baseDir || null, relativePattern };
+}
+
+export function hasGlobMagic(value) {
+    return typeof value === 'string' && /[\*\?\[\{]/.test(value);
+}
+
+export function countSplitLines(text) {
+    if (!text) return 0;
+    let lines = 1;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10) lines += 1;
+    }
+    return lines;
+}
+
+export function countDisplayLines(text) {
+    if (!text) return 0;
+    let lines = text.endsWith('\n') ? 0 : 1;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10) lines += 1;
+    }
+    return lines;
+}
+
+export function coerceShapeFlex(value) {
+    if (typeof value !== 'string') return value;
+    const trimmed = value.trim();
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (Array.isArray(parsed)) return parsed;
+        } catch {}
+    }
+    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed === 'string') return parsed;
+        } catch {}
+    }
+    return value;
+}

package/src/agent/orchestrator/tools/builtin/read-args.mjs

@@ -0,0 +1,103 @@
+import { existsSync } from 'fs';
+import { normalizeInputPath, resolveAgainstCwd } from './path-utils.mjs';
+import { parseLineLimitArg } from './read-formatting.mjs';
+
+const READ_LINE_CONTEXT_DEFAULT = 20;
+const READ_LINE_CONTEXT_MAX = 200;
+
+export function parseReadLineNumberArg(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.trunc(n) : null;
+}
+
+export function parseReadLineContextArg(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return READ_LINE_CONTEXT_DEFAULT;
+    return Math.min(READ_LINE_CONTEXT_MAX, Math.max(0, Math.trunc(n)));
+}
+
+export function parseReadPathLineSpec(rawPath) {
+    if (typeof rawPath !== 'string' || rawPath.length === 0) return null;
+    const text = rawPath.trim();
+    let m = /^(.+?)#L(\d+)(?:-L?(\d+))?(?:\b.*)?$/i.exec(text);
+    if (!m) m = /^(.+):(\d+)(?:-(\d+))?(?::.*)?$/.exec(text);
+    if (!m) return null;
+    const lineNo = parseReadLineNumberArg(m[2]);
+    const endLineRaw = parseReadLineNumberArg(m[3]);
+    if (!lineNo || !m[1]) return null;
+    // Inverted range (e.g. file#L20-L10) is a caller mistake, not a
+    // silent fallback to a context window — surface it as an error
+    // flag so the read tool can return a structured error.
+    const inverted = endLineRaw !== null && endLineRaw < lineNo;
+    const endLine = endLineRaw && endLineRaw >= lineNo ? endLineRaw : null;
+    return { path: m[1], lineNo, endLine, inverted, invertedEnd: inverted ? endLineRaw : null };
+}
+
+export function resolveExistingPathLineCoordinate(rawPath, workDir) {
+    const spec = parseReadPathLineSpec(rawPath);
+    if (!spec) return null;
+    const normalizedRawPath = normalizeInputPath(rawPath);
+    const normalizedSpecPath = normalizeInputPath(spec.path);
+    const rawFull = resolveAgainstCwd(normalizedRawPath, workDir);
+    const specFull = resolveAgainstCwd(normalizedSpecPath, workDir);
+    if (existsSync(rawFull) || !existsSync(specFull)) return null;
+    return { ...spec, path: normalizedSpecPath };
+}
+
+export function normalizePathAndStripLineCoordinate(rawPath, workDir) {
+    const resolved = resolveExistingPathLineCoordinate(rawPath, workDir);
+    return resolved ? resolved.path : normalizeInputPath(rawPath);
+}
+
+export function normaliseReadLineWindowArgs(inputArgs, workDir) {
+    const args = { ...inputArgs };
+    let lineNo = parseReadLineNumberArg(args.line);
+    let pathLineRange = null;
+    if (typeof args.path === 'string' && args.path) {
+        const spec = resolveExistingPathLineCoordinate(args.path, workDir);
+        if (spec) {
+            if (spec.inverted) {
+                args._invertedRangeError = `Error: inverted range in path "${inputArgs.path}" — end (${spec.invertedEnd}) precedes start (${spec.lineNo}); use file:${spec.invertedEnd}-${spec.lineNo} or remove the range`;
+                return args;
+            }
+            args.path = spec.path;
+            if (!lineNo) lineNo = spec.lineNo;
+            if (spec.endLine) pathLineRange = { startLine: spec.lineNo, endLine: spec.endLine };
+        }
+    }
+    const isFullMode = !args.mode || args.mode === 'full';
+    // line= and offset= are ALTERNATIVE window anchors. Silently preferring
+    // offset used to discard line/context and (with a bare low offset) fall
+    // through to a whole-file smart-truncate dump — the exact read explosion
+    // a 7-line `line+context` request was trying to avoid. Make it a hard
+    // conflict instead.
+    if (isFullMode && lineNo && args.offset !== undefined && args.offset !== null) {
+        args._invertedRangeError = `Error: conflicting window args — both line (${lineNo}) and offset (${args.offset}) were given; line/context and offset/limit are alternative window forms, pass only one`;
+        return args;
+    }
+    if (isFullMode && lineNo) {
+        if (pathLineRange && args.context === undefined && (args.limit === undefined || args.limit === null)) {
+            args.offset = Math.max(0, pathLineRange.startLine - 1);
+            args.limit = Math.max(1, pathLineRange.endLine - pathLineRange.startLine + 1);
+        } else {
+            const contextExplicit = args.context !== undefined && args.context !== null;
+            const limitExplicit = args.limit !== undefined && args.limit !== null;
+            const context = parseReadLineContextArg(args.context);
+            if (limitExplicit && !contextExplicit) {
+                // Explicit limit, no explicit context: anchor the window AT the
+                // requested line so it is always included. (Was: offset centered
+                // by the default context, which a small limit then truncated to
+                // exclude the very line the caller asked for.)
+                args.offset = Math.max(0, lineNo - 1);
+                args.limit = parseLineLimitArg(args.limit, (context * 2) + 1);
+            } else {
+                const limit = limitExplicit
+                    ? parseLineLimitArg(args.limit, (context * 2) + 1)
+                    : (context * 2) + 1;
+                args.offset = Math.max(0, lineNo - context - 1);
+                args.limit = limit;
+            }
+        }
+    }
+    return args;
+}

package/src/agent/orchestrator/tools/builtin/read-batch.mjs

@@ -0,0 +1,172 @@
+import { READ_BATCH_RANGE_COALESCE_GAP_LINES } from './read-constants.mjs';
+
+// Slices a `read` body (full mode) to the line window [origOffset+1,
+// origOffset+origLimit] (1-based line numbers in the body). Lines whose
+// leading `^(\d+)│` prefix falls outside the window are dropped; the
+// footer line is rebuilt to reflect the new range.
+export function sliceReadBodyByLines(body, origOffset, origLimit) {
+    if (typeof body !== 'string') return body;
+    const off = typeof origOffset === 'number' ? origOffset : 0;
+    // limit:0 = unlimited (matches single-form parseLineLimitArg invariant)
+    const lim = typeof origLimit === 'number' && origLimit !== 0 ? origLimit : (origLimit === 0 ? Infinity : 2000);
+    const firstLine = off + 1;        // 1-based inclusive
+    const lastLine  = off + lim;      // 1-based inclusive
+    const lines = body.split('\n');
+    const kept = [];
+    let footerIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith('[lines ') || line.startsWith('[read complete')) {
+            footerIdx = i;
+            continue;
+        }
+        const m = /^(\d+)[\t│→]/.exec(line);
+        if (m) {
+            const ln = parseInt(m[1], 10);
+            if (ln >= firstLine && ln <= lastLine) kept.push(line);
+        } else if (kept.length === 0 && footerIdx === -1) {
+            kept.push(line);
+        }
+    }
+    // Mirror the scalar read footer shape — only emit finite hints.
+    // `of ?` / `pass offset:Infinity to continue` is noise that
+    // confuses the caller; drop those fields when totals are unknown
+    // or the slice is unbounded (limit:0/Infinity).
+    const totalLine = footerIdx >= 0 ? lines[footerIdx] : '';
+    const totalM = /of (\d+)/.exec(totalLine);
+    const totalNum = totalM ? parseInt(totalM[1], 10) : NaN;
+    const haveTotal = Number.isFinite(totalNum);
+    const finiteLast = Number.isFinite(lastLine);
+    const emittedLast = haveTotal && finiteLast
+        ? Math.min(lastLine, totalNum)
+        : (finiteLast ? lastLine : (kept.length > 0
+            ? (() => {
+                // Read the last kept line's number prefix.
+                const lastKept = kept[kept.length - 1];
+                const km = /^(\d+)[\t│→]/.exec(lastKept);
+                return km ? parseInt(km[1], 10) : firstLine;
+            })()
+            : firstLine));
+    const totalPart = haveTotal ? ` of ${totalNum}` : '';
+    const moreToRead = haveTotal ? emittedLast < totalNum : finiteLast;
+    const continuationPart = moreToRead && Number.isFinite(emittedLast)
+        ? `; pass offset:${emittedLast} to continue`
+        : '';
+    const newFooter = `[lines ${firstLine}-${emittedLast}${totalPart}${continuationPart}]`;
+    return kept.join('\n') + (kept.length ? '\n' : '') + newFooter;
+}
+
+export function isFullModeReadEntry(entry) {
+    return !entry?.mode || entry.mode === 'full';
+}
+
+/** Caller omitted offset/limit — must use standalone read shaping, not union slice. */
+function entryIsImplicitDefaultRead(entry) {
+    return typeof entry?.limit !== 'number' && typeof entry?.offset !== 'number';
+}
+
+export function readEntryLineWindow(entry) {
+    const offset = typeof entry.offset === 'number' && Number.isFinite(entry.offset)
+        ? Math.max(0, Math.trunc(entry.offset))
+        : 0;
+    // full:true uncaps the read (read-single-tool wantFull), so the coalescing
+    // window must extend to EOF too — otherwise the union read is capped at the
+    // default 2000 lines while the entry actually reads the whole file, and the
+    // per-window slice returns truncated/empty results.
+    const limit = entry.full === true
+        ? Infinity
+        : (typeof entry.limit === 'number'
+            ? (entry.limit === 0 ? Infinity : Math.max(1, Math.trunc(entry.limit)))
+            : 2000);
+    return {
+        offset,
+        end: limit === Infinity ? Infinity : offset + limit,
+    };
+}
+
+export function coalesceObjectReadEntries(rawEntries) {
+    const out = new Array(rawEntries.length);
+    const groups = new Map();
+    for (let i = 0; i < rawEntries.length; i++) {
+        const entry = rawEntries[i];
+        if (!isFullModeReadEntry(entry)) {
+            out[i] = entry;
+            continue;
+        }
+        const win = readEntryLineWindow(entry);
+        const key = entry.path || '';
+        if (!groups.has(key)) groups.set(key, []);
+        groups.get(key).push({ index: i, entry, offset: win.offset, end: win.end });
+    }
+    for (const items of groups.values()) {
+        items.sort((a, b) => {
+            if (a.offset !== b.offset) return a.offset - b.offset;
+            if (a.end === b.end) return 0;
+            if (a.end === Infinity) return 1;
+            if (b.end === Infinity) return -1;
+            return a.end - b.end;
+        });
+        const clusters = [];
+        let current = null;
+        for (const item of items) {
+            const itemImplicit = entryIsImplicitDefaultRead(item.entry);
+            const itemExplicit = !itemImplicit;
+            const canMerge = current
+                && (current.end === Infinity || item.offset <= current.end + READ_BATCH_RANGE_COALESCE_GAP_LINES)
+                && !(current.hasImplicit && itemExplicit)
+                && !(itemImplicit && current.hasExplicit)
+                && !(itemImplicit && current.hasImplicit);
+            if (!canMerge) {
+                current = {
+                    offset: item.offset,
+                    end: item.end,
+                    items: [item],
+                    hasImplicit: itemImplicit,
+                    hasExplicit: itemExplicit,
+                };
+                clusters.push(current);
+                continue;
+            }
+            current.items.push(item);
+            current.hasImplicit = current.hasImplicit || itemImplicit;
+            current.hasExplicit = current.hasExplicit || itemExplicit;
+            if (current.end !== Infinity) current.end = item.end === Infinity ? Infinity : Math.max(current.end, item.end);
+        }
+        for (const cluster of clusters) {
+            if (cluster.items.length === 1) {
+                const item = cluster.items[0];
+                out[item.index] = item.entry;
+                continue;
+            }
+            const unionLimit = cluster.end === Infinity ? 0 : cluster.end - cluster.offset;
+            for (const item of cluster.items) {
+                const entryOffset = typeof item.entry.offset === 'number' && Number.isFinite(item.entry.offset)
+                    ? Math.max(0, Math.trunc(item.entry.offset))
+                    : item.offset;
+                const entryLimit = typeof item.entry.limit === 'number'
+                    ? item.entry.limit
+                    : (item.end === Infinity ? 0 : Math.max(1, item.end - item.offset));
+                out[item.index] = {
+                    ...item.entry,
+                    offset: entryOffset,
+                    limit: entryLimit,
+                    _unionOffset: cluster.offset,
+                    _unionLimit: unionLimit,
+                    _needsPerEntrySlice: true,
+                    _origOffset: item.entry.offset,
+                    _origLimit: item.entry.limit,
+                };
+            }
+        }
+    }
+    return out;
+}
+
+/** Disk-read window when batch coalescing merged nearby ranges. */
+export function readEntryCoalescedDiskWindow(entry) {
+    if (!entry || entry._unionOffset === undefined) return null;
+    return {
+        offset: entry._unionOffset,
+        limit: entry._unionLimit,
+    };
+}

package/src/agent/orchestrator/tools/builtin/read-constants.mjs

@@ -0,0 +1,40 @@
+import { SMART_READ_MAX_BYTES } from './read-formatting.mjs';
+
+// Read tool caps.
+//
+// READ_MAX_SIZE_BYTES (10 MB) — fast-path file-size threshold mirroring
+// Claude Code's FAST_PATH_MAX_SIZE (readFileInRange.ts:44). Files at or below
+// this size use readFile + in-memory split by default, which CC measured at
+// ~2x faster than createReadStream + readline for typical source. Explicit
+// offset/limit windows on files above READ_STREAM_RANGE_MIN_BYTES take the
+// streaming path too, so a targeted read avoids materialising a whole
+// medium/large document just to return a few lines. Default no-range reads
+// switch to the streaming smart-summary path once the file is large enough
+// to trigger output elision anyway.
+//
+// READ_WHOLE_FILE_MAX_BYTES (256 KiB) — soft threshold: default whole-file
+// reads larger than this prefer stream smart-elide + READ_MAX_OUTPUT_BYTES
+// truncation (Codex-style proceed) rather than refusing. Hard in-memory cap
+// for loading a full file remains READ_MAX_SIZE_BYTES (10 MiB).
+//
+// READ_MAX_OUTPUT_BYTES (30 KB) — output-truncation cap. Lead-facing default tightened from 50k. Mirrors CC's
+// MAX_OUTPUT_SIZE intent (utils/file.ts:48) and the throw-vs-truncate
+// trade-off Anthropic chose in #21841 (throw is more token-efficient).
+// NOTE: CC's parallel output budget is maxTokens = 25,000 tokens
+// (limits.ts:18), enforced post-read via a tokenizer throw. mixdog
+// caps on BYTES at read time instead (no tokenizer in the hot path);
+// 30 KB ≈ well under a 25k-token budget, so the byte cap is left as-is
+// rather than converted to a token count that can't be expressed
+// cleanly without a tokenizer.
+export const READ_MAX_SIZE_BYTES = 10 * 1024 * 1024;
+export const READ_WHOLE_FILE_MAX_BYTES = 256 * 1024;
+export const READ_MAX_OUTPUT_BYTES = 30_000;
+export const READ_STREAM_RANGE_MIN_BYTES = 128 * 1024;
+export const READ_SMART_STREAM_MIN_BYTES = SMART_READ_MAX_BYTES;
+export const READ_BATCH_RANGE_COALESCE_GAP_LINES = 256;
+export const READ_LARGE_TAIL_MAX_BYTES = 4 * 1024 * 1024;
+export const READ_STREAM_TIMEOUT_MS = 20_000;
+// Hard cap on bytes scanned in a single ranged streaming read (~512 MiB).
+export const READ_MAX_SCAN_BYTES = 512 * 1024 * 1024;
+// Per-line accumulation cap while streaming (before renderReadLine truncates).
+export const READ_MAX_LINE_COLLECT_BYTES = READ_MAX_OUTPUT_BYTES;

package/src/agent/orchestrator/tools/builtin/read-formatting.mjs

@@ -0,0 +1,118 @@
+import { mergeReadRanges } from './read-ranges.mjs';
+
+export const SMART_READ_MAX_BYTES = 30 * 1024;
+export const SMART_READ_MAX_LINES = 600;
+export const SMART_READ_HEAD_LINES = 200;
+export const SMART_READ_TAIL_LINES = 100;
+// Only the genuinely large full reads warrant the anti-re-read advisory; below
+// this the smart-truncate path (30 KB) already caps normal reads, so a 16 KB
+// floor mostly fired on full:true mid-size reads where the advisory was pure
+// tail bloat. Raised to 40 KB to keep the guidance only where re-reading a big
+// file actually hurts.
+export const READ_CONTEXT_ADVISORY_BYTES = 40 * 1024;
+export const READ_MAX_RENDERED_LINE_CHARS = 2_000;
+// Claude-Code parity: the read line-prefix separator is `→` (the `→`
+// arrow), matching Claude Code's default cat -n format `<n>→<content>`. It
+// MUST be a NON-WHITESPACE glyph: a tab/space separator collides with the
+// content's own leading indentation, so a model hand-reconstructing an edit
+// old_string cannot tell the separator from the indent and produces
+// byte-mismatched anchors (grep finds the substring, edit cannot). All
+// read/edit parsers accept `[\t│→]`, so any in-flight tab/pipe-rendered
+// output stays backward-compatible.
+export const LINE_NO_SEP = '→';
+
+export function buildSmartReadTruncationMarker(totalLines, fileBytes, filePath = '') {
+    const kb = Math.max(1, Math.round((Number(fileBytes) || 0) / 1024));
+    return `... [TRUNCATED - ${totalLines} lines / ${kb} KB] ...`;
+}
+
+function rangeFromRenderedReadRows(rows, fallbackStartLine = 1) {
+    if (!Array.isArray(rows) || rows.length === 0) return null;
+    const nums = [];
+    for (const row of rows) {
+        const m = /^(\d+)[\t│→]/.exec(String(row));
+        if (m) nums.push(Number(m[1]));
+    }
+    if (nums.length > 0) {
+        return { startLine: Math.min(...nums), endLine: Math.max(...nums) };
+    }
+    return {
+        startLine: Math.max(1, Number(fallbackStartLine) || 1),
+        endLine: Math.max(1, (Number(fallbackStartLine) || 1) + rows.length - 1),
+    };
+}
+
+// Optional `budget` { maxLines, headLines, tailLines } lets a caller request a
+// TIGHTER head+tail elision than the 600-line / 200+100 default (e.g. read
+// budget:'compact' or max_lines:N) to bound lead-context cost. Omitted -> the
+// standard caps, so existing 4-arg callers are byte-for-byte unchanged.
+export function smartReadTruncate(renderedWithLineNos, totalLines, fileBytes, filePath = '', budget = null) {
+    const maxLines = budget?.maxLines ?? SMART_READ_MAX_LINES;
+    const headLines = budget?.headLines ?? SMART_READ_HEAD_LINES;
+    const tailLines = budget?.tailLines ?? SMART_READ_TAIL_LINES;
+    const overByBytes = fileBytes > SMART_READ_MAX_BYTES;
+    const overByLines = totalLines > maxLines;
+    if (!overByBytes && !overByLines) {
+        return { text: renderedWithLineNos, truncated: false, totalLines, ranges: null };
+    }
+    const rows = renderedWithLineNos.split('\n');
+    const headCount = Math.min(headLines, rows.length);
+    const tailStart = Math.max(headCount, rows.length - tailLines);
+    const elidedRows = tailStart - headCount;
+    if (elidedRows <= 0) {
+        return { text: renderedWithLineNos, truncated: false, totalLines, ranges: null };
+    }
+    const headRows = rows.slice(0, headCount);
+    const tailRows = rows.slice(tailStart);
+    const head = headRows.join('\n');
+    const tail = tailRows.join('\n');
+    const marker = buildSmartReadTruncationMarker(totalLines, fileBytes, filePath);
+    return {
+        text: `${head}\n${marker}\n${tail}`,
+        truncated: true,
+        totalLines,
+        ranges: mergeReadRanges([
+            rangeFromRenderedReadRows(headRows, 1),
+            rangeFromRenderedReadRows(tailRows, tailStart + 1),
+        ].filter(Boolean)),
+    };
+}
+
+export function appendReadContextAdvisory(out, { filePath, lineCount, bytes }) {
+    return out;
+}
+
+export function formatPaginationHint(remaining, nextOffset) {
+    const n = Number(remaining);
+    const label = Number.isFinite(n) && n > 0 ? `${n} more entries` : 'more entries';
+    return `... [${label}; next offset: ${nextOffset}]`;
+}
+
+export function parseOffsetArg(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.trunc(n) : 0;
+}
+
+export function parseLineLimitArg(value, defaultValue) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return defaultValue;
+    if (n === 0) return Infinity;
+    return Math.max(1, Math.trunc(n));
+}
+
+export function truncateReadLineText(line, { truncateLongLine = true } = {}) {
+    let text = String(line ?? '');
+    const originalLength = text.length;
+    if (truncateLongLine && text.length > READ_MAX_RENDERED_LINE_CHARS) {
+        const cps = [...text];
+        const head = cps.slice(0, 1_500).join('');
+        const tail = cps.slice(-300).join('');
+        text = `${head} ... [line truncated: ${originalLength} chars total] ... ${tail}`;
+    }
+    return text;
+}
+
+export function renderReadLine(lineNo, line, { truncateLongLine = true } = {}) {
+    const text = truncateReadLineText(line, { truncateLongLine });
+    return `${lineNo}${LINE_NO_SEP}${text}`;
+}