@glbgpt/cli 0.1.0-test.4 → 0.1.0

package/dist/src/fs/grepTool.js

@@ -0,0 +1,146 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { GuardError, resolveInWorkspace, sanitizeFsError } from './workspaceGuard.js';
+import { walkFiles } from './walk.js';
+import { globToRegExp } from './globTool.js';
+import { GREP_TIMEOUT_MS, MAX_FILE_SIZE_BYTES, MAX_GREP_LINE_CHARS, MAX_GREP_MATCHES, } from './limits.js';
+function looksBinary(buf) {
+    return buf.subarray(0, 8192).includes(0);
+}
+/**
+ * Per-file matcher, run inside a vm context so the call deadline can interrupt
+ * catastrophic regex backtracking (vm timeout = V8 TerminateExecution, which
+ * does stop a spinning RegExp — see GREP_TIMEOUT_MS in limits.ts). The script
+ * is fixed; the model supplies only the regex SOURCE string, which the RegExp
+ * constructor treats as data, never as code.
+ */
+const MATCH_SCRIPT = new vm.Script(`{
+  const re = new RegExp(source);
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) if (re.test(lines[i])) hits.push(i);
+  hits;
+}`);
+function fmtTimeout(ms) {
+    return ms >= 1000 ? `${Math.round(ms / 1000)}s` : `${ms}ms`;
+}
+export function createGrepTool(root, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? GREP_TIMEOUT_MS;
+    return {
+        name: 'grep',
+        readOnly: true,
+        description: 'Search file contents inside the workspace with a regular expression (JavaScript syntax). ' +
+            `Returns "file:line: text" matches (first ${MAX_GREP_MATCHES}; larger result sets are truncated ` +
+            'with a note). Binary files and files over 1MB are skipped. ' +
+            'Use include (e.g. "*.md") to restrict which files are searched. ' +
+            'Searches are time-boxed; on timeout you get any partial results plus a note (timeout does NOT mean no matches).',
+        parameters: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string', description: 'Regular expression to search for.' },
+                path: { type: 'string', description: 'Directory to search from (default workspace root).' },
+                include: { type: 'string', description: 'Glob filter on file names, e.g. "*.md".' },
+            },
+            required: ['pattern'],
+        },
+        async execute(args) {
+            if (typeof args.pattern !== 'string' || !args.pattern.trim()) {
+                return { error: 'Missing required "pattern" argument.' };
+            }
+            try {
+                new RegExp(args.pattern); // validity check only — matching happens in the vm (see MATCH_SCRIPT)
+            }
+            catch (e) {
+                return { error: `Invalid regex: ${e instanceof Error ? e.message : String(e)}` };
+            }
+            const includeRx = typeof args.include === 'string' && args.include.trim()
+                ? globToRegExp(args.include)
+                : null;
+            const startArg = typeof args.path === 'string' && args.path.trim() ? args.path : '.';
+            try {
+                const start = await resolveInWorkspace(root, startArg);
+                const out = [];
+                let truncated = false;
+                let timedOut = false;
+                const deadline = Date.now() + timeoutMs;
+                const ctx = vm.createContext(Object.create(null));
+                outer: for await (const f of walkFiles(root, start)) {
+                    if (includeRx && !includeRx.test(path.basename(f.rel)))
+                        continue;
+                    const stat = await fs.stat(f.abs);
+                    if (stat.size > MAX_FILE_SIZE_BYTES)
+                        continue;
+                    const buf = await fs.readFile(f.abs);
+                    if (looksBinary(buf))
+                        continue;
+                    const lines = buf.toString('utf8').split('\n');
+                    const remaining = deadline - Date.now();
+                    if (remaining <= 0) {
+                        timedOut = true;
+                        break;
+                    }
+                    let hits;
+                    try {
+                        ctx.source = args.pattern;
+                        ctx.lines = lines;
+                        hits = MATCH_SCRIPT.runInContext(ctx, { timeout: Math.max(1, remaining) });
+                    }
+                    catch (err) {
+                        if (err.code === 'ERR_SCRIPT_EXECUTION_TIMEOUT') {
+                            timedOut = true;
+                            break;
+                        }
+                        throw err;
+                    }
+                    for (const i of hits) {
+                        const text = lines[i].length > MAX_GREP_LINE_CHARS
+                            ? `${lines[i].slice(0, MAX_GREP_LINE_CHARS)}…`
+                            : lines[i];
+                        out.push(`${f.rel}:${i + 1}: ${text.trim()}`);
+                        // Discovery results are cheap — stop at the cap and report truncation
+                        // instead of erroring, saving the model a retry round-trip.
+                        if (out.length >= MAX_GREP_MATCHES) {
+                            truncated = true;
+                            break outer;
+                        }
+                    }
+                }
+                if (timedOut) {
+                    // Claude Code's RipgrepTimeoutError lesson: a timeout must be
+                    // distinguishable from "no matches", or the model draws wrong conclusions.
+                    const t = fmtTimeout(timeoutMs);
+                    if (out.length === 0) {
+                        return {
+                            error: `Search timed out after ${t} before completing (the pattern may backtrack ` +
+                                `catastrophically or the tree is large). This is NOT "no matches" — simplify ` +
+                                'the pattern or narrow the path/include filter and retry.',
+                        };
+                    }
+                    const note = `(Search timed out after ${t} before completing — results above are PARTIAL. ` +
+                        'Simplify the pattern or narrow the path/include filter to search the rest.)';
+                    return {
+                        summary: `${out.length} match${out.length === 1 ? '' : 'es'} (timed out, partial)`,
+                        content: [...out, note].join('\n'),
+                    };
+                }
+                if (out.length === 0)
+                    return { error: `No matches for: ${args.pattern}` };
+                if (truncated) {
+                    const note = `(Results truncated at ${MAX_GREP_MATCHES} matches. Narrow the pattern, path, or include filter.)`;
+                    return {
+                        summary: `${MAX_GREP_MATCHES} matches (truncated)`,
+                        content: [...out, note].join('\n'),
+                    };
+                }
+                return { summary: `${out.length} match${out.length === 1 ? '' : 'es'}`, content: out.join('\n') };
+            }
+            catch (err) {
+                if (err instanceof GuardError)
+                    return { error: err.message };
+                const message = err instanceof Error ? err.message : String(err);
+                return { error: `grep failed: ${sanitizeFsError(message, root)}` };
+            }
+        },
+    };
+}
+//# sourceMappingURL=grepTool.js.map

package/dist/src/fs/grepTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grepTool.js","sourceRoot":"","sources":["../../../src/fs/grepTool.ts"],"names":[],"mappings":"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"}

package/dist/src/fs/index.d.ts

@@ -0,0 +1,8 @@
+/** Public surface of the fs read tools (phase A). */
+import type { ClientTool } from '../core/types.js';
+export { workspaceRoot } from './workspaceGuard.js';
+export { MAX_TOOL_CALLS_PER_TURN } from './limits.js';
+/** The four read-only tools, jailed to `root`. Registration order = model-visible order. */
+/** The fs tool names — source of truth for context pruning's "prunable" check. */
+export declare const FS_TOOL_NAMES: ReadonlySet<string>;
+export declare function createFsTools(root: string): ClientTool[];

package/dist/src/fs/index.js

@@ -0,0 +1,13 @@
+import { createReadFileTool } from './readFileTool.js';
+import { createListDirTool } from './listDirTool.js';
+import { createGlobTool } from './globTool.js';
+import { createGrepTool } from './grepTool.js';
+export { workspaceRoot } from './workspaceGuard.js';
+export { MAX_TOOL_CALLS_PER_TURN } from './limits.js';
+/** The four read-only tools, jailed to `root`. Registration order = model-visible order. */
+/** The fs tool names — source of truth for context pruning's "prunable" check. */
+export const FS_TOOL_NAMES = new Set(['read_file', 'list_dir', 'glob', 'grep']);
+export function createFsTools(root) {
+    return [createReadFileTool(root), createListDirTool(root), createGlobTool(root), createGrepTool(root)];
+}
+//# sourceMappingURL=index.js.map

package/dist/src/fs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/fs/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAEtD,4FAA4F;AAC5F,kFAAkF;AAClF,MAAM,CAAC,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAErG,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,iBAAiB,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;AACzG,CAAC"}

package/dist/src/fs/limits.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Every cap and over-limit behavior for the fs read tools, in one auditable place.
+ * These are BILLING decisions, not implementation details, and the policy splits
+ * by content cost (2026-07-19 revision, Claude Code parity):
+ * - READ content (expensive, thousands of tokens): over-limit = ERROR (~100 bytes)
+ *   — inherited from Claude Code's reverted experiment (#21841): truncation
+ *   lowered tool error rates but RAISED mean token cost.
+ * - DISCOVERY results (cheap path/match lists): over-limit = TRUNCATE + note —
+ *   erroring only wasted the model a retry round-trip.
+ */
+export declare const MAX_FILE_SIZE_BYTES: number;
+export declare const MAX_RANGED_FILE_SIZE_BYTES: number;
+export declare const MAX_READ_LINES = 2000;
+export declare const MAX_READ_OUTPUT_BYTES: number;
+export declare const MAX_LINE_CHARS = 2000;
+export declare const MAX_DIR_ENTRIES = 200;
+export declare const MAX_GLOB_RESULTS = 100;
+export declare const MAX_GLOB_SCAN = 2000;
+export declare const MAX_GREP_MATCHES = 100;
+export declare const MAX_GREP_LINE_CHARS = 200;
+export declare const GREP_TIMEOUT_MS = 5000;
+export declare const MAX_TOOL_CALLS_PER_TURN = 15;
+/** Directory names never listed, walked, or matched (noise + huge). */
+export declare const IGNORED_DIRS: Set<string>;
+/** File names never listed or matched. */
+export declare const IGNORED_FILES: Set<string>;
+export declare const BUDGET_EXHAUSTED_MESSAGE = "Tool budget for this turn is exhausted. Summarize with what you have.";
+export declare const PRUNE_TRIGGER_TOKENS = 30000;
+export declare const PRUNE_KEEP_RECENT = 3;
+export declare const PRUNE_MIN_CONTENT_BYTES = 200;
+export declare const PRUNE_PLACEHOLDER = "[Old tool result cleared to save context \u2014 re-run the tool if needed.]";
+export declare const DEFAULT_SESSION_MAX_CREDITS = 4000;
+export declare const MEDIA_GRACE_WAIT_MS = 45000;
+export declare const MEDIA_POLL_HINT_SECONDS = 0;

package/dist/src/fs/limits.js

@@ -0,0 +1,74 @@
+/**
+ * Every cap and over-limit behavior for the fs read tools, in one auditable place.
+ * These are BILLING decisions, not implementation details, and the policy splits
+ * by content cost (2026-07-19 revision, Claude Code parity):
+ * - READ content (expensive, thousands of tokens): over-limit = ERROR (~100 bytes)
+ *   — inherited from Claude Code's reverted experiment (#21841): truncation
+ *   lowered tool error rates but RAISED mean token cost.
+ * - DISCOVERY results (cheap path/match lists): over-limit = TRUNCATE + note —
+ *   erroring only wasted the model a retry round-trip.
+ */
+export const MAX_FILE_SIZE_BYTES = 1024 * 1024; // read_file / grep skip-threshold
+export const MAX_RANGED_FILE_SIZE_BYTES = 8 * 1024 * 1024; // absolute ceiling — refuse even range reads above this
+// NOTE 2026-07-19: the old DEFAULT_READ_LINES (1000-line default-read error) was removed.
+// Dogfood showed it costs MORE than it saves: the model reads the whole file anyway via
+// error + N range reads (4 round-trips for a 2226-line file). Default reads are now bounded
+// by MAX_FILE_SIZE_BYTES (pre-read) and MAX_READ_OUTPUT_BYTES (post-build) only —
+// Claude Code FileReadTool parity. Over-limit=error stays for READ content (expensive);
+// discovery tools (glob/grep) truncate with a note instead (cheap path lists).
+export const MAX_READ_LINES = 2000; // read_file explicit-limit ceiling
+// 100KB ≈ 25k tokens — Claude Code FileReadTool's output-token cap, live-validated
+// 2026-07-19: the old 256KB cap let a 118KB package-lock.json burn ~33k tokens
+// that then sat in the session context, re-billed on every subsequent turn.
+export const MAX_READ_OUTPUT_BYTES = 100 * 1024; // hard output ceiling for any read_file call
+export const MAX_LINE_CHARS = 2000; // single line cap (truncated with marker)
+export const MAX_DIR_ENTRIES = 200; // list_dir
+export const MAX_GLOB_RESULTS = 100; // glob: shown results (over-cap truncates with a note)
+export const MAX_GLOB_SCAN = 2000; // glob: hard bound on matches collected before sorting
+export const MAX_GREP_MATCHES = 100; // grep
+export const MAX_GREP_LINE_CHARS = 200; // grep match line preview cap
+// grep executes MODEL-supplied regex; JS RegExp backtracks, so an evil pattern
+// ((a+)+$) can hang V8 forever. Matching therefore runs inside a vm script whose
+// timeout (V8 TerminateExecution) interrupts even mid-backtrack — verified live
+// 2026-07-20. The budget is per grep CALL, and because vm runs synchronously it
+// also bounds the worst-case main-thread stall: Claude Code allows 20s but its
+// ripgrep runs out-of-process; in-process, 5s keeps a frozen TUI recoverable.
+export const GREP_TIMEOUT_MS = 5_000;
+export const MAX_TOOL_CALLS_PER_TURN = 15; // TurnLoop budget (counts ALL tools)
+/** Directory names never listed, walked, or matched (noise + huge). */
+export const IGNORED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.next',
+    '__pycache__',
+    '.venv',
+]);
+/** File names never listed or matched. */
+export const IGNORED_FILES = new Set(['.DS_Store']);
+export const BUDGET_EXHAUSTED_MESSAGE = 'Tool budget for this turn is exhausted. Summarize with what you have.';
+// --- Context pruning (microcompact, spec 2026-07-19-context-pruning-design.md) ---
+// Trigger-based batch clearing, NEVER a sliding window: editing an old message
+// invalidates the upstream prompt cache from that point, so continuous pruning
+// would re-bill the whole suffix at full upstream price every turn. User-facing
+// billing is flat per prompt_tokens (verified in yanfa UsageCapture/settlement),
+// so pruning is pure user savings; cache stability protects latency and margin.
+export const PRUNE_TRIGGER_TOKENS = 30_000; // last prompt_tokens above this → prune batch
+export const PRUNE_KEEP_RECENT = 3; // most recent fs results kept intact
+export const PRUNE_MIN_CONTENT_BYTES = 200; // smaller results are cheaper kept than cleared
+export const PRUNE_PLACEHOLDER = '[Old tool result cleared to save context — re-run the tool if needed.]';
+// --- Unattended media budget (spec 2026-07-19-mcp-media-tools-design.md) ---
+// MCP and exec have no human confirmation dialog; the session budget IS the spend
+// control. 4000 ≈ ten default-model images (400 each) or 2-3 mid-range videos
+// (500-1500 each) — measured live via `--estimate` on 2026-07-19.
+export const DEFAULT_SESSION_MAX_CREDITS = 4000;
+// Server-side wait slices: generate AND check_task each absorb up to this much waiting
+// before answering "generating". Real-client finding (2026-07-20, headless Claude Code):
+// agents without a sleep capability END THEIR TURN when told to wait between polls,
+// orphaning the paid task — so the server waits and the agent re-calls immediately
+// (poll hint 0). 45s slices stay inside conservative client timeouts; Claude Code's own
+// MCP tool timeout defaults to ~27.8h, but other clients are far stingier.
+export const MEDIA_GRACE_WAIT_MS = 45_000;
+export const MEDIA_POLL_HINT_SECONDS = 0; // re-call immediately — the server does the waiting
+//# sourceMappingURL=limits.js.map

package/dist/src/fs/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../../src/fs/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,kCAAkC;AAClF,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,wDAAwD;AACnH,0FAA0F;AAC1F,wFAAwF;AACxF,4FAA4F;AAC5F,kFAAkF;AAClF,wFAAwF;AACxF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,CAAC,mCAAmC;AACvE,mFAAmF;AACnF,+EAA+E;AAC/E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,6CAA6C;AAC9F,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,CAAC,0CAA0C;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC,CAAC,WAAW;AAC/C,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC,CAAC,uDAAuD;AAC5F,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC,CAAC,uDAAuD;AAC1F,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC,CAAC,OAAO;AAC5C,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC,CAAC,8BAA8B;AACtE,+EAA+E;AAC/E,iFAAiF;AACjF,gFAAgF;AAChF,gFAAgF;AAChF,+EAA+E;AAC/E,8EAA8E;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AACrC,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC,CAAC,qCAAqC;AAEhF,uEAAuE;AACvE,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC;IAClC,cAAc;IACd,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;IACP,aAAa;IACb,OAAO;CACR,CAAC,CAAC;AACH,0CAA0C;AAC1C,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;AAEpD,MAAM,CAAC,MAAM,wBAAwB,GACnC,uEAAuE,CAAC;AAE1E,oFAAoF;AACpF,+EAA+E;AAC/E,+EAA+E;AAC/E,gFAAgF;AAChF,iFAAiF;AACjF,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,CAAC,8CAA8C;AAC1F,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,CAAC,qCAAqC;AACzE,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC,CAAC,gDAAgD;AAC5F,MAAM,CAAC,MAAM,iBAAiB,GAC5B,wEAAwE,CAAC;AAE3E,8EAA8E;AAC9E,kFAAkF;AAClF,8EAA8E;AAC9E,kEAAkE;AAClE,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAChD,uFAAuF;AACvF,yFAAyF;AACzF,oFAAoF;AACpF,mFAAmF;AACnF,wFAAwF;AACxF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAC1C,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,CAAC,oDAAoD"}

package/dist/src/fs/listDirTool.d.ts

@@ -0,0 +1,2 @@
+import type { ClientTool } from '../core/types.js';
+export declare function createListDirTool(root: string): ClientTool;

package/dist/src/fs/listDirTool.js

@@ -0,0 +1,68 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { GuardError, resolveInWorkspace, sanitizeFsError } from './workspaceGuard.js';
+import { IGNORED_DIRS, IGNORED_FILES, MAX_DIR_ENTRIES } from './limits.js';
+/** 14 → "14B", 2048 → "2.0KB", 3145728 → "3.0MB". */
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+export function createListDirTool(root) {
+    return {
+        name: 'list_dir',
+        readOnly: true,
+        description: 'List the entries of a directory inside the workspace (the directory the CLI was started in). ' +
+            'Directories are suffixed with "/"; files include their size, so questions like "the largest file" ' +
+            'are answerable directly. Common noise (node_modules, .git, dist) is omitted. ' +
+            'Use this to explore before reading files.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Directory to list, relative to the workspace root. Defaults to ".".',
+                },
+            },
+        },
+        async execute(args) {
+            const userPath = typeof args.path === 'string' && args.path.trim() ? args.path : '.';
+            try {
+                const dir = await resolveInWorkspace(root, userPath);
+                const stat = await fs.stat(dir);
+                if (!stat.isDirectory())
+                    return { error: `Not a directory: ${userPath}` };
+                const entries = (await fs.readdir(dir, { withFileTypes: true }))
+                    .filter((e) => !(e.isDirectory() ? IGNORED_DIRS.has(e.name) : IGNORED_FILES.has(e.name)));
+                if (entries.length > MAX_DIR_ENTRIES) {
+                    return {
+                        error: `Directory has ${entries.length} entries (>${MAX_DIR_ENTRIES}). List a subdirectory or use glob with a narrower pattern.`,
+                    };
+                }
+                entries.sort((a, b) => a.isDirectory() === b.isDirectory() ? a.name.localeCompare(b.name) : a.isDirectory() ? -1 : 1);
+                const lines = await Promise.all(entries.map(async (e) => {
+                    if (e.isDirectory())
+                        return `${e.name}/`;
+                    try {
+                        const s = await fs.stat(path.join(dir, e.name));
+                        return `${e.name}  ${formatSize(s.size)}`;
+                    }
+                    catch {
+                        // Dangling symlink or a file deleted mid-listing: name only, never fatal.
+                        return e.name;
+                    }
+                }));
+                return { summary: `${lines.length} entries`, content: lines.join('\n') };
+            }
+            catch (err) {
+                if (err instanceof GuardError)
+                    return { error: err.message };
+                const message = err instanceof Error ? err.message : String(err);
+                return { error: `list_dir failed: ${sanitizeFsError(message, root)}` };
+            }
+        },
+    };
+}
+//# sourceMappingURL=listDirTool.js.map

package/dist/src/fs/listDirTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listDirTool.js","sourceRoot":"","sources":["../../../src/fs/listDirTool.ts"],"names":[],"mappings":"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"}

package/dist/src/fs/readFileTool.d.ts

@@ -0,0 +1,2 @@
+import type { ClientTool } from '../core/types.js';
+export declare function createReadFileTool(root: string): ClientTool;

package/dist/src/fs/readFileTool.js

@@ -0,0 +1,102 @@
+import { promises as fs } from 'node:fs';
+import { GuardError, resolveInWorkspace, sanitizeFsError } from './workspaceGuard.js';
+import { MAX_FILE_SIZE_BYTES, MAX_LINE_CHARS, MAX_RANGED_FILE_SIZE_BYTES, MAX_READ_LINES, MAX_READ_OUTPUT_BYTES, } from './limits.js';
+/** NUL byte in the first 8KB → treat as binary (same heuristic as git). */
+function looksBinary(buf) {
+    return buf.subarray(0, 8192).includes(0);
+}
+export function createReadFileTool(root) {
+    return {
+        name: 'read_file',
+        readOnly: true,
+        description: 'Read a text file inside the workspace. Returns numbered lines ("cat -n" style) so you can cite line numbers. ' +
+            'Reads the whole file by default when it fits (file up to 1MB, output up to 100KB); for bigger files ' +
+            `read a range with offset/limit (up to ${MAX_READ_LINES} lines per read; range reads work on files up to 8MB). ` +
+            'For machine-generated files (lockfiles, minified bundles, large logs) read a small range or grep ' +
+            'instead of the whole file — their bulk rarely helps and the tokens are wasted. ' +
+            'Binary files cannot be read — images can be attached instead (@path in the TUI, --image in exec).',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path relative to the workspace root.' },
+                offset: { type: 'number', description: '1-based first line to read (default 1).' },
+                limit: {
+                    type: 'number',
+                    description: `Max lines to return (up to ${MAX_READ_LINES}). Omit to read the whole file.`,
+                },
+            },
+            required: ['path'],
+        },
+        async execute(args) {
+            if (typeof args.path !== 'string' || !args.path.trim()) {
+                return { error: 'Missing required "path" argument.' };
+            }
+            const explicitLimit = typeof args.limit === 'number' && args.limit > 0;
+            const offset = typeof args.offset === 'number' && args.offset >= 1 ? Math.floor(args.offset) : 1;
+            const limit = explicitLimit ? Math.floor(args.limit) : undefined;
+            if (explicitLimit && limit !== undefined && limit > MAX_READ_LINES) {
+                return {
+                    error: `Requested ${limit} lines (max ${MAX_READ_LINES} per read). Read in chunks with offset/limit.`,
+                };
+            }
+            try {
+                const file = await resolveInWorkspace(root, args.path);
+                const stat = await fs.stat(file);
+                if (stat.isDirectory())
+                    return { error: `Is a directory, not a file: ${args.path}` };
+                // A FIFO/socket/device would make fs.readFile hang forever waiting for a peer — and
+                // dispatch here is not abortable. Reject anything that isn't a plain file up front.
+                if (!stat.isFile())
+                    return { error: `Not a regular file: ${args.path}` };
+                if (explicitLimit) {
+                    if (stat.size > MAX_RANGED_FILE_SIZE_BYTES) {
+                        return {
+                            error: `File is ${stat.size} bytes (>8MB) — too large even for range reads. Use grep to locate the relevant part.`,
+                        };
+                    }
+                }
+                else if (stat.size > MAX_FILE_SIZE_BYTES) {
+                    return {
+                        error: `File is ${stat.size} bytes (>1MB limit). Use grep to find the relevant part, or read a line range with offset/limit.`,
+                    };
+                }
+                const buf = await fs.readFile(file);
+                if (looksBinary(buf)) {
+                    return {
+                        error: 'Binary file (not text). If this is an image, attach it instead (@path in the TUI, --image in exec).',
+                    };
+                }
+                const all = buf.toString('utf8').split('\n');
+                // Trailing newline produces a phantom empty last element; drop it.
+                if (all.length > 1 && all[all.length - 1] === '')
+                    all.pop();
+                // No default line-count gate: a default read returns the whole file, bounded by the
+                // 1MB pre-read and 100KB output checks. Erroring at N lines just forced the model
+                // into error + multiple range reads for the same total tokens (2026-07-19 dogfood).
+                const slice = limit === undefined ? all.slice(offset - 1) : all.slice(offset - 1, offset - 1 + limit);
+                if (slice.length === 0)
+                    return { error: `Offset ${offset} is past the end (${all.length} lines).` };
+                const content = slice
+                    .map((line, i) => {
+                    const text = line.length > MAX_LINE_CHARS ? `${line.slice(0, MAX_LINE_CHARS)}… [line truncated]` : line;
+                    return `${String(offset + i).padStart(6)}\t${text}`;
+                })
+                    .join('\n');
+                const outputBytes = Buffer.byteLength(content, 'utf8');
+                if (outputBytes > MAX_READ_OUTPUT_BYTES) {
+                    return {
+                        error: `This range is ${outputBytes} bytes (max ${MAX_READ_OUTPUT_BYTES} per read). Request a smaller range with offset/limit.`,
+                    };
+                }
+                return { summary: `${slice.length} lines`, content };
+            }
+            catch (err) {
+                if (err instanceof GuardError)
+                    return { error: err.message };
+                const message = err instanceof Error ? err.message : String(err);
+                return { error: `read_file failed: ${sanitizeFsError(message, root)}` };
+            }
+        },
+    };
+}
+//# sourceMappingURL=readFileTool.js.map

package/dist/src/fs/readFileTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readFileTool.js","sourceRoot":"","sources":["../../../src/fs/readFileTool.ts"],"names":[],"mappings":"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"}

package/dist/src/fs/walk.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Depth-first file walker shared by glob and grep. Yields regular files only,
+ * with workspace-relative paths. Skips IGNORED_DIRS/IGNORED_FILES. Symlinks —
+ * file or directory — are never yielded or followed (Dirent.isFile() is false
+ * for them): consumers read yielded paths directly without a guard re-check,
+ * so a yielded symlink could leak content from outside the workspace.
+ */
+export declare function walkFiles(root: string, startDir: string): AsyncGenerator<{
+    abs: string;
+    rel: string;
+}>;

package/dist/src/fs/walk.js

@@ -0,0 +1,38 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { IGNORED_DIRS, IGNORED_FILES } from './limits.js';
+/**
+ * Depth-first file walker shared by glob and grep. Yields regular files only,
+ * with workspace-relative paths. Skips IGNORED_DIRS/IGNORED_FILES. Symlinks —
+ * file or directory — are never yielded or followed (Dirent.isFile() is false
+ * for them): consumers read yielded paths directly without a guard re-check,
+ * so a yielded symlink could leak content from outside the workspace.
+ */
+export async function* walkFiles(root, startDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(startDir, { withFileTypes: true });
+    }
+    catch {
+        // An unreadable directory (EPERM/EACCES on macOS ~/.Trash, vanished mid-walk)
+        // is skipped, not fatal — a home-dir workspace is full of these and one must
+        // not kill the whole glob/grep call (2026-07-19 TUI smoke finding).
+        return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+        const abs = path.join(startDir, e.name);
+        if (e.isDirectory()) {
+            if (IGNORED_DIRS.has(e.name))
+                continue;
+            yield* walkFiles(root, abs);
+        }
+        else if (e.isFile()) {
+            if (IGNORED_FILES.has(e.name))
+                continue;
+            yield { abs, rel: path.relative(root, abs) };
+        }
+        // symlinks (isSymbolicLink) are intentionally not followed here
+    }
+}
+//# sourceMappingURL=walk.js.map

package/dist/src/fs/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../../../src/fs/walk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,SAAS,CAC9B,IAAY,EACZ,QAAgB;IAEhB,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,8EAA8E;QAC9E,6EAA6E;QAC7E,oEAAoE;QACpE,OAAO;IACT,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACrD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YACpB,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;gBAAE,SAAS;YACvC,KAAK,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC9B,CAAC;aAAM,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;YACtB,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;gBAAE,SAAS;YACxC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;QAC/C,CAAC;QACD,gEAAgE;IAClE,CAAC;AACH,CAAC"}

package/dist/src/fs/workspaceGuard.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The ONLY safety module for the fs read tools. Every path a tool touches goes
+ * through resolveInWorkspace(); the tools themselves contain zero safety code.
+ * Phase-B write tools MUST route through this same gate.
+ */
+/** A path-safety violation or lookup failure, with a model-readable message. */
+export declare class GuardError extends Error {
+}
+/** The workspace root: realpath of the CLI start directory, anchored ONCE at startup. */
+export declare function workspaceRoot(cwd?: string): Promise<string>;
+/**
+ * Resolve a user/model-supplied path and prove it stays inside the workspace.
+ *
+ * Order matters: resolve against root -> realpath (follows symlinks) -> prefix
+ * check WITH a trailing separator (so `/ws-evil` cannot pass as `/ws`). The
+ * denial message never echoes the resolved real path — that would leak
+ * outside-workspace structure to the model.
+ */
+export declare function resolveInWorkspace(root: string, userPath: string): Promise<string>;
+/**
+ * Strip the workspace root out of a raw error message before it reaches the model. Node fs
+ * errors embed the absolute path (e.g. `EACCES: permission denied, open '/Users/eric/proj/f'`),
+ * which would otherwise leak the local machine's directory layout and username to the backend.
+ * Used by every tool's generic catch-all — GuardError messages never need this, they are
+ * already written to omit the resolved real path (see DENIED above).
+ */
+export declare function sanitizeFsError(message: string, root: string): string;