@datename/fastcode-termux 0.1.6-beta → 0.1.8-beta.0

package/src/agent/tools/readers.ts

@@ -1,16 +1,65 @@
+import { createReadStream } from "node:fs";
 import { open, readdir, stat } from "node:fs/promises";
-import { basename, extname, join } from "node:path";
+import { basename, extname, join, relative } from "node:path";
+import readline from "node:readline";
 import { createIgnore, isBinaryName } from "../ignore.js";
 import { createOutputBuffer } from "../limits.js";
 import { allowedRoots, isInsideAny, realpathOf, sandboxPath } from "./paths.js";
 
-export async function readMany(cwd: string, paths: string[]): Promise<string> {
+export interface ReadManyResult {
+    text: string;
+    truncated: boolean;
+    totalBytes: number;
+    returnedBytes: number;
+    filesRead: number;
+    filesSkipped: number;
+}
+
+export async function readManyResult(cwd: string, paths: string[], maxBytes = readManyMaxBytes()): Promise<ReadManyResult> {
     const blocks: string[] = [];
+    let used = 0;
+    let totalBytes = 0;
+    let filesRead = 0;
+    let truncated = false;
     for (const path of paths) {
+        if (used >= maxBytes) {
+            truncated = true;
+            break;
+        }
         const file = sandboxPath(cwd, path);
-        blocks.push(`### ${file}\n${await readTextFile(file)}`);
+        const result = await readTextFileResult(file, maxBytes - used);
+        totalBytes += result.totalBytes;
+        const block = `### ${file}\n${result.text}`;
+        const blockBytes = Buffer.byteLength(block, "utf8");
+        if (used + blockBytes > maxBytes) {
+            const allowed = Math.max(0, maxBytes - used);
+            const clipped = Buffer.from(block, "utf8").subarray(0, allowed).toString("utf8");
+            blocks.push(`${clipped}\n[... read_many budget exhausted at ${maxBytes} bytes ...]`);
+            used = maxBytes;
+            filesRead += 1;
+            truncated = true;
+            break;
+        }
+        blocks.push(block);
+        used += blockBytes;
+        filesRead += 1;
+        if (result.truncated)
+            truncated = true;
     }
-    return blocks.join("\n\n");
+    if (filesRead < paths.length)
+        truncated = true;
+    return {
+        text: blocks.join("\n\n"),
+        truncated,
+        totalBytes,
+        returnedBytes: used,
+        filesRead,
+        filesSkipped: Math.max(0, paths.length - filesRead),
+    };
+}
+
+export async function readMany(cwd: string, paths: string[]): Promise<string> {
+    return (await readManyResult(cwd, paths)).text;
 }
 
 const CODE_EXT = new Set([
@@ -51,7 +100,7 @@ export async function listFiles(sandbox: string, root: string, maxDepth: number,
             let line = `${indent(depth + 1)}${entry.name}  (${formatSize(info.size)})`;
             const symbols = await fileSymbols(full, entry.name, info.size);
             if (symbols)
-                line += `  — ${symbols}`;
+                line += `  鈥?${symbols}`;
             out.line(line);
             if (out.full)
                 return;
@@ -104,67 +153,279 @@ export function formatSize(bytes: number): string {
     return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
 
-export async function grepFiles(sandbox: string, root: string, pattern: string, maxDepth: number): Promise<string> {
-    const re = new RegExp(pattern, "i");
-    const out = createOutputBuffer();
+export interface GrepOptions {
+    pattern: string;
+    flags?: string;
+    glob?: string;
+    context?: number;
+    maxResults?: number;
+    maxDepth?: number;
+    signal?: AbortSignal;
+}
+
+export interface GrepResult {
+    text: string;
+    truncated: boolean;
+    matchCount: number;
+    filesScanned: number;
+}
+
+export async function grepFiles(sandbox: string, root: string, options: GrepOptions): Promise<GrepResult> {
+    const re = new RegExp(options.pattern, options.flags ?? "i");
+    const maxResults = Math.max(1, options.maxResults ?? 200);
+    const context = Math.max(0, options.context ?? 0);
     const maxBytes = grepMaxBytes();
-    await walkWithin(sandbox, root, maxDepth, async (file, info) => {
+    const out = createOutputBuffer();
+    const globRe = options.glob ? globToRegExp(options.glob) : undefined;
+    let matchCount = 0;
+    let filesScanned = 0;
+    let truncated = false;
+    await walkWithin(sandbox, root, options.maxDepth ?? 4, async (file, info) => {
+        if (options.signal?.aborted)
+            throw Object.assign(new Error("grep aborted"), { code: "ABORTED" });
         if (!info.isFile())
             return;
         if (isBinaryName(basename(file)))
             return;
+        if (globRe) {
+            const rel = relative(root, file).replace(/\\/g, "/");
+            const target = options.glob && options.glob.includes("/") ? rel : basename(file);
+            if (!globRe.test(target))
+                return;
+        }
         if (info.size > maxBytes) {
             out.line(`${file}: skipped (${formatSize(info.size)} exceeds ${formatSize(maxBytes)})`);
             return !out.full;
         }
+        filesScanned += 1;
         try {
-            const text = await readTextFile(file, maxBytes);
-            const lines = text.split(/\r?\n/);
-            lines.forEach((line, index) => {
-                if (re.test(line))
-                    out.line(file + ":" + (index + 1) + ": " + line);
-            });
+            const result = await readTextFileResult(file, maxBytes);
+            if (result.binary)
+                return;
+            const lines = result.text.split(/\r?\n/);
+            const printed = new Set<number>();
+            for (let index = 0; index < lines.length; index += 1) {
+                if (!re.test(lines[index]))
+                    continue;
+                matchCount += 1;
+                const start = Math.max(0, index - context);
+                const end = Math.min(lines.length - 1, index + context);
+                for (let cursor = start; cursor <= end; cursor += 1) {
+                    if (printed.has(cursor) && cursor !== index)
+                        continue;
+                    printed.add(cursor);
+                    const isMatch = cursor === index;
+                    out.line(`${file}:${cursor + 1}${isMatch ? ": " : "- "}${lines[cursor]}`);
+                    if (out.full) {
+                        truncated = true;
+                        return false;
+                    }
+                }
+                if (matchCount >= maxResults) {
+                    truncated = true;
+                    return false;
+                }
+            }
         }
-        catch {
+        catch (error: any) {
+            if (error?.code === "ABORTED")
+                throw error;
             // Binary or unreadable files are skipped.
         }
         return !out.full;
     });
-    return out.value();
+    if (out.full)
+        truncated = true;
+    return { text: out.value(), truncated, matchCount, filesScanned };
 }
 
-export async function readTextFile(file: string, limit = readMaxBytes()): Promise<string> {
+function globToRegExp(glob: string): RegExp {
+    let source = "^";
+    for (let i = 0; i < glob.length; i += 1) {
+        const char = glob[i];
+        if (char === "*") {
+            if (glob[i + 1] === "*") {
+                source += ".*";
+                i += 1;
+                if (glob[i + 1] === "/")
+                    i += 1;
+            }
+            else {
+                source += "[^/]*";
+            }
+        }
+        else if (char === "?") {
+            source += "[^/]";
+        }
+        else if (/[.+^${}()|[\]\\]/.test(char)) {
+            source += "\\" + char;
+        }
+        else {
+            source += char;
+        }
+    }
+    return new RegExp(source + "$", "i");
+}
+
+export interface ReadTextResult {
+    text: string;
+    truncated: boolean;
+    totalLines?: number;
+    returnedLines: number;
+    totalBytes: number;
+    returnedBytes: number;
+    binary: boolean;
+}
+
+export async function readTextFileResult(file: string, limit = readMaxBytes()): Promise<ReadTextResult> {
     const info = await stat(file);
     if (!info.isFile())
-        throw new Error(`not a file: ${file}`);
+        throw Object.assign(new Error(`not a file: ${file}`), { code: "EISDIR" });
     const length = Math.min(info.size, limit);
     const handle = await open(file, "r");
     try {
         const buffer = Buffer.alloc(length);
         const { bytesRead } = await handle.read(buffer, 0, length, 0);
         const slice = buffer.subarray(0, bytesRead);
-        if (slice.subarray(0, Math.min(8192, slice.length)).includes(0))
-            return `[binary file omitted: ${file} (${info.size} bytes)]`;
+        if (slice.subarray(0, Math.min(8192, slice.length)).includes(0)) {
+            return {
+                text: `[binary file omitted: ${file} (${info.size} bytes)]`,
+                truncated: false,
+                totalLines: undefined,
+                returnedLines: 0,
+                totalBytes: info.size,
+                returnedBytes: 0,
+                binary: true,
+            };
+        }
         const text = slice.toString("utf8");
-        return info.size > length
-            ? `${text}\n[... truncated at ${length} of ${info.size} bytes; use grep or read a narrower file ...]`
-            : text;
+        const truncated = info.size > length;
+        const returnedLines = text ? text.split(/\r?\n/).length : 0;
+        return {
+            text,
+            truncated,
+            totalLines: truncated ? undefined : returnedLines,
+            returnedLines,
+            totalBytes: info.size,
+            returnedBytes: Buffer.byteLength(text, "utf8"),
+            binary: false,
+        };
     }
     finally {
         await handle.close();
     }
 }
 
+export interface ReadRangeResult {
+    text: string;
+    truncated: boolean;
+    totalLines: number;
+    returnedLines: number;
+    totalBytes: number;
+    returnedBytes: number;
+    scannedAll: boolean;
+    binary: boolean;
+}
+
+export async function readFileRange(file: string, offset: number, limit: number, options: { maxBytes?: number; scanMaxBytes?: number; signal?: AbortSignal } = {}): Promise<ReadRangeResult> {
+    const info = await stat(file);
+    if (!info.isFile())
+        throw Object.assign(new Error(`not a file: ${file}`), { code: "EISDIR" });
+    const probe = await readTextFileResult(file, 8192);
+    if (probe.binary) {
+        return {
+            text: probe.text,
+            truncated: false,
+            totalLines: 0,
+            returnedLines: 0,
+            totalBytes: info.size,
+            returnedBytes: 0,
+            scannedAll: true,
+            binary: true,
+        };
+    }
+    const start = Math.max(1, Math.floor(offset));
+    const count = Math.max(1, Math.floor(limit));
+    const maxBytes = options.maxBytes ?? readMaxBytes();
+    const scanMaxBytes = options.scanMaxBytes ?? readScanMaxBytes();
+    const collected: string[] = [];
+    let lineNo = 0;
+    let returnedBytes = 0;
+    let totalBytes = 0;
+    let truncated = false;
+    let scannedAll = true;
+    let sawRange = false;
+    const stream = createReadStream(file, { encoding: "utf8" });
+    const lines = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+        for await (const line of lines) {
+            if (options.signal?.aborted)
+                throw Object.assign(new Error("read aborted"), { code: "ABORTED" });
+            lineNo += 1;
+            totalBytes += Buffer.byteLength(line, "utf8") + 1;
+            if (lineNo >= start && collected.length < count) {
+                sawRange = true;
+                collected.push(line);
+                returnedBytes += Buffer.byteLength(line, "utf8") + 1;
+                if (returnedBytes > maxBytes) {
+                    truncated = true;
+                    scannedAll = false;
+                    break;
+                }
+            }
+            else if (lineNo > start + count - 1) {
+                truncated = true;
+            }
+            if (totalBytes > scanMaxBytes) {
+                truncated = true;
+                scannedAll = false;
+                break;
+            }
+        }
+    }
+    finally {
+        lines.close();
+        stream.destroy();
+    }
+    return {
+        text: collected.join("\n"),
+        truncated,
+        totalLines: lineNo,
+        returnedLines: sawRange ? collected.length : 0,
+        totalBytes: info.size,
+        returnedBytes,
+        scannedAll,
+        binary: false,
+    };
+}
+
+export async function readTextFile(file: string, limit = readMaxBytes()): Promise<string> {
+    const result = await readTextFileResult(file, limit);
+    return result.truncated
+        ? `${result.text}\n[... truncated at ${result.returnedBytes} of ${result.totalBytes} bytes; use read_file offset/limit, grep, or a narrower file ...]`
+        : result.text;
+}
+
 export function readMaxBytes(): number {
     const raw = Number(process.env["FASTCODE_READ_MAX_BYTES"]);
     return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 200_000;
 }
 
-function grepMaxBytes(): number {
+export function grepMaxBytes(): number {
     const raw = Number(process.env["FASTCODE_GREP_MAX_BYTES"]);
     return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 1_000_000;
 }
 
+export function readScanMaxBytes(): number {
+    const raw = Number(process.env["FASTCODE_READ_SCAN_MAX_BYTES"]);
+    return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 8_000_000;
+}
+
+export function readManyMaxBytes(): number {
+    const raw = Number(process.env["FASTCODE_READ_MANY_MAX_BYTES"]);
+    return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 400_000;
+}
+
 async function walkWithin(sandbox: string, root: string, maxDepth: number, visit: (file: string, info: any) => Promise<boolean | void>): Promise<void> {
     const roots = allowedRoots(sandbox).map((entry) => realpathOf(entry)).filter(Boolean) as string[];
     const ignore = createIgnore(sandbox);
@@ -192,6 +453,8 @@ async function walk(node: string, maxDepth: number, visit: (file: string, info:
         return;
     state.visited += 1;
     const insideSandbox = !state.roots || state.roots.length === 0 || isInsideAny(real, state.roots);
+    if (!insideSandbox)
+        return;
     let keepGoing: boolean | void = true;
     try {
         keepGoing = await visit(node, info);
@@ -201,7 +464,7 @@ async function walk(node: string, maxDepth: number, visit: (file: string, info:
     }
     if (keepGoing === false)
         return false;
-    if (!info.isDirectory() || depth >= maxDepth || !insideSandbox)
+    if (!info.isDirectory() || depth >= maxDepth)
         return;
     let entries;
     try {

package/src/agent/tools/replace_in_file.ts

@@ -1,7 +1,13 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { resolvePath } from "./paths.js";
 import type { Tool } from "./types.js";
-import { invalid, preparePath, requiredString } from "./validate.js";
+import { invalid, optionalNumber, preparePath, requiredString } from "./validate.js";
+
+function countOccurrences(source: string, find: string): number {
+    if (!find)
+        return 0;
+    return source.split(find).length - 1;
+}
 
 export const replaceInFileTool: Tool = {
     name: "replace_in_file",
@@ -11,8 +17,13 @@ export const replaceInFileTool: Tool = {
     prepare(call, ctx) {
         try {
             requiredString(call, "path");
-            requiredString(call, "find");
+            const find = requiredString(call, "find");
             requiredString(call, "replace");
+            if (!find)
+                return invalid("find must not be empty");
+            const expected = optionalNumber(call, "expectedMatches");
+            if (expected !== undefined && (expected < 1 || !Number.isInteger(expected)))
+                return invalid("expectedMatches must be a positive integer");
         }
         catch (err: any) {
             return invalid(err.message);
@@ -23,10 +34,33 @@ export const replaceInFileTool: Tool = {
         const file = resolvePath(ctx.cwd, call);
         const find = requiredString(call, "find");
         const replacement = requiredString(call, "replace");
+        const expected = optionalNumber(call, "expectedMatches");
         const source = await readFile(file, "utf8");
-        if (!source.includes(find))
-            return { ok: false, output: `text not found in ${file}` };
+        const count = countOccurrences(source, find);
+        if (count === 0) {
+            return {
+                ok: false,
+                output: `text not found in ${file}`,
+                code: "NOT_FOUND",
+                hint: "Read the file first and pass the exact current text.",
+                matches: 0,
+            };
+        }
+        if (expected !== undefined && count !== expected) {
+            return {
+                ok: false,
+                output: `expected ${expected} match(es) but found ${count} in ${file}; file unchanged`,
+                code: "INVALID_ARGS",
+                hint: "Update find or expectedMatches so the replacement is explicit.",
+                matches: count,
+            };
+        }
         await writeFile(file, source.split(find).join(replacement), "utf8");
-        return { ok: true, output: `replaced text in ${file}`, sideEffects: { touched: [file] } };
+        return {
+            ok: true,
+            output: `replaced ${count} occurrence(s) in ${file}`,
+            matches: count,
+            sideEffects: { touched: [file] },
+        };
     },
 };

package/src/agent/tools/shell.ts

@@ -1,7 +1,7 @@
 import type { ShellExecResult } from "../shell-session.js";
 import { executeShellCommand, pollShellSession } from "../shell-session.js";
 import type { Tool } from "./types.js";
-import { invalid, numberOption } from "./validate.js";
+import { invalid, normalizeTimeoutMs, numberOption } from "./validate.js";
 
 export const shellTool: Tool = {
     name: "shell",
@@ -26,7 +26,7 @@ export const shellTool: Tool = {
         const result = await executeShellCommand(call.command, ctx.cwd, {
             signal: ctx.signal,
             turn: ctx.turn,
-            timeoutMs: numberOption(call.timeoutMs, 120000),
+            timeoutMs: normalizeTimeoutMs(call.timeoutMs),
         });
         return formatExec(result);
     },

package/src/agent/tools/types.ts

@@ -2,12 +2,39 @@ export type StateScope = "call" | "turn" | "session";
 
 export type RevalidateKey = "trust" | "sandboxRoots" | "schema" | "modelCaps";
 
+export type ToolErrorCode =
+    | "ENOENT"
+    | "EACCES"
+    | "EEXIST"
+    | "ENOTDIR"
+    | "EISDIR"
+    | "EXDEV"
+    | "INVALID_ARGS"
+    | "SANDBOX_DENY"
+    | "APPROVAL_DENY"
+    | "EGRESS_DENY"
+    | "NOT_FOUND"
+    | "ABORTED"
+    | "UNKNOWN";
+
 export interface SideEffects {
   touched?: string[];
   created?: string[];
   removed?: string[];
 }
 
+export interface EgressAudit {
+  outlet: string;
+  target?: string;
+  rule: string;
+  mode: "audit" | "block";
+  wouldBlock: boolean;
+  code: "EGRESS_DENY";
+  reason: string;
+}
+
+import type { ApprovalResolver } from "../approval.js";
+
 export interface ToolCall {
   tool: string;
   [key: string]: any;
@@ -16,6 +43,17 @@ export interface ToolCall {
 export interface ToolResult {
   ok: boolean;
   output: string;
+  code?: ToolErrorCode;
+  hint?: string;
+  truncated?: boolean;
+  totalLines?: number;
+  returnedLines?: number;
+  totalBytes?: number;
+  returnedBytes?: number;
+  filesRead?: number;
+  filesSkipped?: number;
+  matches?: number;
+  egress?: EgressAudit;
   sideEffects?: SideEffects;
 }
 
@@ -23,9 +61,13 @@ export interface ToolCtx {
     cwd: string;
     signal?: AbortSignal;
     turn?: number;
+    requestApproval?: ApprovalResolver;
+    catalogHash?: string;
 }
 
-export type Prepared = { ok: true } | { ok: false; output: string };
+export type Prepared =
+    | { ok: true }
+    | { ok: false; output: string; code?: ToolErrorCode; hint?: string };
 
 export interface ApprovalHints {
   mayRequireApproval: boolean;

package/src/agent/tools/validate.ts

@@ -1,8 +1,9 @@
+import { debugLog } from "../../lib/debug.js";
 import { sandboxPath } from "./paths.js";
-import type { Prepared, ToolCall } from "./types.js";
+import type { Prepared, ToolCall, ToolErrorCode } from "./types.js";
 
-export function invalid(output: string): Prepared {
-    return { ok: false, output };
+export function invalid(output: string, code: ToolErrorCode = "INVALID_ARGS", hint?: string): Prepared {
+    return { ok: false, output, code, ...(hint ? { hint } : {}) };
 }
 
 export function requiredString(call: ToolCall, key: string): string {
@@ -24,12 +25,80 @@ export function numberOption(value: any, fallback: number): number {
     return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
 
+export function optionalNumber(call: ToolCall, key: string): number | undefined {
+    const value = call[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw new Error(`${key} must be a finite number`);
+    return value;
+}
+
+export function clampInt(value: number | undefined, fallback: number, min: number, max: number): number {
+    if (value === undefined)
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}
+
+export function booleanOption(value: any, fallback = false): boolean {
+    return typeof value === "boolean" ? value : fallback;
+}
+
+export const MAX_TIMEOUT_MS = 2147483647;
+
+/**
+ * Normalize a tool `timeoutMs` value.
+ *
+ * Only `null`/`undefined` mean "not specified". Any other non-number, NaN,
+ * Infinity, or negative value is a caller error and must be surfaced instead
+ * of silently falling back. Large finite values are clamped to the
+ * `setTimeout` ceiling (2^31-1) rather than overflowing to 1ms.
+ */
+export function normalizeTimeoutMs(value: unknown, fallback = 120000): number {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "number") {
+        throw new TypeError(`timeoutMs must be a finite number; received ${describeValue(value)}`);
+    }
+    if (!Number.isFinite(value)) {
+        throw new TypeError(`timeoutMs must be a finite number; received ${describeValue(value)}`);
+    }
+    if (value < 0) {
+        throw new TypeError(`timeoutMs must not be negative; received ${describeValue(value)}`);
+    }
+    const floored = Math.floor(value);
+    const clamped = Math.min(floored, MAX_TIMEOUT_MS);
+    if (clamped !== floored)
+        debugLog("timeout", `timeoutMs ${value} clamped to ${clamped}`);
+    return clamped;
+}
+
+function describeValue(value: unknown): string {
+    if (typeof value === "string")
+        return `string ${JSON.stringify(value)}`;
+    if (typeof value === "number")
+        return String(value);
+    if (typeof value === "bigint")
+        return `bigint ${value}n`;
+    if (typeof value === "object" && value !== null) {
+        try {
+            return `object ${JSON.stringify(value)}`;
+        }
+        catch {
+            return "object";
+        }
+    }
+    return String(value);
+}
+
 export function preparePath(cwd: string, raw: string): Prepared {
     try {
         sandboxPath(cwd, raw);
         return { ok: true };
     }
     catch (err: any) {
-        return invalid(err?.message ?? String(err));
+        const message = err?.message ?? String(err);
+        const code = /outside sandbox/i.test(message) ? "SANDBOX_DENY" : "INVALID_ARGS";
+        return invalid(message, code, /outside sandbox/i.test(message) ? "Use a path inside the project or an allowed root." : undefined);
     }
 }

package/src/agent/tools/write_file.ts

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import { resolvePath } from "./paths.js";
@@ -21,8 +22,9 @@ export const writeFileTool: Tool = {
     },
     async execute(call, ctx) {
         const file = resolvePath(ctx.cwd, call);
+        const existed = existsSync(file);
         await mkdir(dirname(file), { recursive: true });
         await writeFile(file, requiredString(call, "content"), "utf8");
-        return { ok: true, output: `wrote ${file}`, sideEffects: { touched: [file] } };
+        return { ok: true, output: `wrote ${file}`, sideEffects: existed ? { touched: [file] } : { created: [file] } };
     },
 };