@mikode13/harness 4.0.0 → 5.0.0

package/dist/tools/domain/commands.js

@@ -0,0 +1,191 @@
+import { InvalidAgentConfigError } from '#src/shared/domain/errors';
+import { isOneOf } from '#src/shared/domain/isOneOf';
+/** The roles of the model-backed orchestrator a command can be given to. */
+export const commandRoles = ['planner', 'executor', 'reviewer'];
+export const defaultCommandTimeoutMs = 10 * 60 * 1000;
+export const defaultCommandOutputBytes = 16 * 1024;
+// A test filter or a snapshot name, not a script.
+const maxTextLength = 1000;
+const maxOutputBytes = 1024 * 1024;
+const maxTimeoutMs = 24 * 60 * 60 * 1000;
+const namePattern = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+const variablePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// The tool's input names the command with this key, so no parameter may take it.
+const reservedParameter = 'name';
+/**
+ * Checks every command before an agent is built, so a mistake in the configuration fails there
+ * and never as a refused call in the middle of a run.
+ *
+ * @throws {InvalidAgentConfigError} for the first thing that is wrong.
+ */
+export function validateCommands(commands) {
+    // Unknown throughout: the configuration may come from a JSON file, whatever its type says.
+    if (!isRecord(commands))
+        throw new InvalidAgentConfigError('Commands must be an object');
+    const entries = Object.entries(commands);
+    if (entries.length === 0)
+        throw new InvalidAgentConfigError('No command is configured');
+    for (const [name, definition] of entries) {
+        const fail = (problem) => {
+            throw new InvalidAgentConfigError(`Command "${name}" ${problem}`);
+        };
+        if (!namePattern.test(name)) {
+            fail('needs a name of letters, digits, "-" and "_", starting with a letter');
+        }
+        if (!isRecord(definition))
+            fail('must be an object');
+        const { description, executable, cwd, timeoutMs, outputBytes, env, args, roles } = definition;
+        if (typeof description !== 'string' || description.trim() === '') {
+            fail('needs a description');
+        }
+        if (typeof executable !== 'string' || !isArgument(executable))
+            fail('needs an executable');
+        if (cwd !== undefined && (typeof cwd !== 'string' || !isArgument(cwd))) {
+            fail('has an invalid cwd');
+        }
+        checkLimit(timeoutMs, maxTimeoutMs, 'timeoutMs', fail);
+        checkLimit(outputBytes, maxOutputBytes, 'outputBytes', fail);
+        if (env !== undefined && !isRecord(env))
+            fail('needs env to map names to values');
+        for (const [variable, value] of Object.entries((env ?? {}))) {
+            if (!variablePattern.test(variable))
+                fail(`sets an invalid variable name "${variable}"`);
+            if (typeof value !== 'string' || value.includes('\0')) {
+                fail(`sets "${variable}" to a non-string`);
+            }
+        }
+        if (roles !== undefined &&
+            (!Array.isArray(roles) ||
+                roles.length === 0 ||
+                new Set(roles).size !== roles.length ||
+                !roles.every(role => typeof role === 'string' && isOneOf(commandRoles, role)))) {
+            fail(`needs roles to list some of ${commandRoles.join(', ')}, each once`);
+        }
+        if (args !== undefined && !Array.isArray(args))
+            fail('needs args to be a list');
+        const seen = new Set();
+        for (const argument of (args ?? [])) {
+            if (typeof argument === 'string') {
+                if (!isArgument(argument, { allowEmpty: true })) {
+                    fail('has an argument with a NUL character');
+                }
+                continue;
+            }
+            if (!isRecord(argument))
+                fail('has an argument that is neither text nor a parameter');
+            checkParameter(argument, seen, fail);
+        }
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function checkLimit(value, max, field, fail) {
+    if (value === undefined)
+        return;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0 || value > max) {
+        fail(`needs ${field} to be a whole number from 1 to ${String(max)}`);
+    }
+}
+function checkParameter(parameter, seen, fail) {
+    // Unknown: the configuration may come from a JSON file, whatever its type says.
+    const name = parameter.name;
+    if (typeof name !== 'string' || !namePattern.test(name) || name === reservedParameter) {
+        fail(`has a parameter with an invalid name ${typeof name === 'string' ? `"${name}"` : 'that is not text'}`);
+    }
+    if (seen.has(name))
+        fail(`uses the parameter "${name}" twice`);
+    seen.add(name);
+    if (typeof parameter.description !== 'string' || parameter.description.trim() === '') {
+        fail(`needs a description for the parameter "${name}"`);
+    }
+    const { required } = parameter;
+    if (required !== undefined && typeof required !== 'boolean') {
+        fail(`needs required to be true or false for the parameter "${name}"`);
+    }
+    switch (parameter.type) {
+        case 'paths':
+            return;
+        case 'choice':
+            if (!Array.isArray(parameter.values) ||
+                parameter.values.length === 0 ||
+                !parameter.values.every(value => typeof value === 'string' && isArgument(value))) {
+                fail(`needs the choice "${name}" to list at least one value`);
+            }
+            return;
+        case 'text':
+            if (typeof parameter.pattern !== 'string')
+                fail(`needs a pattern for the text "${name}"`);
+            try {
+                textMatcher(parameter.pattern);
+            }
+            catch {
+                fail(`has a pattern for the text "${name}" that is not a valid regular expression`);
+            }
+            return;
+        default:
+            fail(`has a parameter "${name}" of an unknown type`);
+    }
+}
+function isArgument(value, { allowEmpty = false } = {}) {
+    return (allowEmpty || value !== '') && !value.includes('\0');
+}
+function textMatcher(pattern) {
+    return new RegExp(`^(?:${pattern})$`, 'u');
+}
+/** The commands `role` may run: those that name it, or, without `roles`, the executor. */
+export function commandsFor(commands, role) {
+    return Object.fromEntries(Object.entries(commands).filter(([, definition]) => (definition.roles ?? ['executor']).includes(role)));
+}
+/** The parameters of a command, in the order its arguments use them. */
+export function parametersOf(definition) {
+    return (definition.args ?? []).filter(argument => typeof argument !== 'string');
+}
+/**
+ * The arguments a call runs with: the fixed ones as declared, and each parameter replaced by
+ * the value the model gave, once checked.
+ *
+ * @throws {Error} worded for the model, when a value is not one the parameter takes.
+ */
+export function buildArguments(definition, values) {
+    const args = [];
+    for (const argument of definition.args ?? []) {
+        if (typeof argument === 'string') {
+            args.push(argument);
+            continue;
+        }
+        const value = values[argument.name] ?? null;
+        args.push(...valueArguments(argument, value));
+    }
+    return args;
+}
+function valueArguments(parameter, value) {
+    const { name } = parameter;
+    if (parameter.type === 'paths') {
+        if (!Array.isArray(value))
+            throw new Error(`"${name}" takes a list of paths`);
+        return value;
+    }
+    if (value === null) {
+        if (parameter.required === true)
+            throw new Error(`"${name}" is required`);
+        return [];
+    }
+    if (typeof value !== 'string')
+        throw new Error(`"${name}" takes one value`);
+    if (parameter.type === 'choice') {
+        if (!parameter.values.includes(value)) {
+            throw new Error(`"${name}" takes one of: ${parameter.values.join(', ')}`);
+        }
+        return [value];
+    }
+    if (value.startsWith('-'))
+        throw new Error(`"${name}" may not start with "-"`);
+    if (value.length > maxTextLength ||
+        value.includes('\0') ||
+        !textMatcher(parameter.pattern).test(value)) {
+        throw new Error(`"${name}" must match ${parameter.pattern}`);
+    }
+    return [value];
+}
+//# sourceMappingURL=commands.js.map

package/dist/tools/domain/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../../src/tools/domain/commands.ts"],"names":[],"mappings":"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","sourcesContent":["import { InvalidAgentConfigError } from '#src/shared/domain/errors';\nimport { isOneOf } from '#src/shared/domain/isOneOf';\n\n/**\n * Something the model fills in a command's arguments. It never writes free arguments: each\n * value is checked against what the consumer declared here, and none can become a flag it did\n * not declare.\n *\n * - `paths`: files or folders inside the roots that the agent may read, each its own argument,\n *   relative to the command's working directory. The model may give none.\n * - `choice`: one of `values`, as the consumer wrote them, so a value may be a flag.\n * - `text`: a value that matches `pattern` whole, and never starts with `-`.\n *\n * A `choice` or `text` that is not `required` may be left out, and then adds no argument.\n */\nexport type CommandParameter =\n\t| { type: 'paths'; name: string; description: string }\n\t| { type: 'choice'; name: string; description: string; values: string[]; required?: boolean }\n\t| { type: 'text'; name: string; description: string; pattern: string; required?: boolean };\n\n/** One argument of a command: fixed text, or the place where a parameter goes. */\nexport type CommandArgument = string | CommandParameter;\n\n/** The roles of the model-backed orchestrator a command can be given to. */\nexport const commandRoles = ['planner', 'executor', 'reviewer'] as const;\nexport type CommandRole = (typeof commandRoles)[number];\n\n/**\n * A command the consumer lets the agent run, such as the project's tests or its formatter. It\n * runs without a shell, so nothing in an argument is ever read as shell syntax.\n */\nexport interface CommandDefinition {\n\t/** What it does and when to run it, for the model. */\n\tdescription: string;\n\t/**\n\t * The program: a name looked up in the command's `PATH`, or a path. A relative path is from\n\t * `cwd`.\n\t */\n\texecutable: string;\n\targs?: CommandArgument[];\n\t/**\n\t * Where it runs, inside a `write` root: relative to the first root, or absolute. Defaults to\n\t * the first root.\n\t */\n\tcwd?: string;\n\t/**\n\t * Variables set for it, on top of the few it inherits: `PATH`, `HOME`, `TMPDIR`, `USER`,\n\t * `SHELL`, `LANG` and `LC_*`. Nothing else of this process's environment reaches it, so\n\t * neither do the provider keys.\n\t */\n\tenv?: Record<string, string>;\n\t/** How long it may run before its whole process group is stopped. Defaults to 10 minutes. */\n\ttimeoutMs?: number;\n\t/** How much of the end of its output the model reads. Defaults to 16 KB. */\n\toutputBytes?: number;\n\t/**\n\t * Which roles of `createLLMOrchestrator` may run it, such as the planner for a command that\n\t * reads an issue. Defaults to the executor only. Whoever runs it, the files are captured\n\t * around it, so what it changes is in the history. `createFileTools` offers every command.\n\t */\n\troles?: CommandRole[];\n}\n\n/** The commands an agent may run, by the name the model calls each one. */\nexport type Commands = Record<string, CommandDefinition>;\n\nexport const defaultCommandTimeoutMs = 10 * 60 * 1000;\nexport const defaultCommandOutputBytes = 16 * 1024;\n// A test filter or a snapshot name, not a script.\nconst maxTextLength = 1000;\nconst maxOutputBytes = 1024 * 1024;\nconst maxTimeoutMs = 24 * 60 * 60 * 1000;\n\nconst namePattern = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;\nconst variablePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;\n// The tool's input names the command with this key, so no parameter may take it.\nconst reservedParameter = 'name';\n\n/** A parameter's value as the model sent it, with `paths` already checked and resolved. */\nexport type ParameterValue = string[] | string | null;\n\n/**\n * Checks every command before an agent is built, so a mistake in the configuration fails there\n * and never as a refused call in the middle of a run.\n *\n * @throws {InvalidAgentConfigError} for the first thing that is wrong.\n */\nexport function validateCommands(commands: Commands): void {\n\t// Unknown throughout: the configuration may come from a JSON file, whatever its type says.\n\tif (!isRecord(commands)) throw new InvalidAgentConfigError('Commands must be an object');\n\tconst entries = Object.entries(commands as Record<string, unknown>);\n\tif (entries.length === 0) throw new InvalidAgentConfigError('No command is configured');\n\tfor (const [name, definition] of entries) {\n\t\tconst fail = (problem: string) => {\n\t\t\tthrow new InvalidAgentConfigError(`Command \"${name}\" ${problem}`);\n\t\t};\n\t\tif (!namePattern.test(name)) {\n\t\t\tfail('needs a name of letters, digits, \"-\" and \"_\", starting with a letter');\n\t\t}\n\t\tif (!isRecord(definition)) fail('must be an object');\n\t\tconst { description, executable, cwd, timeoutMs, outputBytes, env, args, roles } =\n\t\t\tdefinition as Record<string, unknown>;\n\t\tif (typeof description !== 'string' || description.trim() === '') {\n\t\t\tfail('needs a description');\n\t\t}\n\t\tif (typeof executable !== 'string' || !isArgument(executable)) fail('needs an executable');\n\t\tif (cwd !== undefined && (typeof cwd !== 'string' || !isArgument(cwd))) {\n\t\t\tfail('has an invalid cwd');\n\t\t}\n\t\tcheckLimit(timeoutMs, maxTimeoutMs, 'timeoutMs', fail);\n\t\tcheckLimit(outputBytes, maxOutputBytes, 'outputBytes', fail);\n\t\tif (env !== undefined && !isRecord(env)) fail('needs env to map names to values');\n\t\tfor (const [variable, value] of Object.entries((env ?? {}) as Record<string, unknown>)) {\n\t\t\tif (!variablePattern.test(variable)) fail(`sets an invalid variable name \"${variable}\"`);\n\t\t\tif (typeof value !== 'string' || value.includes('\\0')) {\n\t\t\t\tfail(`sets \"${variable}\" to a non-string`);\n\t\t\t}\n\t\t}\n\n\t\tif (\n\t\t\troles !== undefined &&\n\t\t\t(!Array.isArray(roles) ||\n\t\t\t\troles.length === 0 ||\n\t\t\t\tnew Set(roles).size !== roles.length ||\n\t\t\t\t!roles.every(role => typeof role === 'string' && isOneOf(commandRoles, role)))\n\t\t) {\n\t\t\tfail(`needs roles to list some of ${commandRoles.join(', ')}, each once`);\n\t\t}\n\t\tif (args !== undefined && !Array.isArray(args)) fail('needs args to be a list');\n\t\tconst seen = new Set<string>();\n\t\tfor (const argument of (args ?? []) as unknown[]) {\n\t\t\tif (typeof argument === 'string') {\n\t\t\t\tif (!isArgument(argument, { allowEmpty: true })) {\n\t\t\t\t\tfail('has an argument with a NUL character');\n\t\t\t\t}\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!isRecord(argument)) fail('has an argument that is neither text nor a parameter');\n\t\t\tcheckParameter(argument as CommandParameter, seen, fail);\n\t\t}\n\t}\n}\n\nfunction isRecord(value: unknown): boolean {\n\treturn typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction checkLimit(\n\tvalue: unknown,\n\tmax: number,\n\tfield: string,\n\tfail: (problem: string) => never,\n): void {\n\tif (value === undefined) return;\n\tif (typeof value !== 'number' || !Number.isInteger(value) || value <= 0 || value > max) {\n\t\tfail(`needs ${field} to be a whole number from 1 to ${String(max)}`);\n\t}\n}\n\nfunction checkParameter(\n\tparameter: CommandParameter,\n\tseen: Set<string>,\n\tfail: (problem: string) => never,\n): void {\n\t// Unknown: the configuration may come from a JSON file, whatever its type says.\n\tconst name: unknown = parameter.name;\n\tif (typeof name !== 'string' || !namePattern.test(name) || name === reservedParameter) {\n\t\tfail(\n\t\t\t`has a parameter with an invalid name ${typeof name === 'string' ? `\"${name}\"` : 'that is not text'}`,\n\t\t);\n\t}\n\tif (seen.has(name)) fail(`uses the parameter \"${name}\" twice`);\n\tseen.add(name);\n\tif (typeof parameter.description !== 'string' || parameter.description.trim() === '') {\n\t\tfail(`needs a description for the parameter \"${name}\"`);\n\t}\n\tconst { required } = parameter as { required?: unknown };\n\tif (required !== undefined && typeof required !== 'boolean') {\n\t\tfail(`needs required to be true or false for the parameter \"${name}\"`);\n\t}\n\n\tswitch (parameter.type) {\n\t\tcase 'paths':\n\t\t\treturn;\n\t\tcase 'choice':\n\t\t\tif (\n\t\t\t\t!Array.isArray(parameter.values) ||\n\t\t\t\tparameter.values.length === 0 ||\n\t\t\t\t!parameter.values.every(value => typeof value === 'string' && isArgument(value))\n\t\t\t) {\n\t\t\t\tfail(`needs the choice \"${name}\" to list at least one value`);\n\t\t\t}\n\t\t\treturn;\n\t\tcase 'text':\n\t\t\tif (typeof parameter.pattern !== 'string') fail(`needs a pattern for the text \"${name}\"`);\n\t\t\ttry {\n\t\t\t\ttextMatcher(parameter.pattern);\n\t\t\t} catch {\n\t\t\t\tfail(`has a pattern for the text \"${name}\" that is not a valid regular expression`);\n\t\t\t}\n\t\t\treturn;\n\t\tdefault:\n\t\t\tfail(`has a parameter \"${name}\" of an unknown type`);\n\t}\n}\n\nfunction isArgument(value: string, { allowEmpty = false } = {}): boolean {\n\treturn (allowEmpty || value !== '') && !value.includes('\\0');\n}\n\nfunction textMatcher(pattern: string): RegExp {\n\treturn new RegExp(`^(?:${pattern})$`, 'u');\n}\n\n/** The commands `role` may run: those that name it, or, without `roles`, the executor. */\nexport function commandsFor(commands: Commands, role: CommandRole): Commands {\n\treturn Object.fromEntries(\n\t\tObject.entries(commands).filter(([, definition]) =>\n\t\t\t(definition.roles ?? ['executor']).includes(role),\n\t\t),\n\t);\n}\n\n/** The parameters of a command, in the order its arguments use them. */\nexport function parametersOf(definition: CommandDefinition): CommandParameter[] {\n\treturn (definition.args ?? []).filter(argument => typeof argument !== 'string');\n}\n\n/**\n * The arguments a call runs with: the fixed ones as declared, and each parameter replaced by\n * the value the model gave, once checked.\n *\n * @throws {Error} worded for the model, when a value is not one the parameter takes.\n */\nexport function buildArguments(\n\tdefinition: CommandDefinition,\n\tvalues: Record<string, ParameterValue>,\n): string[] {\n\tconst args: string[] = [];\n\tfor (const argument of definition.args ?? []) {\n\t\tif (typeof argument === 'string') {\n\t\t\targs.push(argument);\n\t\t\tcontinue;\n\t\t}\n\t\tconst value = values[argument.name] ?? null;\n\t\targs.push(...valueArguments(argument, value));\n\t}\n\treturn args;\n}\n\nfunction valueArguments(parameter: CommandParameter, value: ParameterValue): string[] {\n\tconst { name } = parameter;\n\tif (parameter.type === 'paths') {\n\t\tif (!Array.isArray(value)) throw new Error(`\"${name}\" takes a list of paths`);\n\t\treturn value;\n\t}\n\tif (value === null) {\n\t\tif (parameter.required === true) throw new Error(`\"${name}\" is required`);\n\t\treturn [];\n\t}\n\tif (typeof value !== 'string') throw new Error(`\"${name}\" takes one value`);\n\n\tif (parameter.type === 'choice') {\n\t\tif (!parameter.values.includes(value)) {\n\t\t\tthrow new Error(`\"${name}\" takes one of: ${parameter.values.join(', ')}`);\n\t\t}\n\t\treturn [value];\n\t}\n\n\tif (value.startsWith('-')) throw new Error(`\"${name}\" may not start with \"-\"`);\n\tif (\n\t\tvalue.length > maxTextLength ||\n\t\tvalue.includes('\\0') ||\n\t\t!textMatcher(parameter.pattern).test(value)\n\t) {\n\t\tthrow new Error(`\"${name}\" must match ${parameter.pattern}`);\n\t}\n\treturn [value];\n}\n"]}

package/dist/tools/domain/editResponse.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What a modification returns: its path, then the lines around each change as the file now
+ * reads them, numbered, with two lines of context. The model can check its edit without reading
+ * the file again. What does not fit is counted, not shown.
+ */
+export declare function describeModification(path: string, before: string, after: string): string;
+/**
+ * An edit as a git-style unified diff, for the person watching it happen. A missing side is a
+ * file that did not exist, or no longer does. Too long a diff is cut, and says so.
+ */
+export declare function editDiff(path: string, before: string | undefined, after: string | undefined): string;
+/** What a creation returns: a confirmation and the size, not the content the model just sent. */
+export declare function describeCreation(path: string, content: Buffer): string;
+export declare function describeDeletion(path: string): string;

package/dist/tools/domain/editResponse.js

@@ -0,0 +1,79 @@
+import { unifiedDiff } from '#src/diff/domain/unifiedDiff';
+import { cutLine } from "./lineLength.js";
+// Enough to place a change without reading the file again.
+const contextLines = 2;
+// What one response may show: a large rewrite is named, not repeated.
+const maxShownLines = 60;
+/** A line of `path` as the model reads it: without the `\r` of a CRLF ending, and not too long. */
+function shownLine(path, text) {
+    return cutLine(path, text.endsWith('\r') ? text.slice(0, -1) : text);
+}
+function lineCount(text) {
+    if (text === '')
+        return 0;
+    const lines = text.split('\n');
+    return lines.at(-1) === '' ? lines.length - 1 : lines.length;
+}
+/**
+ * What a modification returns: its path, then the lines around each change as the file now
+ * reads them, numbered, with two lines of context. The model can check its edit without reading
+ * the file again. What does not fit is counted, not shown.
+ */
+export function describeModification(path, before, after) {
+    if (after === '')
+        return `Changed ${path}. The file is now empty.`;
+    const shown = [];
+    let hidden = 0;
+    let line = 0;
+    for (const text of unifiedDiff(before, after, { context: contextLines }).split('\n')) {
+        const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(text);
+        if (hunk) {
+            if (shown.length > 0 && shown.length < maxShownLines)
+                shown.push('…');
+            line = Number(hunk[1]);
+            continue;
+        }
+        // Removed lines are gone from the file, and git's marker is not a line of it.
+        if (!text.startsWith(' ') && !text.startsWith('+'))
+            continue;
+        if (shown.length < maxShownLines) {
+            shown.push(`${String(line)}: ${shownLine(path, text.slice(1))}`);
+        }
+        else
+            hidden++;
+        line++;
+    }
+    const header = `Changed ${path}. It now reads, around the change:`;
+    const notice = hidden > 0
+        ? [`[${String(hidden)} more lines of the change are not shown. Read the file to see them.]`]
+        : [];
+    return [header, ...shown, ...notice].join('\n');
+}
+// What one edit's diff may hold for the person watching; the history keeps the whole change.
+const maxDiffLines = 400;
+/**
+ * An edit as a git-style unified diff, for the person watching it happen. A missing side is a
+ * file that did not exist, or no longer does. Too long a diff is cut, and says so.
+ */
+export function editDiff(path, before, after) {
+    const lines = [
+        `--- ${before === undefined ? '/dev/null' : `a/${path}`}`,
+        `+++ ${after === undefined ? '/dev/null' : `b/${path}`}`,
+        ...unifiedDiff(before ?? '', after ?? '', { context: contextLines }).split('\n'),
+    ];
+    if (lines.length <= maxDiffLines)
+        return lines.join('\n');
+    return [
+        ...lines.slice(0, maxDiffLines),
+        `... ${String(lines.length - maxDiffLines)} more lines of the diff not shown`,
+    ].join('\n');
+}
+/** What a creation returns: a confirmation and the size, not the content the model just sent. */
+export function describeCreation(path, content) {
+    const lines = lineCount(content.toString('utf8'));
+    return `Created ${path} (${String(lines)} ${lines === 1 ? 'line' : 'lines'}, ${String(content.length)} bytes).`;
+}
+export function describeDeletion(path) {
+    return `Deleted ${path}.`;
+}
+//# sourceMappingURL=editResponse.js.map

package/dist/tools/domain/editResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editResponse.js","sourceRoot":"","sources":["../../../src/tools/domain/editResponse.ts"],"names":[],"mappings":"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","sourcesContent":["import { unifiedDiff } from '#src/diff/domain/unifiedDiff';\nimport { cutLine } from './lineLength.ts';\n\n// Enough to place a change without reading the file again.\nconst contextLines = 2;\n// What one response may show: a large rewrite is named, not repeated.\nconst maxShownLines = 60;\n/** A line of `path` as the model reads it: without the `\\r` of a CRLF ending, and not too long. */\nfunction shownLine(path: string, text: string): string {\n\treturn cutLine(path, text.endsWith('\\r') ? text.slice(0, -1) : text);\n}\n\nfunction lineCount(text: string): number {\n\tif (text === '') return 0;\n\tconst lines = text.split('\\n');\n\treturn lines.at(-1) === '' ? lines.length - 1 : lines.length;\n}\n\n/**\n * What a modification returns: its path, then the lines around each change as the file now\n * reads them, numbered, with two lines of context. The model can check its edit without reading\n * the file again. What does not fit is counted, not shown.\n */\nexport function describeModification(path: string, before: string, after: string): string {\n\tif (after === '') return `Changed ${path}. The file is now empty.`;\n\tconst shown: string[] = [];\n\tlet hidden = 0;\n\tlet line = 0;\n\tfor (const text of unifiedDiff(before, after, { context: contextLines }).split('\\n')) {\n\t\tconst hunk = /^@@ -\\d+(?:,\\d+)? \\+(\\d+)(?:,\\d+)? @@/.exec(text);\n\t\tif (hunk) {\n\t\t\tif (shown.length > 0 && shown.length < maxShownLines) shown.push('…');\n\t\t\tline = Number(hunk[1]);\n\t\t\tcontinue;\n\t\t}\n\t\t// Removed lines are gone from the file, and git's marker is not a line of it.\n\t\tif (!text.startsWith(' ') && !text.startsWith('+')) continue;\n\t\tif (shown.length < maxShownLines) {\n\t\t\tshown.push(`${String(line)}: ${shownLine(path, text.slice(1))}`);\n\t\t} else hidden++;\n\t\tline++;\n\t}\n\n\tconst header = `Changed ${path}. It now reads, around the change:`;\n\tconst notice =\n\t\thidden > 0\n\t\t\t? [`[${String(hidden)} more lines of the change are not shown. Read the file to see them.]`]\n\t\t\t: [];\n\treturn [header, ...shown, ...notice].join('\\n');\n}\n\n// What one edit's diff may hold for the person watching; the history keeps the whole change.\nconst maxDiffLines = 400;\n\n/**\n * An edit as a git-style unified diff, for the person watching it happen. A missing side is a\n * file that did not exist, or no longer does. Too long a diff is cut, and says so.\n */\nexport function editDiff(\n\tpath: string,\n\tbefore: string | undefined,\n\tafter: string | undefined,\n): string {\n\tconst lines = [\n\t\t`--- ${before === undefined ? '/dev/null' : `a/${path}`}`,\n\t\t`+++ ${after === undefined ? '/dev/null' : `b/${path}`}`,\n\t\t...unifiedDiff(before ?? '', after ?? '', { context: contextLines }).split('\\n'),\n\t];\n\tif (lines.length <= maxDiffLines) return lines.join('\\n');\n\treturn [\n\t\t...lines.slice(0, maxDiffLines),\n\t\t`... ${String(lines.length - maxDiffLines)} more lines of the diff not shown`,\n\t].join('\\n');\n}\n\n/** What a creation returns: a confirmation and the size, not the content the model just sent. */\nexport function describeCreation(path: string, content: Buffer): string {\n\tconst lines = lineCount(content.toString('utf8'));\n\treturn `Created ${path} (${String(lines)} ${lines === 1 ? 'line' : 'lines'}, ${String(content.length)} bytes).`;\n}\n\nexport function describeDeletion(path: string): string {\n\treturn `Deleted ${path}.`;\n}\n"]}

package/dist/tools/domain/fileEdits.d.ts

@@ -0,0 +1,64 @@
+import type { FileState } from '#src/recovery/domain/recoveryStore';
+import type { AllowedPath } from './accessPolicy.ts';
+/**
+ * One change to one file, with the path as the model wrote it. Each edit format, such as a
+ * patch or a text replacement, works out the whole new content and asks for one of these.
+ *
+ * `expected` is the hash of the content the change was worked out from. It is refused if the
+ * file no longer holds it, so a change is never applied to a version nobody looked at.
+ */
+export type FileChange = {
+    kind: 'create';
+    path: string;
+    content: Buffer;
+} | {
+    kind: 'replace';
+    path: string;
+    content: Buffer;
+    expected?: string;
+} | {
+    kind: 'delete';
+    path: string;
+    expected?: string;
+};
+/**
+ * A change checked and ready to apply, and the only thing that can be applied: what is
+ * approved is exactly what is written. It is applied only if the file still holds `before`.
+ */
+export interface PreparedEdit {
+    readonly kind: FileChange['kind'];
+    /** As the model wrote it, for every message about it. */
+    readonly path: string;
+    readonly target: AllowedPath;
+    readonly before: FileState;
+    /**
+     * The editor's own copy, taken in `prepare`, for showing what will be written. Its bytes can
+     * still be changed, so `apply` writes them only while they match `contentHash`.
+     */
+    readonly content: Buffer | undefined;
+    /** The SHA-256 of `content` as prepared. */
+    readonly contentHash: string | undefined;
+    /**
+     * The change can make `.gitignore` hide less, which would open paths to every tool. It
+     * takes effect only if the user allows it: a tool asks for it as `destructive`.
+     */
+    readonly widensIgnoreRules: boolean;
+}
+/**
+ * Why a change was not made, worded for the model. Nothing was written: the file is as it was.
+ */
+export declare class EditRefusedError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A change the file may hold but the run's record does not confirm, worded for the model: it was
+ * made and could not be recorded as made, or whether it was made cannot be told. The record keeps
+ * the change as prepared, so an undo can still check the file, and writing stops for the run.
+ */
+export declare class EditUnconfirmedError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/tools/domain/fileEdits.js

@@ -0,0 +1,21 @@
+/**
+ * Why a change was not made, worded for the model. Nothing was written: the file is as it was.
+ */
+export class EditRefusedError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'EditRefusedError';
+    }
+}
+/**
+ * A change the file may hold but the run's record does not confirm, worded for the model: it was
+ * made and could not be recorded as made, or whether it was made cannot be told. The record keeps
+ * the change as prepared, so an undo can still check the file, and writing stops for the run.
+ */
+export class EditUnconfirmedError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'EditUnconfirmedError';
+    }
+}
+//# sourceMappingURL=fileEdits.js.map

package/dist/tools/domain/fileEdits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileEdits.js","sourceRoot":"","sources":["../../../src/tools/domain/fileEdits.ts"],"names":[],"mappings":"AAuCA;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAC1C,YAAY,OAAe,EAAE,OAA6B;QACzD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IAChC,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC9C,YAAY,OAAe,EAAE,OAA6B;QACzD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACpC,CAAC;CACD","sourcesContent":["import type { FileState } from '#src/recovery/domain/recoveryStore';\nimport type { AllowedPath } from './accessPolicy.ts';\n\n/**\n * One change to one file, with the path as the model wrote it. Each edit format, such as a\n * patch or a text replacement, works out the whole new content and asks for one of these.\n *\n * `expected` is the hash of the content the change was worked out from. It is refused if the\n * file no longer holds it, so a change is never applied to a version nobody looked at.\n */\nexport type FileChange =\n\t| { kind: 'create'; path: string; content: Buffer }\n\t| { kind: 'replace'; path: string; content: Buffer; expected?: string }\n\t| { kind: 'delete'; path: string; expected?: string };\n\n/**\n * A change checked and ready to apply, and the only thing that can be applied: what is\n * approved is exactly what is written. It is applied only if the file still holds `before`.\n */\nexport interface PreparedEdit {\n\treadonly kind: FileChange['kind'];\n\t/** As the model wrote it, for every message about it. */\n\treadonly path: string;\n\treadonly target: AllowedPath;\n\treadonly before: FileState;\n\t/**\n\t * The editor's own copy, taken in `prepare`, for showing what will be written. Its bytes can\n\t * still be changed, so `apply` writes them only while they match `contentHash`.\n\t */\n\treadonly content: Buffer | undefined;\n\t/** The SHA-256 of `content` as prepared. */\n\treadonly contentHash: string | undefined;\n\t/**\n\t * The change can make `.gitignore` hide less, which would open paths to every tool. It\n\t * takes effect only if the user allows it: a tool asks for it as `destructive`.\n\t */\n\treadonly widensIgnoreRules: boolean;\n}\n\n/**\n * Why a change was not made, worded for the model. Nothing was written: the file is as it was.\n */\nexport class EditRefusedError extends Error {\n\tconstructor(message: string, options?: { cause?: unknown }) {\n\t\tsuper(message, options);\n\t\tthis.name = 'EditRefusedError';\n\t}\n}\n\n/**\n * A change the file may hold but the run's record does not confirm, worded for the model: it was\n * made and could not be recorded as made, or whether it was made cannot be told. The record keeps\n * the change as prepared, so an undo can still check the file, and writing stops for the run.\n */\nexport class EditUnconfirmedError extends Error {\n\tconstructor(message: string, options?: { cause?: unknown }) {\n\t\tsuper(message, options);\n\t\tthis.name = 'EditUnconfirmedError';\n\t}\n}\n"]}

package/dist/tools/domain/lineLength.d.ts

@@ -0,0 +1,7 @@
+/**
+ * How long a line of `path` may be before the model sees it cut: long for Markdown and plain
+ * text, short for everything else. See "Prose files show their long lines whole" in decisions.md.
+ */
+export declare function maxLineLength(path: string): number;
+/** `text` as the model reads it from `path`: cut, with a mark, when longer than the file's limit. */
+export declare function cutLine(path: string, text: string): string;

package/dist/tools/domain/lineLength.js

@@ -0,0 +1,26 @@
+// Code is where one line can be a whole minified bundle, larger than everything else the model
+// reads; a line of hand-written code fits well within this.
+const codeLineLength = 300;
+// Prose keeps a paragraph, or a table row, on one line. Cut, such a line cannot be copied into
+// an edit's context, so it is shown whole up to this, which also bounds a generated one.
+const proseLineLength = 5000;
+const proseExtensions = new Set(['.md', '.markdown', '.mdx', '.txt']);
+/**
+ * How long a line of `path` may be before the model sees it cut: long for Markdown and plain
+ * text, short for everything else. See "Prose files show their long lines whole" in decisions.md.
+ */
+export function maxLineLength(path) {
+    return proseExtensions.has(extensionOf(path)) ? proseLineLength : codeLineLength;
+}
+/** The extension of the file's own name, lower case: `.md` for `docs/A.MD`, none for `.md`. */
+function extensionOf(path) {
+    const name = path.slice(Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\')) + 1);
+    const dot = name.lastIndexOf('.');
+    return dot > 0 ? name.slice(dot).toLowerCase() : '';
+}
+/** `text` as the model reads it from `path`: cut, with a mark, when longer than the file's limit. */
+export function cutLine(path, text) {
+    const max = maxLineLength(path);
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+//# sourceMappingURL=lineLength.js.map

package/dist/tools/domain/lineLength.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineLength.js","sourceRoot":"","sources":["../../../src/tools/domain/lineLength.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,4DAA4D;AAC5D,MAAM,cAAc,GAAG,GAAG,CAAC;AAC3B,+FAA+F;AAC/F,yFAAyF;AACzF,MAAM,eAAe,GAAG,IAAI,CAAC;AAC7B,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEtE;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACzC,OAAO,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,cAAc,CAAC;AAClF,CAAC;AAED,+FAA+F;AAC/F,SAAS,WAAW,CAAC,IAAY;IAChC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACrF,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACrD,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,IAAY;IACjD,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAChC,OAAO,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5D,CAAC","sourcesContent":["// Code is where one line can be a whole minified bundle, larger than everything else the model\n// reads; a line of hand-written code fits well within this.\nconst codeLineLength = 300;\n// Prose keeps a paragraph, or a table row, on one line. Cut, such a line cannot be copied into\n// an edit's context, so it is shown whole up to this, which also bounds a generated one.\nconst proseLineLength = 5000;\nconst proseExtensions = new Set(['.md', '.markdown', '.mdx', '.txt']);\n\n/**\n * How long a line of `path` may be before the model sees it cut: long for Markdown and plain\n * text, short for everything else. See \"Prose files show their long lines whole\" in decisions.md.\n */\nexport function maxLineLength(path: string): number {\n\treturn proseExtensions.has(extensionOf(path)) ? proseLineLength : codeLineLength;\n}\n\n/** The extension of the file's own name, lower case: `.md` for `docs/A.MD`, none for `.md`. */\nfunction extensionOf(path: string): string {\n\tconst name = path.slice(Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\\\')) + 1);\n\tconst dot = name.lastIndexOf('.');\n\treturn dot > 0 ? name.slice(dot).toLowerCase() : '';\n}\n\n/** `text` as the model reads it from `path`: cut, with a mark, when longer than the file's limit. */\nexport function cutLine(path: string, text: string): string {\n\tconst max = maxLineLength(path);\n\treturn text.length > max ? `${text.slice(0, max)}…` : text;\n}\n"]}

package/dist/tools/domain/preparedCall.d.ts

@@ -0,0 +1,31 @@
+import type { CommandLine, ToolRisk } from '#src/agent/domain/approval';
+import type { ToolDefinition } from '#src/llm/domain/tool';
+import type { ToolCallContext } from './readRegistry.ts';
+import type { Tool } from './tool.ts';
+/**
+ * A tool call checked and fixed before anyone approves it: its risk is judged on what will
+ * really happen, and `run` does exactly that, nothing worked out again.
+ */
+export interface PreparedCall {
+    readonly risk: ToolRisk;
+    /** For a change to a file, what it will change as a unified diff, fixed when prepared. */
+    readonly diff?: string;
+    /** For a call that runs a configured command, what it will run, fixed when prepared. */
+    readonly command?: CommandLine;
+    run(signal: AbortSignal): Promise<string>;
+}
+/**
+ * A tool built by the harness, such as a write tool, which prepares each call against the
+ * state of the run before it is approved. Internal: consumers build a `Tool`.
+ */
+export interface PreparingTool extends ToolDefinition {
+    /** Rejects with a message for the model when the call cannot run. */
+    prepare(input: unknown, signal: AbortSignal, call: ToolCallContext): Promise<PreparedCall>;
+}
+/** What an agent can run: a consumer's `Tool`, or one the harness built. */
+export type AgentTool = Tool | PreparingTool;
+/**
+ * Brings any tool into the one lifecycle of prepare, approve, run. A consumer's `Tool` has its
+ * risk judged now, and later runs on the input as the model sent it.
+ */
+export declare function prepareCall(tool: AgentTool, input: unknown, signal: AbortSignal, call: ToolCallContext): Promise<PreparedCall>;

package/dist/tools/domain/preparedCall.js

@@ -0,0 +1,14 @@
+function isPreparing(tool) {
+    return 'prepare' in tool;
+}
+/**
+ * Brings any tool into the one lifecycle of prepare, approve, run. A consumer's `Tool` has its
+ * risk judged now, and later runs on the input as the model sent it.
+ */
+export async function prepareCall(tool, input, signal, call) {
+    if (isPreparing(tool))
+        return tool.prepare(input, signal, call);
+    const risk = tool.risk(input);
+    return { risk, run: runSignal => tool.execute(input, runSignal) };
+}
+//# sourceMappingURL=preparedCall.js.map

package/dist/tools/domain/preparedCall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preparedCall.js","sourceRoot":"","sources":["../../../src/tools/domain/preparedCall.ts"],"names":[],"mappings":"AA8BA,SAAS,WAAW,CAAC,IAAe;IACnC,OAAO,SAAS,IAAI,IAAI,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAChC,IAAe,EACf,KAAc,EACd,MAAmB,EACnB,IAAqB;IAErB,IAAI,WAAW,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAEhE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9B,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;AACnE,CAAC","sourcesContent":["import type { CommandLine, ToolRisk } from '#src/agent/domain/approval';\nimport type { ToolDefinition } from '#src/llm/domain/tool';\nimport type { ToolCallContext } from './readRegistry.ts';\nimport type { Tool } from './tool.ts';\n\n/**\n * A tool call checked and fixed before anyone approves it: its risk is judged on what will\n * really happen, and `run` does exactly that, nothing worked out again.\n */\nexport interface PreparedCall {\n\treadonly risk: ToolRisk;\n\t/** For a change to a file, what it will change as a unified diff, fixed when prepared. */\n\treadonly diff?: string;\n\t/** For a call that runs a configured command, what it will run, fixed when prepared. */\n\treadonly command?: CommandLine;\n\trun(signal: AbortSignal): Promise<string>;\n}\n\n/**\n * A tool built by the harness, such as a write tool, which prepares each call against the\n * state of the run before it is approved. Internal: consumers build a `Tool`.\n */\nexport interface PreparingTool extends ToolDefinition {\n\t/** Rejects with a message for the model when the call cannot run. */\n\tprepare(input: unknown, signal: AbortSignal, call: ToolCallContext): Promise<PreparedCall>;\n}\n\n/** What an agent can run: a consumer's `Tool`, or one the harness built. */\nexport type AgentTool = Tool | PreparingTool;\n\nfunction isPreparing(tool: AgentTool): tool is PreparingTool {\n\treturn 'prepare' in tool;\n}\n\n/**\n * Brings any tool into the one lifecycle of prepare, approve, run. A consumer's `Tool` has its\n * risk judged now, and later runs on the input as the model sent it.\n */\nexport async function prepareCall(\n\ttool: AgentTool,\n\tinput: unknown,\n\tsignal: AbortSignal,\n\tcall: ToolCallContext,\n): Promise<PreparedCall> {\n\tif (isPreparing(tool)) return tool.prepare(input, signal, call);\n\n\tconst risk = tool.risk(input);\n\treturn { risk, run: runSignal => tool.execute(input, runSignal) };\n}\n"]}

package/dist/tools/domain/readRegistry.d.ts

@@ -0,0 +1,46 @@
+import type { RunContext } from '#src/agent/domain/runContext';
+/**
+ * What one conversation has seen of each file: the hash of the content a read showed it, or an
+ * edit of its own left. An edit is made only from that version, so the model never changes a
+ * file it has not read, or one that changed since.
+ *
+ * Keyed by the file's real path, so two spellings of one file are one entry. It belongs to the
+ * conversation, not to the run: each role, with its own conversation, has its own.
+ */
+export declare class ReadRegistry {
+    private seen;
+    /** The reads of one run, which count for the conversation only once the run succeeded. */
+    begin(): RunReads;
+    /**
+     * Forgets every file: the workspace moved through its history, so what the conversation saw
+     * may no longer be what the files hold.
+     */
+    clear(): void;
+}
+/**
+ * The versions one run has seen, on top of what its conversation saw before it. A failed run
+ * records nothing in its conversation, so the model does not remember what it read there: its
+ * reads are kept only by `commit`.
+ */
+export declare class RunReads {
+    private readonly base;
+    private readonly own;
+    private readonly save;
+    constructor(base: ReadonlyMap<string, string>, save: (seen: Map<string, string>) => void);
+    /** The version of `absolute` the conversation has seen, if any. */
+    versionOf(absolute: string): string | undefined;
+    /** The conversation now knows `absolute` as holding the content `hash` names. */
+    record(absolute: string, hash: string): void;
+    /** The file is gone, as the conversation knows it. */
+    forget(absolute: string): void;
+    /** Keeps this run's reads for the conversation's next runs. */
+    commit(): void;
+}
+/**
+ * What a harness-built tool gets for one call: the run it belongs to, shared by every role, and
+ * the reads of the conversation that made the call.
+ */
+export interface ToolCallContext {
+    readonly run: RunContext;
+    readonly reads: RunReads;
+}