@mikode13/harness 2.2.0 → 3.0.0

package/dist/tools/infrastructure/gitWorkspace.d.ts

@@ -0,0 +1,13 @@
+import type { TextMatch } from '../domain/workspace.ts';
+import { BoundedWorkspace } from './boundedWorkspace.ts';
+/**
+ * The fallback `Workspace`, on the git the repository already has. git applies `.gitignore`
+ * by itself, even to an explicit path, but only inside a repository: outside one, every
+ * operation fails.
+ */
+export declare class GitWorkspace extends BoundedWorkspace {
+    protected listCandidates(signal: AbortSignal): Promise<string[]>;
+    protected findMatches(pattern: string, ignoreCase: boolean, signal: AbortSignal, keep: (match: TextMatch) => void): Promise<void>;
+    private listFiles0;
+    private git;
+}

package/dist/tools/infrastructure/gitWorkspace.js

@@ -0,0 +1,61 @@
+import { BoundedWorkspace } from "./boundedWorkspace.js";
+import { firstLine, runProcess } from "./runProcess.js";
+/**
+ * The fallback `Workspace`, on the git the repository already has. git applies `.gitignore`
+ * by itself, even to an explicit path, but only inside a repository: outside one, every
+ * operation fails.
+ */
+export class GitWorkspace extends BoundedWorkspace {
+    async listCandidates(signal) {
+        // Tracked files and new ones not yet added; then the tracked ones `.gitignore` matches
+        // anyway, such as a `.env` committed before it was ignored. ripgrep hides those, and the
+        // fallback must not show what the preferred implementation hides.
+        const [listed, ignored] = await Promise.all([
+            this.listFiles0(['--cached', '--others', '--exclude-standard'], signal),
+            this.listFiles0(['--cached', '--ignored', '--exclude-standard'], signal),
+        ]);
+        const hidden = new Set(ignored);
+        return listed.filter(path => !hidden.has(path));
+    }
+    async findMatches(pattern, ignoreCase, signal, keep) {
+        const { stderr, exitCode } = await this.git([
+            'grep',
+            // Untracked files too, or the agent could not search a file it has just created.
+            '--untracked',
+            // Binary files left out, as ripgrep does.
+            '-I',
+            '--line-number',
+            // path NUL line NUL text, so a colon in a path cannot split it.
+            '-z',
+            // Perl syntax, so `\d` and `\b` mean what they mean to ripgrep.
+            '-P',
+            ...(ignoreCase ? ['--ignore-case'] : []),
+            // `-e`, so a pattern starting with a dash is never read as an option.
+            '-e',
+            pattern,
+        ], signal, line => {
+            const [path, number, ...text] = line.split('\0');
+            if (path && number) {
+                keep({ path, line: Number(number), text: text.join('\0').replace(/\r$/, '') });
+            }
+        });
+        // 1 means no match; anything above is a failure, such as a pattern that does not compile.
+        if (exitCode > 1) {
+            throw new Error(`git could not search for the pattern: ${firstLine(stderr)}`);
+        }
+    }
+    async listFiles0(options, signal) {
+        const { stdout, stderr, exitCode } = await this.git(['ls-files', '-z', ...options], signal);
+        if (exitCode !== 0) {
+            throw new Error(`git could not list the files: ${firstLine(stderr)}`);
+        }
+        return stdout.split('\0').filter(path => path !== '');
+    }
+    git(args, signal, onLine) {
+        // A user's settings must not change the output this parses: colour codes would end up in
+        // the text, `grep.column` adds a field, and `grep.fullName` makes paths relative to the
+        // repository instead of the root.
+        return runProcess('git', ['-c', 'color.ui=never', '-c', 'grep.column=false', '-c', 'grep.fullName=false', ...args], { cwd: this.root, signal, onLine });
+    }
+}
+//# sourceMappingURL=gitWorkspace.js.map

package/dist/tools/infrastructure/gitWorkspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitWorkspace.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/gitWorkspace.ts"],"names":[],"mappings":"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","sourcesContent":["import type { TextMatch } from '../domain/workspace.ts';\nimport { BoundedWorkspace } from './boundedWorkspace.ts';\nimport { firstLine, runProcess } from './runProcess.ts';\n\n/**\n * The fallback `Workspace`, on the git the repository already has. git applies `.gitignore`\n * by itself, even to an explicit path, but only inside a repository: outside one, every\n * operation fails.\n */\nexport class GitWorkspace extends BoundedWorkspace {\n\tprotected async listCandidates(signal: AbortSignal): Promise<string[]> {\n\t\t// Tracked files and new ones not yet added; then the tracked ones `.gitignore` matches\n\t\t// anyway, such as a `.env` committed before it was ignored. ripgrep hides those, and the\n\t\t// fallback must not show what the preferred implementation hides.\n\t\tconst [listed, ignored] = await Promise.all([\n\t\t\tthis.listFiles0(['--cached', '--others', '--exclude-standard'], signal),\n\t\t\tthis.listFiles0(['--cached', '--ignored', '--exclude-standard'], signal),\n\t\t]);\n\t\tconst hidden = new Set(ignored);\n\n\t\treturn listed.filter(path => !hidden.has(path));\n\t}\n\n\tprotected async findMatches(\n\t\tpattern: string,\n\t\tignoreCase: boolean,\n\t\tsignal: AbortSignal,\n\t\tkeep: (match: TextMatch) => void,\n\t): Promise<void> {\n\t\tconst { stderr, exitCode } = await this.git(\n\t\t\t[\n\t\t\t\t'grep',\n\t\t\t\t// Untracked files too, or the agent could not search a file it has just created.\n\t\t\t\t'--untracked',\n\t\t\t\t// Binary files left out, as ripgrep does.\n\t\t\t\t'-I',\n\t\t\t\t'--line-number',\n\t\t\t\t// path NUL line NUL text, so a colon in a path cannot split it.\n\t\t\t\t'-z',\n\t\t\t\t// Perl syntax, so `\\d` and `\\b` mean what they mean to ripgrep.\n\t\t\t\t'-P',\n\t\t\t\t...(ignoreCase ? ['--ignore-case'] : []),\n\t\t\t\t// `-e`, so a pattern starting with a dash is never read as an option.\n\t\t\t\t'-e',\n\t\t\t\tpattern,\n\t\t\t],\n\t\t\tsignal,\n\t\t\tline => {\n\t\t\t\tconst [path, number, ...text] = line.split('\\0');\n\t\t\t\tif (path && number) {\n\t\t\t\t\tkeep({ path, line: Number(number), text: text.join('\\0').replace(/\\r$/, '') });\n\t\t\t\t}\n\t\t\t},\n\t\t);\n\t\t// 1 means no match; anything above is a failure, such as a pattern that does not compile.\n\t\tif (exitCode > 1) {\n\t\t\tthrow new Error(`git could not search for the pattern: ${firstLine(stderr)}`);\n\t\t}\n\t}\n\n\tprivate async listFiles0(options: string[], signal: AbortSignal): Promise<string[]> {\n\t\tconst { stdout, stderr, exitCode } = await this.git(['ls-files', '-z', ...options], signal);\n\t\tif (exitCode !== 0) {\n\t\t\tthrow new Error(`git could not list the files: ${firstLine(stderr)}`);\n\t\t}\n\n\t\treturn stdout.split('\\0').filter(path => path !== '');\n\t}\n\n\tprivate git(args: string[], signal: AbortSignal, onLine?: (line: string) => void) {\n\t\t// A user's settings must not change the output this parses: colour codes would end up in\n\t\t// the text, `grep.column` adds a field, and `grep.fullName` makes paths relative to the\n\t\t// repository instead of the root.\n\t\treturn runProcess(\n\t\t\t'git',\n\t\t\t['-c', 'color.ui=never', '-c', 'grep.column=false', '-c', 'grep.fullName=false', ...args],\n\t\t\t{ cwd: this.root, signal, onLine },\n\t\t);\n\t}\n}\n"]}

package/dist/tools/infrastructure/ripgrepWorkspace.d.ts

@@ -0,0 +1,20 @@
+import type { TextMatch } from '../domain/workspace.ts';
+import { BoundedWorkspace } from './boundedWorkspace.ts';
+/**
+ * The preferred `Workspace`, on the ripgrep binary that ships with the package. It always runs
+ * from the root with no path: ripgrep ignores nothing that it is given explicitly.
+ *
+ * It takes the binary's path instead of importing `@vscode/ripgrep`, which throws on import when
+ * the platform has no binary; `createWorkspace` loads it where that failure can be handled.
+ */
+export declare class RipgrepWorkspace extends BoundedWorkspace {
+    private readonly ripgrepPath;
+    constructor({ ripgrepPath, ...options }: {
+        root: string;
+        ripgrepPath: string;
+        timeoutMs?: number;
+    });
+    protected listCandidates(signal: AbortSignal): Promise<string[]>;
+    protected findMatches(pattern: string, ignoreCase: boolean, signal: AbortSignal, keep: (match: TextMatch) => void): Promise<void>;
+    private ripgrep;
+}

package/dist/tools/infrastructure/ripgrepWorkspace.js

@@ -0,0 +1,85 @@
+import { BoundedWorkspace } from "./boundedWorkspace.js";
+import { firstLine, runProcess } from "./runProcess.js";
+// Every call sees what git would. Each flag is ours; nothing a model writes ever reaches the
+// command line except the pattern, and that only after `-e`.
+const sameViewAsGit = [
+    // A user's ripgrep configuration could switch the ignore rules off.
+    '--no-config',
+    // ripgrep's own `.ignore` and `.rgignore` outrank `.gitignore`, so a `!.env` line in either
+    // would show a secret git hides. Only git's ignore sources count.
+    '--no-ignore-dot',
+    // Hidden files such as `.github/` are part of the repository; ripgrep skips them by default.
+    '--hidden',
+    // `.gitignore` applies even outside a git repository.
+    '--no-require-git',
+    // `--hidden` would otherwise search git's own folder.
+    '--glob',
+    '!.git',
+    // Windows would print `\`; every path in a `Workspace` is written with `/`.
+    '--path-separator',
+    '/',
+];
+function decode({ text, bytes }) {
+    return text ?? Buffer.from(bytes ?? '', 'base64').toString('utf8');
+}
+/**
+ * The preferred `Workspace`, on the ripgrep binary that ships with the package. It always runs
+ * from the root with no path: ripgrep ignores nothing that it is given explicitly.
+ *
+ * It takes the binary's path instead of importing `@vscode/ripgrep`, which throws on import when
+ * the platform has no binary; `createWorkspace` loads it where that failure can be handled.
+ */
+export class RipgrepWorkspace extends BoundedWorkspace {
+    ripgrepPath;
+    constructor({ ripgrepPath, ...options }) {
+        super(options);
+        this.ripgrepPath = ripgrepPath;
+    }
+    async listCandidates(signal) {
+        const { stdout, stderr, exitCode } = await this.ripgrep(['--files', '--null'], signal);
+        // 1 means nothing to list, which an empty repository is. 2 with a listing means some
+        // folder could not be read, which git skips with a warning too; without one, it failed.
+        if (exitCode > 1 && stdout === '') {
+            throw new Error(`ripgrep could not list the files: ${firstLine(stderr)}`);
+        }
+        return stdout
+            .split('\0')
+            .filter(path => path !== '')
+            .map(path => path.replace(/^\.\//, ''));
+    }
+    async findMatches(pattern, ignoreCase, signal, keep) {
+        // ripgrep ends every search it ran with a summary. A failure before searching, such as a
+        // pattern that does not compile, prints none. A count, not a flag: TypeScript cannot see
+        // the callback change it.
+        let summaries = 0;
+        const { stderr, exitCode } = await this.ripgrep(['--json', ...(ignoreCase ? ['--ignore-case'] : []), '-e', pattern], signal, line => {
+            if (line === '') {
+                return;
+            }
+            const event = JSON.parse(line);
+            if (event.type === 'summary') {
+                summaries++;
+            }
+            if (event.type === 'match') {
+                keep({
+                    path: decode(event.data.path).replace(/^\.\//, ''),
+                    line: event.data.line_number,
+                    text: decode(event.data.lines).replace(/\r?\n$/, ''),
+                });
+            }
+        });
+        // 1 means no match. 2 after a search means some file could not be read, and the rest
+        // stands, as it does on git; 2 with no search is the failure.
+        if (exitCode > 1 && summaries === 0) {
+            throw new Error(`ripgrep could not search for the pattern: ${firstLine(stderr)}`);
+        }
+    }
+    ripgrep(args, signal, onLine) {
+        return runProcess(this.ripgrepPath, [...sameViewAsGit, ...args], {
+            cwd: this.root,
+            signal,
+            onLine,
+        });
+    }
+}
+//# sourceMappingURL=ripgrepWorkspace.js.map

package/dist/tools/infrastructure/ripgrepWorkspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ripgrepWorkspace.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/ripgrepWorkspace.ts"],"names":[],"mappings":"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","sourcesContent":["import type { TextMatch } from '../domain/workspace.ts';\nimport { BoundedWorkspace } from './boundedWorkspace.ts';\nimport { firstLine, runProcess } from './runProcess.ts';\n\n// Every call sees what git would. Each flag is ours; nothing a model writes ever reaches the\n// command line except the pattern, and that only after `-e`.\nconst sameViewAsGit = [\n\t// A user's ripgrep configuration could switch the ignore rules off.\n\t'--no-config',\n\t// ripgrep's own `.ignore` and `.rgignore` outrank `.gitignore`, so a `!.env` line in either\n\t// would show a secret git hides. Only git's ignore sources count.\n\t'--no-ignore-dot',\n\t// Hidden files such as `.github/` are part of the repository; ripgrep skips them by default.\n\t'--hidden',\n\t// `.gitignore` applies even outside a git repository.\n\t'--no-require-git',\n\t// `--hidden` would otherwise search git's own folder.\n\t'--glob',\n\t'!.git',\n\t// Windows would print `\\`; every path in a `Workspace` is written with `/`.\n\t'--path-separator',\n\t'/',\n];\n\ninterface RipgrepText {\n\ttext?: string;\n\t// ripgrep sends what is not valid UTF-8 as base64 instead.\n\tbytes?: string;\n}\n\ninterface RipgrepEvent {\n\ttype: string;\n\tdata: { path: RipgrepText; line_number: number; lines: RipgrepText };\n}\n\nfunction decode({ text, bytes }: RipgrepText): string {\n\treturn text ?? Buffer.from(bytes ?? '', 'base64').toString('utf8');\n}\n\n/**\n * The preferred `Workspace`, on the ripgrep binary that ships with the package. It always runs\n * from the root with no path: ripgrep ignores nothing that it is given explicitly.\n *\n * It takes the binary's path instead of importing `@vscode/ripgrep`, which throws on import when\n * the platform has no binary; `createWorkspace` loads it where that failure can be handled.\n */\nexport class RipgrepWorkspace extends BoundedWorkspace {\n\tprivate readonly ripgrepPath: string;\n\n\tconstructor({\n\t\tripgrepPath,\n\t\t...options\n\t}: {\n\t\troot: string;\n\t\tripgrepPath: string;\n\t\ttimeoutMs?: number;\n\t}) {\n\t\tsuper(options);\n\t\tthis.ripgrepPath = ripgrepPath;\n\t}\n\n\tprotected async listCandidates(signal: AbortSignal): Promise<string[]> {\n\t\tconst { stdout, stderr, exitCode } = await this.ripgrep(['--files', '--null'], signal);\n\t\t// 1 means nothing to list, which an empty repository is. 2 with a listing means some\n\t\t// folder could not be read, which git skips with a warning too; without one, it failed.\n\t\tif (exitCode > 1 && stdout === '') {\n\t\t\tthrow new Error(`ripgrep could not list the files: ${firstLine(stderr)}`);\n\t\t}\n\n\t\treturn stdout\n\t\t\t.split('\\0')\n\t\t\t.filter(path => path !== '')\n\t\t\t.map(path => path.replace(/^\\.\\//, ''));\n\t}\n\n\tprotected async findMatches(\n\t\tpattern: string,\n\t\tignoreCase: boolean,\n\t\tsignal: AbortSignal,\n\t\tkeep: (match: TextMatch) => void,\n\t): Promise<void> {\n\t\t// ripgrep ends every search it ran with a summary. A failure before searching, such as a\n\t\t// pattern that does not compile, prints none. A count, not a flag: TypeScript cannot see\n\t\t// the callback change it.\n\t\tlet summaries = 0;\n\t\tconst { stderr, exitCode } = await this.ripgrep(\n\t\t\t['--json', ...(ignoreCase ? ['--ignore-case'] : []), '-e', pattern],\n\t\t\tsignal,\n\t\t\tline => {\n\t\t\t\tif (line === '') {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tconst event = JSON.parse(line) as RipgrepEvent;\n\t\t\t\tif (event.type === 'summary') {\n\t\t\t\t\tsummaries++;\n\t\t\t\t}\n\t\t\t\tif (event.type === 'match') {\n\t\t\t\t\tkeep({\n\t\t\t\t\t\tpath: decode(event.data.path).replace(/^\\.\\//, ''),\n\t\t\t\t\t\tline: event.data.line_number,\n\t\t\t\t\t\ttext: decode(event.data.lines).replace(/\\r?\\n$/, ''),\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t},\n\t\t);\n\n\t\t// 1 means no match. 2 after a search means some file could not be read, and the rest\n\t\t// stands, as it does on git; 2 with no search is the failure.\n\t\tif (exitCode > 1 && summaries === 0) {\n\t\t\tthrow new Error(`ripgrep could not search for the pattern: ${firstLine(stderr)}`);\n\t\t}\n\t}\n\n\tprivate ripgrep(args: string[], signal: AbortSignal, onLine?: (line: string) => void) {\n\t\treturn runProcess(this.ripgrepPath, [...sameViewAsGit, ...args], {\n\t\t\tcwd: this.root,\n\t\t\tsignal,\n\t\t\tonLine,\n\t\t});\n\t}\n}\n"]}

package/dist/tools/infrastructure/runProcess.d.ts

@@ -0,0 +1,23 @@
+export interface ProcessResult {
+    /** Empty when the output went to `onLine` instead. */
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Runs a program with its arguments as an array, never through a shell, so nothing a model
+ * writes can become a command. Standard input is closed: ripgrep given no path searches its
+ * standard input whenever that is a pipe. A cancelled signal kills the process and rejects
+ * with the signal's `AbortError`.
+ *
+ * With `onLine`, each line of the output is handed over as it arrives and nothing is kept, so
+ * the caller decides what to hold; only a single line is then bound by the size limit. An
+ * error thrown by `onLine` stops the program and rejects with that error.
+ */
+export declare function runProcess(command: string, args: string[], { cwd, signal, onLine }: {
+    cwd: string;
+    signal: AbortSignal;
+    onLine?: (line: string) => void;
+}): Promise<ProcessResult>;
+/** The first line of a program's error output, which is the part a model can act on. */
+export declare function firstLine(text: string): string;

package/dist/tools/infrastructure/runProcess.js

@@ -0,0 +1,91 @@
+import { spawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+// What a program may print, or one line of it may hold, before it is stopped. Beyond this it
+// has printed far more than anyone can read.
+const maxOutputBytes = 64 * 1024 * 1024;
+/**
+ * Runs a program with its arguments as an array, never through a shell, so nothing a model
+ * writes can become a command. Standard input is closed: ripgrep given no path searches its
+ * standard input whenever that is a pipe. A cancelled signal kills the process and rejects
+ * with the signal's `AbortError`.
+ *
+ * With `onLine`, each line of the output is handed over as it arrives and nothing is kept, so
+ * the caller decides what to hold; only a single line is then bound by the size limit. An
+ * error thrown by `onLine` stops the program and rejects with that error.
+ */
+export function runProcess(command, args, { cwd, signal, onLine }) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd, signal, stdio: ['ignore', 'pipe', 'pipe'] });
+        const decoder = new StringDecoder('utf8');
+        const stdout = [];
+        const stderr = [];
+        let pending = '';
+        let size = 0;
+        let failure;
+        const stop = (error) => {
+            failure ??= error;
+            child.kill();
+        };
+        const deliver = (text) => {
+            if (!onLine) {
+                stdout.push(text);
+                return;
+            }
+            const lines = (pending + text).split('\n');
+            pending = lines.pop() ?? '';
+            for (const line of lines)
+                onLine(line);
+        };
+        child.stdout.on('data', (chunk) => {
+            if (failure) {
+                return;
+            }
+            size = onLine ? pending.length + chunk.length : size + chunk.length;
+            if (size > maxOutputBytes) {
+                stop(new Error(`The program printed more than ${String(maxOutputBytes / 1024 / 1024)} MB`));
+                return;
+            }
+            try {
+                deliver(decoder.write(chunk));
+            }
+            catch (error) {
+                stop(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+        child.stderr.on('data', (chunk) => stderr.push(chunk));
+        // A missing program, or the cancellation, which arrives as an `AbortError`.
+        child.on('error', reject);
+        child.on('close', (code, killedBy) => {
+            // Stopped from outside, such as by the out-of-memory killer: what it printed is not the
+            // whole answer, and an exit code would pass it off as one. Its own stops set `failure`.
+            if (code === null && !failure) {
+                failure = new Error(`${command} was stopped by ${killedBy ?? 'a signal'} before it finished`);
+            }
+            if (!failure) {
+                try {
+                    deliver(decoder.end());
+                    if (onLine && pending !== '')
+                        onLine(pending);
+                }
+                catch (error) {
+                    failure = error instanceof Error ? error : new Error(String(error));
+                }
+            }
+            if (failure) {
+                reject(failure);
+                return;
+            }
+            resolve({
+                stdout: stdout.join(''),
+                stderr: Buffer.concat(stderr).toString('utf8'),
+                // Not null here: a process stopped by a signal was rejected above.
+                exitCode: code ?? 1,
+            });
+        });
+    });
+}
+/** The first line of a program's error output, which is the part a model can act on. */
+export function firstLine(text) {
+    return text.trim().split('\n')[0] ?? '';
+}
+//# sourceMappingURL=runProcess.js.map

package/dist/tools/infrastructure/runProcess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runProcess.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/runProcess.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from 'node:child_process';\nimport { StringDecoder } from 'node:string_decoder';\n\n// What a program may print, or one line of it may hold, before it is stopped. Beyond this it\n// has printed far more than anyone can read.\nconst maxOutputBytes = 64 * 1024 * 1024;\n\nexport interface ProcessResult {\n\t/** Empty when the output went to `onLine` instead. */\n\tstdout: string;\n\tstderr: string;\n\texitCode: number;\n}\n\n/**\n * Runs a program with its arguments as an array, never through a shell, so nothing a model\n * writes can become a command. Standard input is closed: ripgrep given no path searches its\n * standard input whenever that is a pipe. A cancelled signal kills the process and rejects\n * with the signal's `AbortError`.\n *\n * With `onLine`, each line of the output is handed over as it arrives and nothing is kept, so\n * the caller decides what to hold; only a single line is then bound by the size limit. An\n * error thrown by `onLine` stops the program and rejects with that error.\n */\nexport function runProcess(\n\tcommand: string,\n\targs: string[],\n\t{ cwd, signal, onLine }: { cwd: string; signal: AbortSignal; onLine?: (line: string) => void },\n): Promise<ProcessResult> {\n\treturn new Promise((resolve, reject) => {\n\t\tconst child = spawn(command, args, { cwd, signal, stdio: ['ignore', 'pipe', 'pipe'] });\n\t\tconst decoder = new StringDecoder('utf8');\n\t\tconst stdout: string[] = [];\n\t\tconst stderr: Buffer[] = [];\n\t\tlet pending = '';\n\t\tlet size = 0;\n\t\tlet failure: Error | undefined;\n\n\t\tconst stop = (error: Error) => {\n\t\t\tfailure ??= error;\n\t\t\tchild.kill();\n\t\t};\n\n\t\tconst deliver = (text: string) => {\n\t\t\tif (!onLine) {\n\t\t\t\tstdout.push(text);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst lines = (pending + text).split('\\n');\n\t\t\tpending = lines.pop() ?? '';\n\t\t\tfor (const line of lines) onLine(line);\n\t\t};\n\n\t\tchild.stdout.on('data', (chunk: Buffer) => {\n\t\t\tif (failure) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tsize = onLine ? pending.length + chunk.length : size + chunk.length;\n\t\t\tif (size > maxOutputBytes) {\n\t\t\t\tstop(new Error(`The program printed more than ${String(maxOutputBytes / 1024 / 1024)} MB`));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tdeliver(decoder.write(chunk));\n\t\t\t} catch (error) {\n\t\t\t\tstop(error instanceof Error ? error : new Error(String(error)));\n\t\t\t}\n\t\t});\n\t\tchild.stderr.on('data', (chunk: Buffer) => stderr.push(chunk));\n\n\t\t// A missing program, or the cancellation, which arrives as an `AbortError`.\n\t\tchild.on('error', reject);\n\t\tchild.on('close', (code, killedBy) => {\n\t\t\t// Stopped from outside, such as by the out-of-memory killer: what it printed is not the\n\t\t\t// whole answer, and an exit code would pass it off as one. Its own stops set `failure`.\n\t\t\tif (code === null && !failure) {\n\t\t\t\tfailure = new Error(\n\t\t\t\t\t`${command} was stopped by ${killedBy ?? 'a signal'} before it finished`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (!failure) {\n\t\t\t\ttry {\n\t\t\t\t\tdeliver(decoder.end());\n\t\t\t\t\tif (onLine && pending !== '') onLine(pending);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tfailure = error instanceof Error ? error : new Error(String(error));\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (failure) {\n\t\t\t\treject(failure);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tresolve({\n\t\t\t\tstdout: stdout.join(''),\n\t\t\t\tstderr: Buffer.concat(stderr).toString('utf8'),\n\t\t\t\t// Not null here: a process stopped by a signal was rejected above.\n\t\t\t\texitCode: code ?? 1,\n\t\t\t});\n\t\t});\n\t});\n}\n\n/** The first line of a program's error output, which is the part a model can act on. */\nexport function firstLine(text: string): string {\n\treturn text.trim().split('\\n')[0] ?? '';\n}\n"]}

package/dist/tools/infrastructure/workspaceTools.d.ts

@@ -0,0 +1,4 @@
+import type { Tool } from '../domain/tool.ts';
+import type { Workspace } from '../domain/workspace.ts';
+/** The three read-only tools an agent explores a repository with. */
+export declare function createWorkspaceTools(workspace: Workspace): Tool[];

package/dist/tools/infrastructure/workspaceTools.js

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import { defineTool } from "./defineTool.js";
+// What one call may return. The model can ask for fewer lines, never for more.
+const maxFiles = 200;
+const maxMatches = 100;
+const maxLines = 200;
+// One minified line can be larger than everything else the model has read.
+const maxLineLength = 300;
+// Strict mode has no optional fields: an argument the model may leave out is nullable.
+const scope = {
+    path: z.string().nullable().describe('A folder or file to stay inside, relative to the root.'),
+    glob: z.string().nullable().describe('Only paths matching this glob, such as "**/*.ts".'),
+};
+/** One line as the model reads it: a minified bundle on a single line would flood its context. */
+function cutLine(text) {
+    return text.length > maxLineLength ? `${text.slice(0, maxLineLength)}…` : text;
+}
+function assertPositiveInteger(name, value) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`${name} must be a whole number of at least 1; got ${String(value)}`);
+    }
+}
+/** The three read-only tools an agent explores a repository with. */
+export function createWorkspaceTools(workspace) {
+    return [
+        defineTool({
+            name: 'listFiles',
+            description: 'Lists the files of the repository, sorted. Ignored files such as dependencies are left out.',
+            input: z.object(scope),
+            execute: async ({ path, glob }, signal) => {
+                // The port takes "no scope" as a missing field.
+                const { files, total, truncated } = await workspace.listFiles({ path: path ?? undefined, glob: glob ?? undefined, limit: maxFiles }, signal);
+                // Nothing found is an answer too, not an empty string.
+                if (files.length === 0) {
+                    return 'No files.';
+                }
+                const notice = truncated
+                    ? `\n[Showing ${String(files.length)} of ${String(total)} files. Narrow the path or glob to see the rest.]`
+                    : '';
+                return files.join('\n') + notice;
+            },
+        }),
+        defineTool({
+            name: 'searchText',
+            description: 'Searches the repository for a regular expression and returns each matching line as path:line: text.',
+            input: z.object({
+                pattern: z.string().describe('A regular expression.'),
+                ignoreCase: z.boolean().nullable().describe('Match regardless of case. Defaults to false.'),
+                ...scope,
+            }),
+            execute: async ({ path, glob, ignoreCase, pattern }, signal) => {
+                const { matches, total, truncated } = await workspace.searchText({
+                    path: path ?? undefined,
+                    glob: glob ?? undefined,
+                    ignoreCase: ignoreCase ?? false,
+                    pattern,
+                    limit: maxMatches,
+                }, signal);
+                if (matches.length === 0) {
+                    return 'No matches.';
+                }
+                const results = matches.map(match => `${match.path}:${String(match.line)}: ${cutLine(match.text)}`);
+                const notice = truncated
+                    ? `\n[Showing ${String(results.length)} of ${String(total)} matches. Narrow the path or glob to see the rest.]`
+                    : '';
+                return results.join('\n') + notice;
+            },
+        }),
+        defineTool({
+            name: 'readFile',
+            description: 'Reads lines of a file, each prefixed with its number.',
+            input: z.object({
+                path: z.string().describe('The file, relative to the root.'),
+                fromLine: z.number().nullable().describe('The first line to read, from 1. Defaults to 1.'),
+                lineCount: z
+                    .number()
+                    .nullable()
+                    .describe(`How many lines to read, at most ${String(maxLines)}. Defaults to ${String(maxLines)}.`),
+            }),
+            execute: async ({ fromLine, lineCount, path }, signal) => {
+                const from = fromLine ?? 1;
+                const requested = lineCount ?? maxLines;
+                // Checked here, before reading, because strict mode allows the schema no minimum.
+                assertPositiveInteger('fromLine', from);
+                assertPositiveInteger('lineCount', requested);
+                const { lines, totalLines, truncated } = await workspace.readFile({ path, fromLine: from, lineCount: Math.min(requested, maxLines) }, signal);
+                // The file's length tells the model where its range went wrong.
+                if (lines.length === 0) {
+                    return `No lines from ${String(from)}: the file has ${String(totalLines)} lines.`;
+                }
+                const numbered = lines.map((text, index) => `${String(from + index)}: ${cutLine(text)}`);
+                const cut = lines.filter(text => text.length > maxLineLength).length;
+                const notices = [
+                    ...(cut > 0
+                        ? [
+                            `[${String(cut)} lines were longer than ${String(maxLineLength)} characters and were cut.]`,
+                        ]
+                        : []),
+                    ...(truncated
+                        ? [
+                            `[The file has ${String(totalLines)} lines. Read from line ${String(from + lines.length)} to continue.]`,
+                        ]
+                        : []),
+                ];
+                return [...numbered, ...notices].join('\n');
+            },
+        }),
+    ];
+}
+//# sourceMappingURL=workspaceTools.js.map

package/dist/tools/infrastructure/workspaceTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceTools.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/workspaceTools.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport type { Tool } from '../domain/tool.ts';\nimport type { Workspace } from '../domain/workspace.ts';\nimport { defineTool } from './defineTool.ts';\n\n// What one call may return. The model can ask for fewer lines, never for more.\nconst maxFiles = 200;\nconst maxMatches = 100;\nconst maxLines = 200;\n// One minified line can be larger than everything else the model has read.\nconst maxLineLength = 300;\n\n// Strict mode has no optional fields: an argument the model may leave out is nullable.\nconst scope = {\n\tpath: z.string().nullable().describe('A folder or file to stay inside, relative to the root.'),\n\tglob: z.string().nullable().describe('Only paths matching this glob, such as \"**/*.ts\".'),\n};\n\n/** One line as the model reads it: a minified bundle on a single line would flood its context. */\nfunction cutLine(text: string): string {\n\treturn text.length > maxLineLength ? `${text.slice(0, maxLineLength)}…` : text;\n}\n\nfunction assertPositiveInteger(name: string, value: number): void {\n\tif (!Number.isInteger(value) || value < 1) {\n\t\tthrow new Error(`${name} must be a whole number of at least 1; got ${String(value)}`);\n\t}\n}\n\n/** The three read-only tools an agent explores a repository with. */\nexport function createWorkspaceTools(workspace: Workspace): Tool[] {\n\treturn [\n\t\tdefineTool({\n\t\t\tname: 'listFiles',\n\t\t\tdescription:\n\t\t\t\t'Lists the files of the repository, sorted. Ignored files such as dependencies are left out.',\n\t\t\tinput: z.object(scope),\n\t\t\texecute: async ({ path, glob }, signal) => {\n\t\t\t\t// The port takes \"no scope\" as a missing field.\n\t\t\t\tconst { files, total, truncated } = await workspace.listFiles(\n\t\t\t\t\t{ path: path ?? undefined, glob: glob ?? undefined, limit: maxFiles },\n\t\t\t\t\tsignal,\n\t\t\t\t);\n\n\t\t\t\t// Nothing found is an answer too, not an empty string.\n\t\t\t\tif (files.length === 0) {\n\t\t\t\t\treturn 'No files.';\n\t\t\t\t}\n\n\t\t\t\tconst notice = truncated\n\t\t\t\t\t? `\\n[Showing ${String(files.length)} of ${String(total)} files. Narrow the path or glob to see the rest.]`\n\t\t\t\t\t: '';\n\t\t\t\treturn files.join('\\n') + notice;\n\t\t\t},\n\t\t}),\n\n\t\tdefineTool({\n\t\t\tname: 'searchText',\n\t\t\tdescription:\n\t\t\t\t'Searches the repository for a regular expression and returns each matching line as path:line: text.',\n\t\t\tinput: z.object({\n\t\t\t\tpattern: z.string().describe('A regular expression.'),\n\t\t\t\tignoreCase: z.boolean().nullable().describe('Match regardless of case. Defaults to false.'),\n\t\t\t\t...scope,\n\t\t\t}),\n\t\t\texecute: async ({ path, glob, ignoreCase, pattern }, signal) => {\n\t\t\t\tconst { matches, total, truncated } = await workspace.searchText(\n\t\t\t\t\t{\n\t\t\t\t\t\tpath: path ?? undefined,\n\t\t\t\t\t\tglob: glob ?? undefined,\n\t\t\t\t\t\tignoreCase: ignoreCase ?? false,\n\t\t\t\t\t\tpattern,\n\t\t\t\t\t\tlimit: maxMatches,\n\t\t\t\t\t},\n\t\t\t\t\tsignal,\n\t\t\t\t);\n\n\t\t\t\tif (matches.length === 0) {\n\t\t\t\t\treturn 'No matches.';\n\t\t\t\t}\n\n\t\t\t\tconst results = matches.map(\n\t\t\t\t\tmatch => `${match.path}:${String(match.line)}: ${cutLine(match.text)}`,\n\t\t\t\t);\n\n\t\t\t\tconst notice = truncated\n\t\t\t\t\t? `\\n[Showing ${String(results.length)} of ${String(total)} matches. Narrow the path or glob to see the rest.]`\n\t\t\t\t\t: '';\n\t\t\t\treturn results.join('\\n') + notice;\n\t\t\t},\n\t\t}),\n\n\t\tdefineTool({\n\t\t\tname: 'readFile',\n\t\t\tdescription: 'Reads lines of a file, each prefixed with its number.',\n\t\t\tinput: z.object({\n\t\t\t\tpath: z.string().describe('The file, relative to the root.'),\n\t\t\t\tfromLine: z.number().nullable().describe('The first line to read, from 1. Defaults to 1.'),\n\t\t\t\tlineCount: z\n\t\t\t\t\t.number()\n\t\t\t\t\t.nullable()\n\t\t\t\t\t.describe(\n\t\t\t\t\t\t`How many lines to read, at most ${String(maxLines)}. Defaults to ${String(maxLines)}.`,\n\t\t\t\t\t),\n\t\t\t}),\n\t\t\texecute: async ({ fromLine, lineCount, path }, signal) => {\n\t\t\t\tconst from = fromLine ?? 1;\n\t\t\t\tconst requested = lineCount ?? maxLines;\n\t\t\t\t// Checked here, before reading, because strict mode allows the schema no minimum.\n\t\t\t\tassertPositiveInteger('fromLine', from);\n\t\t\t\tassertPositiveInteger('lineCount', requested);\n\n\t\t\t\tconst { lines, totalLines, truncated } = await workspace.readFile(\n\t\t\t\t\t{ path, fromLine: from, lineCount: Math.min(requested, maxLines) },\n\t\t\t\t\tsignal,\n\t\t\t\t);\n\n\t\t\t\t// The file's length tells the model where its range went wrong.\n\t\t\t\tif (lines.length === 0) {\n\t\t\t\t\treturn `No lines from ${String(from)}: the file has ${String(totalLines)} lines.`;\n\t\t\t\t}\n\n\t\t\t\tconst numbered = lines.map((text, index) => `${String(from + index)}: ${cutLine(text)}`);\n\t\t\t\tconst cut = lines.filter(text => text.length > maxLineLength).length;\n\t\t\t\tconst notices = [\n\t\t\t\t\t...(cut > 0\n\t\t\t\t\t\t? [\n\t\t\t\t\t\t\t\t`[${String(cut)} lines were longer than ${String(maxLineLength)} characters and were cut.]`,\n\t\t\t\t\t\t\t]\n\t\t\t\t\t\t: []),\n\t\t\t\t\t...(truncated\n\t\t\t\t\t\t? [\n\t\t\t\t\t\t\t\t`[The file has ${String(totalLines)} lines. Read from line ${String(from + lines.length)} to continue.]`,\n\t\t\t\t\t\t\t]\n\t\t\t\t\t\t: []),\n\t\t\t\t];\n\t\t\t\treturn [...numbered, ...notices].join('\\n');\n\t\t\t},\n\t\t}),\n\t];\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mikode13/harness",
-	"version": "2.2.0",
+	"version": "3.0.0",
 	"description": "Test/agent harness utility",
 	"type": "module",
 	"license": "SEE LICENSE IN LICENSE",
@@ -63,6 +63,7 @@
 		"@anthropic-ai/claude-agent-sdk": "^0.3.220",
 		"@anthropic-ai/sdk": "^0.115.0",
 		"@openai/codex-sdk": "^0.154.0",
+		"@vscode/ripgrep": "^1.18.0",
 		"openai": "^7.23.0",
 		"zod": "^4.4.3"
 	}