frely-cli 0.23.9 → 0.23.11

package/dist/agent/run.js

@@ -0,0 +1,233 @@
+import { spawn } from "node:child_process";
+import { cliLaunchArguments } from "../cli-launch.js";
+import { ClientToolsUnsupportedError, invokeInstalledAgent, openInstalledAgentSession, SkillAccessError, } from "../skill/access.js";
+import { addUsage, createRun, effectiveStatus, listRuns, processAlive, readRun, resolveRun, resumable, writeRun, } from "./run-store.js";
+import { READ_TOOLS, WorkspaceReadBridge } from "./workspace-read.js";
+const MAX_TASK_BYTES = 128 * 1024;
+const OVERVIEW_HEADER = "\n\n---\nLocal workspace (read-only file tools are available: read what you need, do not guess). Readable files:\n";
+export const defaultRunDeps = {
+    openSession: (distributionId) => openInstalledAgentSession({ distributionId }),
+    invokePlain: async (distributionId, task, signal) => {
+        const result = await invokeInstalledAgent({ distributionId, task, signal });
+        return { text: result.text, modelId: result.modelId, ...("usage" in result && result.usage ? { usage: result.usage } : {}) };
+    },
+    spawnWorker: (runId) => {
+        // Detached, so Ctrl-C, a host command timeout or a killed parent does not stop the call it is waiting for.
+        const launch = cliLaunchArguments(process.argv[1] ?? "", ["agent", "__worker", runId]);
+        spawn(launch[0], launch.slice(1), { detached: true, stdio: "ignore", windowsHide: true, env: process.env }).unref();
+    },
+    stderr: (text) => { process.stderr.write(text); },
+    pollMs: 400,
+};
+/** Create the run record, start the detached worker and wait for the end. The same call also serves `frely agent result --wait`. */
+export async function startRun(input, deps = defaultRunDeps) {
+    if (!input.task.trim() || Buffer.byteLength(input.task, "utf8") > MAX_TASK_BYTES)
+        throw new SkillAccessError("input_invalid", "Agent input must be non-empty and at most 128 KiB.");
+    const record = await createRun({
+        distributionId: input.distributionId,
+        task: input.task,
+        ...(input.read === undefined ? {} : { readRoot: input.read.root, limits: input.read.limits }),
+    });
+    deps.stderr(`Run ${record.runId} started. If this command is cut off the run keeps going: frely agent result ${record.runId} --wait\n`);
+    deps.spawnWorker(record.runId);
+    return waitForRun(record.runId, deps);
+}
+/** Poll the local record until the run is no longer running; prints each newly read file to stderr. */
+export async function waitForRun(runId, deps = defaultRunDeps) {
+    const seen = new Set();
+    while (true) {
+        const record = await readRun(runId);
+        if (record === null)
+            throw new SkillAccessError("remote_call_failed", "The run record is no longer on this computer.");
+        for (const file of record.filesRead) {
+            if (!seen.has(file.path)) {
+                seen.add(file.path);
+                deps.stderr(`read ${file.path}\n`);
+            }
+        }
+        if (effectiveStatus(record) !== "running")
+            return { ...record, status: effectiveStatus(record) };
+        await new Promise((resolve) => setTimeout(resolve, deps.pollMs));
+    }
+}
+/** A finished run as the foreground command reports it: the result, or the error the call would have thrown. */
+export function runOutcome(record) {
+    if (record.status === "completed") {
+        return {
+            ok: true,
+            runId: record.runId,
+            distributionId: record.distributionId,
+            ...(record.modelId === undefined ? {} : { modelId: record.modelId }),
+            text: record.text ?? "",
+            ...(record.readRoot === undefined ? {} : { filesRead: record.filesRead, rounds: record.rounds.length }),
+            ...(record.usage.total_tokens > 0 ? { usage: record.usage } : {}),
+            ...(record.toolsUnsupported === true ? { toolsUnsupported: true } : {}),
+        };
+    }
+    throw runFailure(record);
+}
+export function runFailure(record) {
+    if (record.status === "interrupted") {
+        return new SkillAccessError("remote_call_failed", `The run was interrupted before it finished. Run \`frely agent result ${record.runId} --resume --wait\` to continue it; the interrupted round is billed again.`);
+    }
+    if (record.status === "cancelled")
+        return new SkillAccessError("remote_call_failed", `The run ${record.runId} was cancelled.`);
+    const code = (record.error?.code ?? "remote_call_failed");
+    return new SkillAccessError(code, record.error?.message ?? "The remote Frely Agent call failed.");
+}
+/** The state `frely agent result` and `frely agent runs` print for a run (no task text; the result text only when finished). */
+export function runSummary(record) {
+    const status = effectiveStatus(record);
+    return {
+        ok: status === "running" || status === "completed",
+        runId: record.runId,
+        status,
+        distributionId: record.distributionId,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        rounds: record.rounds.length,
+        filesRead: record.filesRead,
+        usage: record.usage,
+        ...(status === "completed" ? { text: record.text ?? "" } : {}),
+        ...(status === "completed" || record.error === undefined ? {} : { error: record.error }),
+        resumable: resumable(record),
+        ...(status === "running" ? { note: "Still running. Progress so far is listed; run `frely agent result <runId> --wait` to wait for the answer." } : {}),
+    };
+}
+export async function listRunSummaries() {
+    return (await listRuns()).slice(0, 20).map((record) => {
+        const { filesRead, usage, ...rest } = runSummary(record);
+        return { ...rest, filesRead: record.filesRead.length, totalTokens: usage.total_tokens };
+    });
+}
+/** Stop a run: ask its worker to abort the call (the server stops and settles what was used), or mark an orphaned record. */
+export async function cancelRun(target, deps = defaultRunDeps) {
+    const record = await resolveRun(target);
+    if (record.status !== "running")
+        return record;
+    if (processAlive(record.workerPid)) {
+        try {
+            process.kill(record.workerPid, "SIGTERM");
+        }
+        catch { /* it just ended */ }
+        for (let waited = 0; waited < 5000; waited += deps.pollMs) {
+            await new Promise((resolve) => setTimeout(resolve, deps.pollMs));
+            const current = await readRun(record.runId);
+            if (current !== null && current.status !== "running")
+                return current;
+        }
+    }
+    const latest = await readRun(record.runId) ?? record;
+    if (latest.status !== "running")
+        return latest;
+    return writeRun({ ...latest, status: "cancelled" });
+}
+/** Prepare an interrupted or failed run to continue with the items it already has, and start a worker for it. */
+export async function resumeRun(target, deps = defaultRunDeps) {
+    const record = await resolveRun(target);
+    if (!resumable(record))
+        throw new Error(effectiveStatus(record) === "running" ? "This run is still running." : "This run cannot be resumed.");
+    const { error: _error, workerPid: _pid, ...rest } = record;
+    const next = await writeRun({ ...rest, status: "running", resumeCount: record.resumeCount + 1 });
+    deps.stderr(`Resuming run ${record.runId}. The round that was interrupted is billed again.\n`);
+    deps.spawnWorker(record.runId);
+    return next;
+}
+/** The worker side: runs the call (and the tool rounds) of one record, saving after every step. */
+export async function executeRun(runId, deps = defaultRunDeps, signal = new AbortController().signal) {
+    const loaded = await readRun(runId);
+    if (loaded === null || loaded.status !== "running")
+        return;
+    let record = await writeRun({ ...loaded, workerPid: process.pid });
+    const save = async (patch) => { record = await writeRun({ ...record, ...patch }); };
+    try {
+        if (record.readRoot === undefined) {
+            const result = await deps.invokePlain(record.distributionId, record.task, signal);
+            await save({ status: "completed", modelId: result.modelId, text: result.text });
+            return;
+        }
+        await runWithTools(record, save, () => record, deps, signal);
+    }
+    catch (error) {
+        if (signal.aborted) {
+            await save({ status: "cancelled" });
+            return;
+        }
+        const code = error instanceof SkillAccessError ? error.code : "remote_call_failed";
+        const message = error instanceof SkillAccessError ? error.message : "The remote Frely Agent call failed.";
+        await save({ status: "failed", error: { code, message } });
+    }
+}
+async function runWithTools(start, save, current, deps, signal) {
+    const limits = start.limits;
+    if (limits === undefined || start.readRoot === undefined)
+        throw new SkillAccessError("input_invalid", "The run has no workspace.");
+    const bridge = await WorkspaceReadBridge.open(start.readRoot, limits);
+    bridge.restore({ usedBytes: start.bridge?.usedBytes ?? 0, roundsAnswered: start.bridge?.roundsAnswered ?? 0, filesRead: start.filesRead });
+    const task = await withOverview(start.task, bridge);
+    const session = await deps.openSession(start.distributionId);
+    await save({ modelId: session.modelId });
+    const hardCap = limits.maxRounds + 3;
+    while (true) {
+        if (signal.aborted)
+            throw new Error("aborted");
+        const items = [...current().items];
+        const pending = unansweredCalls(items);
+        if (pending.length > 0) {
+            const outputs = await bridge.answerRound(pending);
+            for (const output of outputs)
+                items.push({ type: "function_call_output", call_id: output.callId, output: output.output });
+            await save({ items, filesRead: bridge.filesRead(), bridge: { usedBytes: bridge.state().usedBytes, roundsAnswered: bridge.state().roundsAnswered } });
+        }
+        if (current().rounds.length >= hardCap)
+            throw new SkillAccessError("remote_call_failed", "The Agent kept asking for files after the read budget was used up.");
+        const startedAt = new Date().toISOString();
+        let turn;
+        try {
+            turn = await session.turn({ task, tools: READ_TOOLS, items, signal });
+        }
+        catch (error) {
+            if (error instanceof ClientToolsUnsupportedError && current().rounds.length === 0) {
+                // The Agent takes no caller tools: do the plain single call, as if --read had not been given.
+                const result = await deps.invokePlain(start.distributionId, start.task, signal);
+                await save({ status: "completed", modelId: result.modelId, text: result.text, toolsUnsupported: true });
+                return;
+            }
+            throw error;
+        }
+        const round = {
+            n: current().rounds.length + 1,
+            ...(turn.requestId === undefined ? {} : { requestId: turn.requestId }),
+            startedAt,
+            endedAt: new Date().toISOString(),
+            toolCalls: turn.status === "tool_calls" ? turn.calls.map((call) => call.name) : [],
+            ...(turn.usage === undefined ? {} : { usage: turn.usage }),
+        };
+        const usage = addUsage(current().usage, turn.usage);
+        if (turn.status === "completed") {
+            await save({ status: "completed", text: turn.text, rounds: [...current().rounds, round], usage });
+            return;
+        }
+        await save({ rounds: [...current().rounds, round], usage, items: [...items, ...turn.items] });
+    }
+}
+function unansweredCalls(items) {
+    const answered = new Set(items.flatMap((item) => (item.type === "function_call_output" ? [item.call_id] : [])));
+    return items.flatMap((item) => (item.type === "function_call" && !answered.has(item.call_id) ? [{ callId: item.call_id, name: item.name, arguments: item.arguments }] : []));
+}
+/** Task plus the path tree of the readable files, kept inside the 128 KiB input limit. */
+async function withOverview(task, bridge) {
+    const room = MAX_TASK_BYTES - Buffer.byteLength(task, "utf8") - Buffer.byteLength(OVERVIEW_HEADER, "utf8");
+    if (room < 256)
+        return task;
+    const overview = await bridge.overview(Math.min(8 * 1024, room));
+    return overview === "" ? task : `${task}${OVERVIEW_HEADER}${overview}`;
+}
+/** Entry of `frely agent __worker <runId>`: cancel on SIGTERM, ignore the terminal hang-up. */
+export async function workerMain(runId, deps = defaultRunDeps) {
+    const controller = new AbortController();
+    process.on("SIGTERM", () => controller.abort());
+    process.on("SIGHUP", () => undefined);
+    await executeRun(runId, deps, controller.signal);
+}
+//# sourceMappingURL=run.js.map

package/dist/agent/run.js.map

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

package/dist/agent/workspace-read.d.ts

@@ -0,0 +1,78 @@
+import type { CallerToolDefinition } from "../skill/router.js";
+/** One tool result is cut at this size (the Agent runtime rejects larger caller tool outputs). */
+export declare const TOOL_OUTPUT_LIMIT_BYTES: number;
+export declare const DEFAULT_TOTAL_READ_BYTES: number;
+export declare const DEFAULT_MAX_ROUNDS = 16;
+export interface ReadLimits {
+    /** Total tool output handed to the Agent in one run. */
+    readonly totalBytes: number;
+    /** Rounds in which tool calls are answered; later calls get "budget exhausted". */
+    readonly maxRounds: number;
+}
+export declare const DEFAULT_READ_LIMITS: ReadLimits;
+export interface FileRead {
+    readonly path: string;
+    readonly bytes: number;
+}
+/**
+ * Read-only tools, with the same names and parameters as the FrelyMCP workspace tools. They run on this computer; the Agent only sees
+ * what a call returns.
+ */
+export declare const READ_TOOLS: readonly CallerToolDefinition[];
+/**
+ * Why a workspace path never leaves this computer, or null. Applies to every read-only tool result: git internals, environment files,
+ * key material, package-manager credentials. Gitignored files and binaries are checked separately (they need git and the file content).
+ */
+export declare function localDenyReason(relativePath: string): string | null;
+/** Which of these workspace-relative paths git ignores. Outside a git repository nothing is ignored. */
+export declare function gitIgnoredPaths(root: string, paths: readonly string[]): Promise<Set<string>>;
+/** The repository root for `--read` without a directory: the git top level of the current directory, else the directory itself. */
+export declare function defaultReadRoot(cwd: string): Promise<string>;
+export declare class WorkspaceReadBridge {
+    private readonly workspace;
+    readonly limits: ReadLimits;
+    private used;
+    private roundsAnswered;
+    private readonly reads;
+    private constructor();
+    static open(root: string, limits?: ReadLimits): Promise<WorkspaceReadBridge>;
+    get root(): string;
+    /** Restore the counters of an earlier part of the same run (resume). */
+    restore(state: {
+        readonly usedBytes: number;
+        readonly roundsAnswered: number;
+        readonly filesRead: readonly FileRead[];
+    }): void;
+    state(): {
+        usedBytes: number;
+        roundsAnswered: number;
+        filesRead: FileRead[];
+    };
+    filesRead(): FileRead[];
+    /** True once the Agent has used up the round budget; its next tool calls only get "budget exhausted". */
+    get roundBudgetSpent(): boolean;
+    /** Answer one round of calls. Never throws: a failure is the tool's output. Returns `onRead(path)` events through `log`. */
+    answerRound(calls: readonly {
+        callId: string;
+        name: string;
+        arguments: string;
+    }[], log?: (path: string) => void): Promise<{
+        callId: string;
+        output: string;
+    }[]>;
+    private exhaustedMessage;
+    private run;
+    private sanitize;
+    private noteRead;
+    private dispatch;
+    private ignored;
+    /** Drop denied and gitignored entries from a listing. */
+    private visible;
+    /**
+     * A path tree of the files the Agent may read, cut at `maxBytes`: the first thing it gets, so it can choose what to open. Uses
+     * `git ls-files` (tracked and untracked, not ignored) in a repository, else a bounded walk.
+     */
+    overview(maxBytes?: number): Promise<string>;
+}
+/** Cut at a byte limit on a character boundary, saying so, so the Agent knows to ask for a line range. */
+export declare function limitBytes(text: string, limit: number): string;

package/dist/agent/workspace-read.js

@@ -0,0 +1,292 @@
+import { execFile, spawn } from "node:child_process";
+import { basename } from "node:path";
+import { promisify } from "node:util";
+import { Workspace } from "../runtime/workspace.js";
+const execute = promisify(execFile);
+/** One tool result is cut at this size (the Agent runtime rejects larger caller tool outputs). */
+export const TOOL_OUTPUT_LIMIT_BYTES = 64 * 1024;
+export const DEFAULT_TOTAL_READ_BYTES = 1024 * 1024;
+export const DEFAULT_MAX_ROUNDS = 16;
+const OVERVIEW_LIMIT_BYTES = 8 * 1024;
+const DENIED = "denied by local policy";
+export const DEFAULT_READ_LIMITS = Object.freeze({ totalBytes: DEFAULT_TOTAL_READ_BYTES, maxRounds: DEFAULT_MAX_ROUNDS });
+/**
+ * Read-only tools, with the same names and parameters as the FrelyMCP workspace tools. They run on this computer; the Agent only sees
+ * what a call returns.
+ */
+export const READ_TOOLS = Object.freeze([
+    tool("workspace_info", "Describe the workspace and the limits of these read-only tools.", {}),
+    tool("list_directory", "List a directory of the workspace (path relative to the workspace root).", { path: { type: "string" } }),
+    tool("find_files", "Find files by glob pattern, for example **/*.ts.", { path: { type: "string" }, pattern: { type: "string" }, maxResults: { type: "integer" } }, ["pattern"]),
+    tool("search_files", "Search file contents for text (or a regular expression).", {
+        path: { type: "string" }, query: { type: "string" }, regex: { type: "boolean" }, caseSensitive: { type: "boolean" }, maxResults: { type: "integer" }, contextLines: { type: "integer" },
+    }, ["query"]),
+    tool("read_file", "Read a text file (up to 64 KiB per call; use startLine/endLine for the rest).", { path: { type: "string" }, startLine: { type: "integer" }, endLine: { type: "integer" } }, ["path"]),
+    tool("read_file_lines", "Read a line range of a text file.", { path: { type: "string" }, startLine: { type: "integer" }, endLine: { type: "integer" } }, ["path", "startLine"]),
+    tool("stat_path", "Size and type of a file or directory.", { path: { type: "string" } }, ["path"]),
+]);
+function tool(name, description, properties, required = []) {
+    return { type: "function", name, description, parameters: { type: "object", properties, required, additionalProperties: false } };
+}
+/**
+ * Why a workspace path never leaves this computer, or null. Applies to every read-only tool result: git internals, environment files,
+ * key material, package-manager credentials. Gitignored files and binaries are checked separately (they need git and the file content).
+ */
+export function localDenyReason(relativePath) {
+    const segments = relativePath.split(/[\\/]+/u).filter((segment) => segment !== "" && segment !== ".");
+    if (segments.some((segment) => segment.toLowerCase() === ".git"))
+        return DENIED;
+    const name = (segments.at(-1) ?? "").toLowerCase();
+    if (name === ".env" || name.startsWith(".env.") || name.startsWith(".env-"))
+        return DENIED;
+    if (/\.(pem|key|p12)$/u.test(name))
+        return DENIED;
+    if (/^id_/u.test(name))
+        return DENIED;
+    if (name === ".npmrc" || name === ".netrc" || name === ".pypirc")
+        return DENIED;
+    return null;
+}
+/** Which of these workspace-relative paths git ignores. Outside a git repository nothing is ignored. */
+export async function gitIgnoredPaths(root, paths) {
+    if (paths.length === 0)
+        return new Set();
+    return new Promise((resolve) => {
+        const child = spawn("git", ["-C", root, "check-ignore", "--stdin", "-z"], { stdio: ["pipe", "pipe", "ignore"], windowsHide: true });
+        const chunks = [];
+        child.stdout.on("data", (chunk) => chunks.push(chunk));
+        child.once("error", () => resolve(new Set()));
+        child.once("close", (code) => resolve(code === 0 ? new Set(Buffer.concat(chunks).toString("utf8").split("\0").filter(Boolean)) : new Set()));
+        child.stdin.once("error", () => undefined);
+        child.stdin.end(paths.join("\0") + "\0");
+    });
+}
+/** The repository root for `--read` without a directory: the git top level of the current directory, else the directory itself. */
+export async function defaultReadRoot(cwd) {
+    try {
+        const { stdout } = await execute("git", ["-C", cwd, "rev-parse", "--show-toplevel"], { windowsHide: true });
+        const top = stdout.trim();
+        return top === "" ? cwd : top;
+    }
+    catch {
+        return cwd;
+    }
+}
+export class WorkspaceReadBridge {
+    workspace;
+    limits;
+    used = 0;
+    roundsAnswered = 0;
+    reads = new Map();
+    constructor(workspace, limits) {
+        this.workspace = workspace;
+        this.limits = limits;
+    }
+    static async open(root, limits = DEFAULT_READ_LIMITS) {
+        return new WorkspaceReadBridge(await Workspace.open(root), limits);
+    }
+    get root() { return this.workspace.root; }
+    /** Restore the counters of an earlier part of the same run (resume). */
+    restore(state) {
+        this.used = state.usedBytes;
+        this.roundsAnswered = state.roundsAnswered;
+        for (const file of state.filesRead)
+            this.reads.set(file.path, file.bytes);
+    }
+    state() {
+        return { usedBytes: this.used, roundsAnswered: this.roundsAnswered, filesRead: this.filesRead() };
+    }
+    filesRead() {
+        return [...this.reads].map(([path, bytes]) => ({ path, bytes }));
+    }
+    /** True once the Agent has used up the round budget; its next tool calls only get "budget exhausted". */
+    get roundBudgetSpent() { return this.roundsAnswered >= this.limits.maxRounds; }
+    /** Answer one round of calls. Never throws: a failure is the tool's output. Returns `onRead(path)` events through `log`. */
+    async answerRound(calls, log = () => undefined) {
+        const exhausted = this.roundBudgetSpent;
+        if (!exhausted)
+            this.roundsAnswered += 1;
+        const outputs = [];
+        for (const call of calls) {
+            outputs.push({ callId: call.callId, output: exhausted || this.used >= this.limits.totalBytes ? this.exhaustedMessage() : await this.run(call, log) });
+        }
+        return outputs;
+    }
+    exhaustedMessage() {
+        return "budget exhausted: no more files can be read in this run. Answer with what you have already read.";
+    }
+    async run(call, log) {
+        let args;
+        try {
+            const parsed = call.arguments.trim() === "" ? {} : JSON.parse(call.arguments);
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+                throw new Error("not an object");
+            args = parsed;
+        }
+        catch {
+            return "error: arguments must be a JSON object";
+        }
+        let output;
+        try {
+            output = await this.dispatch(call.name, args, log);
+        }
+        catch (error) {
+            output = `error: ${this.sanitize(error instanceof Error ? error.message : "tool failed")}`;
+        }
+        output = limitBytes(output, Math.min(TOOL_OUTPUT_LIMIT_BYTES, Math.max(0, this.limits.totalBytes - this.used)));
+        this.used += Buffer.byteLength(output, "utf8");
+        return output;
+    }
+    sanitize(message) {
+        return message.split(this.workspace.root).join(".");
+    }
+    noteRead(path, bytes, log) {
+        if (!this.reads.has(path))
+            log(path);
+        this.reads.set(path, (this.reads.get(path) ?? 0) + bytes);
+    }
+    async dispatch(name, args, log) {
+        switch (name) {
+            case "workspace_info":
+                return JSON.stringify({
+                    workspace: basename(this.workspace.root),
+                    tools: READ_TOOLS.map((entry) => entry.name),
+                    limits: { toolOutputBytes: TOOL_OUTPUT_LIMIT_BYTES, totalBytes: this.limits.totalBytes, rounds: this.limits.maxRounds },
+                    note: "Read-only. Git internals, .env files, key files, files ignored by git and binary files are not readable.",
+                });
+            case "list_directory": {
+                const path = pathArg(args, "path", ".");
+                if (localDenyReason(path) !== null || await this.ignored(path))
+                    return DENIED;
+                const info = await this.workspace.statPath(path);
+                if (info.type !== "directory")
+                    return JSON.stringify(info);
+                const entries = await this.workspace.listDirectory(path);
+                const kept = await this.visible(entries.map((entry) => ({ entry, path: joinPath(path, entry.name) })));
+                return JSON.stringify(kept.map(({ entry }) => entry));
+            }
+            case "stat_path": {
+                const path = pathArg(args, "path");
+                if (localDenyReason(path) !== null || await this.ignored(path))
+                    return DENIED;
+                return JSON.stringify(await this.workspace.statPath(path));
+            }
+            case "find_files": {
+                const path = pathArg(args, "path", ".");
+                if (localDenyReason(path) !== null)
+                    return DENIED;
+                const found = await this.workspace.findFiles(path, stringArg(args, "pattern"), intArg(args, "maxResults", 100, 1, 1000));
+                return JSON.stringify((await this.visible(found.map((file) => ({ file, path: file })))).map(({ file }) => file));
+            }
+            case "search_files": {
+                const path = pathArg(args, "path", ".");
+                if (localDenyReason(path) !== null)
+                    return DENIED;
+                const hits = await this.workspace.searchFiles(path, stringArg(args, "query"), {
+                    regex: args.regex === true,
+                    caseSensitive: args.caseSensitive === true,
+                    maxResults: intArg(args, "maxResults", 50, 1, 500),
+                    contextLines: intArg(args, "contextLines", 0, 0, 10),
+                });
+                const kept = await this.visible(hits.map((hit) => ({ hit, path: hit.path })));
+                for (const { hit } of kept)
+                    this.noteRead(hit.path, Buffer.byteLength(hit.text, "utf8"), log);
+                return JSON.stringify(kept.map(({ hit }) => hit));
+            }
+            case "read_file":
+            case "read_file_lines": {
+                const path = pathArg(args, "path");
+                if (localDenyReason(path) !== null || await this.ignored(path))
+                    return DENIED;
+                const file = await this.workspace.readFileBytes(path);
+                if (file.data.subarray(0, 8000).includes(0))
+                    return `${DENIED} (binary file)`;
+                const ranged = name === "read_file_lines" || args.startLine !== undefined || args.endLine !== undefined;
+                const text = ranged
+                    ? (await this.workspace.readFileLines(path, intArg(args, "startLine", 1, 1, Number.MAX_SAFE_INTEGER), args.endLine === undefined ? undefined : intArg(args, "endLine", 1, 1, Number.MAX_SAFE_INTEGER))).content
+                    : file.data.toString("utf8");
+                const returned = limitBytes(text, TOOL_OUTPUT_LIMIT_BYTES);
+                this.noteRead(path, Buffer.byteLength(returned, "utf8"), log);
+                return returned;
+            }
+            default:
+                return `error: unknown tool ${name.slice(0, 64)}`;
+        }
+    }
+    async ignored(path) {
+        if (path === "." || path === "")
+            return false;
+        return (await gitIgnoredPaths(this.workspace.root, [normalize(path)])).size > 0;
+    }
+    /** Drop denied and gitignored entries from a listing. */
+    async visible(entries) {
+        const allowed = entries.filter((entry) => localDenyReason(entry.path) === null);
+        const ignored = await gitIgnoredPaths(this.workspace.root, allowed.map((entry) => normalize(entry.path)));
+        return allowed.filter((entry) => !ignored.has(normalize(entry.path)));
+    }
+    /**
+     * A path tree of the files the Agent may read, cut at `maxBytes`: the first thing it gets, so it can choose what to open. Uses
+     * `git ls-files` (tracked and untracked, not ignored) in a repository, else a bounded walk.
+     */
+    async overview(maxBytes = OVERVIEW_LIMIT_BYTES) {
+        let files;
+        try {
+            const { stdout } = await execute("git", ["-C", this.workspace.root, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { maxBuffer: 16 * 1024 * 1024, windowsHide: true });
+            files = stdout.split("\0").filter(Boolean);
+        }
+        catch {
+            files = await this.workspace.findFiles(".", "*", 2000).catch(() => []);
+        }
+        files = [...new Set(files)].filter((file) => localDenyReason(file) === null).sort();
+        const lines = [];
+        let size = 0;
+        for (const file of files) {
+            size += Buffer.byteLength(file, "utf8") + 1;
+            if (size > maxBytes)
+                break;
+            lines.push(file);
+        }
+        const more = files.length - lines.length;
+        return `${lines.join("\n")}${more > 0 ? `\n... and ${more} more files` : ""}`;
+    }
+}
+function joinPath(base, name) {
+    return base === "." || base === "" ? name : `${base.replace(/[\\/]+$/u, "")}/${name}`;
+}
+function normalize(path) {
+    return path.split(/[\\/]+/u).filter((segment) => segment !== "" && segment !== ".").join("/");
+}
+function pathArg(args, name, fallback) {
+    const value = args[name];
+    if (value === undefined && fallback !== undefined)
+        return fallback;
+    if (typeof value !== "string" || value === "" || value.includes("\0"))
+        throw new Error(`${name} must be a non-empty path.`);
+    return value;
+}
+function stringArg(args, name) {
+    const value = args[name];
+    if (typeof value !== "string" || value === "")
+        throw new Error(`${name} is required.`);
+    return value;
+}
+function intArg(args, name, fallback, min, max) {
+    const value = args[name];
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max)
+        throw new Error(`${name} must be an integer from ${min} to ${max}.`);
+    return value;
+}
+/** Cut at a byte limit on a character boundary, saying so, so the Agent knows to ask for a line range. */
+export function limitBytes(text, limit) {
+    if (Buffer.byteLength(text, "utf8") <= limit)
+        return text;
+    const note = "\n[truncated: output limit reached; use read_file_lines for the rest]";
+    const room = Math.max(0, limit - Buffer.byteLength(note, "utf8"));
+    let cut = Buffer.from(text, "utf8").subarray(0, room).toString("utf8");
+    if (cut.endsWith("�"))
+        cut = cut.slice(0, -1);
+    return limit === 0 ? "" : cut + note;
+}
+//# sourceMappingURL=workspace-read.js.map