@mikode13/harness 4.0.1 → 5.1.0

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

@@ -0,0 +1,8 @@
+/** Whether a file or folder name is one of the usual credential files. */
+export declare function isSecretName(name: string): boolean;
+/**
+ * Whether an absolute path names a file the harness treats as a secret by default. It goes by
+ * names and places, so it is a filter for the usual suspects, not a detector: a key pasted into
+ * an ordinary source file is not found.
+ */
+export declare function isSecretPath(path: string, home: string): boolean;

package/dist/tools/infrastructure/secretPaths.js

@@ -0,0 +1,76 @@
+import { isAbsolute, relative, sep } from 'node:path';
+// Every name is compared in lower case: on macOS `.ENV` is the same file as `.env`.
+/** File names that hold credentials wherever they are. */
+const secretNames = new Set([
+    '.env',
+    '.envrc',
+    '.netrc',
+    '.pgpass',
+    '.git-credentials',
+    'id_rsa',
+    'id_dsa',
+    'id_ecdsa',
+    'id_ed25519',
+    'id_ecdsa_sk',
+    'id_ed25519_sk',
+]);
+/** Endings of key stores, private keys and state files that embed secrets. */
+const secretEndings = [
+    '.pem',
+    '.key',
+    '.p12',
+    '.pfx',
+    '.jks',
+    '.keystore',
+    '.tfstate',
+    '.tfstate.backup',
+];
+/** `.env.local` and its kind hold real values; these endings mark a template to copy from. */
+const environmentTemplates = ['.example', '.sample', '.template'];
+/** Folders under the home directory that only hold credentials. */
+const secretHomeFolders = [
+    '.ssh',
+    '.aws',
+    '.gnupg',
+    '.azure',
+    '.kube',
+    '.password-store',
+    '.config/gcloud',
+    '.config/gh',
+    'Library/Keychains',
+].map(folder => folder.toLowerCase());
+/** Files under the home directory that hold registry or tool tokens. */
+const secretHomeFiles = ['.npmrc', '.pypirc', '.docker/config.json', '.config/git/credentials'].map(file => file.toLowerCase());
+/** `path` below `folder`, as lower-case components, or undefined when it is not inside. */
+function inside(folder, path) {
+    const below = relative(folder.toLowerCase(), path.toLowerCase());
+    if (below === '..' || below.startsWith(`..${sep}`) || isAbsolute(below))
+        return undefined;
+    return below.split(sep).join('/');
+}
+/** Whether a file or folder name is one of the usual credential files. */
+export function isSecretName(name) {
+    const lower = name.toLowerCase();
+    if (secretNames.has(lower))
+        return true;
+    if (lower.startsWith('.env.')) {
+        return !environmentTemplates.some(ending => lower.endsWith(ending));
+    }
+    return secretEndings.some(ending => lower.endsWith(ending));
+}
+/**
+ * Whether an absolute path names a file the harness treats as a secret by default. It goes by
+ * names and places, so it is a filter for the usual suspects, not a detector: a key pasted into
+ * an ordinary source file is not found.
+ */
+export function isSecretPath(path, home) {
+    const name = path.split(sep).at(-1) ?? '';
+    if (isSecretName(name))
+        return true;
+    const underHome = inside(home, path);
+    if (underHome === undefined || underHome === '')
+        return false;
+    return (secretHomeFolders.some(folder => underHome === folder || underHome.startsWith(`${folder}/`)) ||
+        secretHomeFiles.includes(underHome));
+}
+//# sourceMappingURL=secretPaths.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secretPaths.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/secretPaths.ts"],"names":[],"mappings":"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","sourcesContent":["import { isAbsolute, relative, sep } from 'node:path';\n\n// Every name is compared in lower case: on macOS `.ENV` is the same file as `.env`.\n\n/** File names that hold credentials wherever they are. */\nconst secretNames = new Set([\n\t'.env',\n\t'.envrc',\n\t'.netrc',\n\t'.pgpass',\n\t'.git-credentials',\n\t'id_rsa',\n\t'id_dsa',\n\t'id_ecdsa',\n\t'id_ed25519',\n\t'id_ecdsa_sk',\n\t'id_ed25519_sk',\n]);\n\n/** Endings of key stores, private keys and state files that embed secrets. */\nconst secretEndings = [\n\t'.pem',\n\t'.key',\n\t'.p12',\n\t'.pfx',\n\t'.jks',\n\t'.keystore',\n\t'.tfstate',\n\t'.tfstate.backup',\n];\n\n/** `.env.local` and its kind hold real values; these endings mark a template to copy from. */\nconst environmentTemplates = ['.example', '.sample', '.template'];\n\n/** Folders under the home directory that only hold credentials. */\nconst secretHomeFolders = [\n\t'.ssh',\n\t'.aws',\n\t'.gnupg',\n\t'.azure',\n\t'.kube',\n\t'.password-store',\n\t'.config/gcloud',\n\t'.config/gh',\n\t'Library/Keychains',\n].map(folder => folder.toLowerCase());\n\n/** Files under the home directory that hold registry or tool tokens. */\nconst secretHomeFiles = ['.npmrc', '.pypirc', '.docker/config.json', '.config/git/credentials'].map(\n\tfile => file.toLowerCase(),\n);\n\n/** `path` below `folder`, as lower-case components, or undefined when it is not inside. */\nfunction inside(folder: string, path: string): string | undefined {\n\tconst below = relative(folder.toLowerCase(), path.toLowerCase());\n\tif (below === '..' || below.startsWith(`..${sep}`) || isAbsolute(below)) return undefined;\n\treturn below.split(sep).join('/');\n}\n\n/** Whether a file or folder name is one of the usual credential files. */\nexport function isSecretName(name: string): boolean {\n\tconst lower = name.toLowerCase();\n\tif (secretNames.has(lower)) return true;\n\tif (lower.startsWith('.env.')) {\n\t\treturn !environmentTemplates.some(ending => lower.endsWith(ending));\n\t}\n\treturn secretEndings.some(ending => lower.endsWith(ending));\n}\n\n/**\n * Whether an absolute path names a file the harness treats as a secret by default. It goes by\n * names and places, so it is a filter for the usual suspects, not a detector: a key pasted into\n * an ordinary source file is not found.\n */\nexport function isSecretPath(path: string, home: string): boolean {\n\tconst name = path.split(sep).at(-1) ?? '';\n\tif (isSecretName(name)) return true;\n\n\tconst underHome = inside(home, path);\n\tif (underHome === undefined || underHome === '') return false;\n\treturn (\n\t\tsecretHomeFolders.some(folder => underHome === folder || underHome.startsWith(`${folder}/`)) ||\n\t\tsecretHomeFiles.includes(underHome)\n\t);\n}\n"]}

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

@@ -0,0 +1,12 @@
+import type { RecoveryStore } from '#src/recovery/domain/recoveryStore';
+import { type AccessPolicy } from '../domain/accessPolicy.ts';
+import type { PreparingTool } from '../domain/preparedCall.ts';
+/**
+ * `showChanges` for the planner and the reviewer: what the current task has changed so far, as a
+ * diff per file, from the run's own record. It shows only what the role may read: a secret the
+ * executor was allowed to write is counted, never shown.
+ */
+export declare function createShowChangesTool({ store, policy, }: {
+    store: RecoveryStore;
+    policy: AccessPolicy;
+}): PreparingTool;

package/dist/tools/infrastructure/showChangesTool.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { showChanges } from '#src/recovery/domain/runChanges';
+import { AccessDeniedError } from "../domain/accessPolicy.js";
+import { definePreparingTool } from "./defineTool.js";
+// A reviewer reads a change whole, but not a rewrite of the whole repository.
+const maxLines = 600;
+const nothingYet = 'Nothing has been changed in this task yet.';
+/**
+ * `showChanges` for the planner and the reviewer: what the current task has changed so far, as a
+ * diff per file, from the run's own record. It shows only what the role may read: a secret the
+ * executor was allowed to write is counted, never shown.
+ */
+export function createShowChangesTool({ store, policy, }) {
+    return definePreparingTool({
+        name: 'showChanges',
+        description: 'Shows what this task has changed in the repository so far, as a diff per file, in the order each file was first changed.',
+        input: z.object({}),
+        summarize: () => 'changes in this task',
+        prepare: (_, __, { run }) => Promise.resolve({
+            risk: 'safe',
+            run: async (signal) => {
+                const { runId } = run.historyRun;
+                if (runId === undefined)
+                    return nothingYet;
+                const diff = await showChanges(store, runId, {
+                    maxLines,
+                    visible: async (path) => {
+                        try {
+                            await policy.check(path, 'read', signal);
+                            return true;
+                        }
+                        catch (error) {
+                            if (error instanceof AccessDeniedError)
+                                return false;
+                            throw error;
+                        }
+                    },
+                });
+                return diff === '' ? nothingYet : diff;
+            },
+        }),
+    });
+}
+//# sourceMappingURL=showChangesTool.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"showChangesTool.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/showChangesTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAqB,MAAM,2BAA2B,CAAC;AAEjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,8EAA8E;AAC9E,MAAM,QAAQ,GAAG,GAAG,CAAC;AAErB,MAAM,UAAU,GAAG,4CAA4C,CAAC;AAEhE;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,EACrC,KAAK,EACL,MAAM,GAIN;IACA,OAAO,mBAAmB,CAAC;QAC1B,IAAI,EAAE,aAAa;QACnB,WAAW,EACV,0HAA0H;QAC3H,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACnB,SAAS,EAAE,GAAG,EAAE,CAAC,sBAAsB;QACvC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,CAC3B,OAAO,CAAC,OAAO,CAAC;YACf,IAAI,EAAE,MAAM;YACZ,GAAG,EAAE,KAAK,EAAC,MAAM,EAAC,EAAE;gBACnB,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,UAAU,CAAC;gBACjC,IAAI,KAAK,KAAK,SAAS;oBAAE,OAAO,UAAU,CAAC;gBAC3C,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE;oBAC5C,QAAQ;oBACR,OAAO,EAAE,KAAK,EAAC,IAAI,EAAC,EAAE;wBACrB,IAAI,CAAC;4BACJ,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;4BACzC,OAAO,IAAI,CAAC;wBACb,CAAC;wBAAC,OAAO,KAAK,EAAE,CAAC;4BAChB,IAAI,KAAK,YAAY,iBAAiB;gCAAE,OAAO,KAAK,CAAC;4BACrD,MAAM,KAAK,CAAC;wBACb,CAAC;oBACF,CAAC;iBACD,CAAC,CAAC;gBACH,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;YACxC,CAAC;SACD,CAAC;KACH,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import { z } from 'zod';\nimport type { RecoveryStore } from '#src/recovery/domain/recoveryStore';\nimport { showChanges } from '#src/recovery/domain/runChanges';\nimport { AccessDeniedError, type AccessPolicy } from '../domain/accessPolicy.ts';\nimport type { PreparingTool } from '../domain/preparedCall.ts';\nimport { definePreparingTool } from './defineTool.ts';\n\n// A reviewer reads a change whole, but not a rewrite of the whole repository.\nconst maxLines = 600;\n\nconst nothingYet = 'Nothing has been changed in this task yet.';\n\n/**\n * `showChanges` for the planner and the reviewer: what the current task has changed so far, as a\n * diff per file, from the run's own record. It shows only what the role may read: a secret the\n * executor was allowed to write is counted, never shown.\n */\nexport function createShowChangesTool({\n\tstore,\n\tpolicy,\n}: {\n\tstore: RecoveryStore;\n\tpolicy: AccessPolicy;\n}): PreparingTool {\n\treturn definePreparingTool({\n\t\tname: 'showChanges',\n\t\tdescription:\n\t\t\t'Shows what this task has changed in the repository so far, as a diff per file, in the order each file was first changed.',\n\t\tinput: z.object({}),\n\t\tsummarize: () => 'changes in this task',\n\t\tprepare: (_, __, { run }) =>\n\t\t\tPromise.resolve({\n\t\t\t\trisk: 'safe',\n\t\t\t\trun: async signal => {\n\t\t\t\t\tconst { runId } = run.historyRun;\n\t\t\t\t\tif (runId === undefined) return nothingYet;\n\t\t\t\t\tconst diff = await showChanges(store, runId, {\n\t\t\t\t\t\tmaxLines,\n\t\t\t\t\t\tvisible: async path => {\n\t\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\t\tawait policy.check(path, 'read', signal);\n\t\t\t\t\t\t\t\treturn true;\n\t\t\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\t\t\tif (error instanceof AccessDeniedError) return false;\n\t\t\t\t\t\t\t\tthrow error;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t},\n\t\t\t\t\t});\n\t\t\t\t\treturn diff === '' ? nothingYet : diff;\n\t\t\t\t},\n\t\t\t}),\n\t});\n}\n"]}

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

@@ -0,0 +1,33 @@
+import type { PreparedCall } from '../domain/preparedCall.ts';
+import type { ToolCallContext } from '../domain/readRegistry.ts';
+import type { WorkspaceWrites } from './workspaceWrites.ts';
+/**
+ * One edit, as an edit format asks for it, with the path as the model wrote it. A modification
+ * works its new content out from what the file holds now, the version the model read; it throws
+ * `EditRefusedError` with what the model needs to fix the call, such as a text that matched
+ * twice.
+ */
+export type EditRequest = {
+    kind: 'create';
+    path: string;
+    content: Buffer;
+} | {
+    kind: 'modify';
+    path: string;
+    change: (current: Buffer) => Buffer;
+} | {
+    kind: 'delete';
+    path: string;
+};
+/**
+ * Prepares an edit from the version of the file this conversation read, and only from it:
+ *
+ * - a file it never read is `READ_REQUIRED`;
+ * - a file changed since it read it is `STALE_FILE`;
+ * - a new file needs a path that does not exist.
+ *
+ * Once applied, the conversation knows the file as the edit left it, so it can edit it again
+ * without reading it. What it returns to the model is short: the lines around a change, or a
+ * confirmation.
+ */
+export declare function prepareTrackedEdit(writes: WorkspaceWrites, request: EditRequest, signal: AbortSignal, { run, reads }: ToolCallContext): Promise<PreparedCall>;

package/dist/tools/infrastructure/trackedEdits.js

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto';
+import { describeCreation, describeDeletion, describeModification, editDiff, } from "../domain/editResponse.js";
+import { EditRefusedError } from "../domain/fileEdits.js";
+import { editRisk } from "./fileEditor.js";
+function hashOf(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Prepares an edit from the version of the file this conversation read, and only from it:
+ *
+ * - a file it never read is `READ_REQUIRED`;
+ * - a file changed since it read it is `STALE_FILE`;
+ * - a new file needs a path that does not exist.
+ *
+ * Once applied, the conversation knows the file as the edit left it, so it can edit it again
+ * without reading it. What it returns to the model is short: the lines around a change, or a
+ * confirmation.
+ */
+export async function prepareTrackedEdit(writes, request, signal, { run, reads }) {
+    const editor = writes.editorFor(run);
+    const { path } = request;
+    if (request.kind === 'create') {
+        const prepared = await editor.prepare({ kind: 'create', path, content: request.content }, signal);
+        return {
+            risk: editRisk(prepared),
+            diff: editDiff(path, undefined, request.content.toString('utf8')),
+            run: async (runSignal) => {
+                await editor.apply(prepared, runSignal);
+                // It wrote the content itself, so it has seen it.
+                reads.record(prepared.target.absolute, hashOf(request.content));
+                return describeCreation(path, request.content);
+            },
+        };
+    }
+    const { target, state, content } = await editor.current(path, signal);
+    if (!state.exists || content === undefined) {
+        throw new EditRefusedError(`"${path}" does not exist`);
+    }
+    const seen = reads.versionOf(target.absolute);
+    if (seen === undefined) {
+        throw new EditRefusedError(`READ_REQUIRED: read "${path}" before changing it`);
+    }
+    if (seen !== state.hash) {
+        throw new EditRefusedError(`STALE_FILE: "${path}" changed since you read it; read it again`);
+    }
+    if (request.kind === 'delete') {
+        const prepared = await editor.prepare({ kind: 'delete', path, expected: seen }, signal);
+        return {
+            risk: editRisk(prepared),
+            diff: editDiff(path, content.toString('utf8'), undefined),
+            run: async (runSignal) => {
+                await editor.apply(prepared, runSignal);
+                reads.forget(target.absolute);
+                return describeDeletion(path);
+            },
+        };
+    }
+    const next = request.change(content);
+    const prepared = await editor.prepare({ kind: 'replace', path, content: next, expected: seen }, signal);
+    return {
+        risk: editRisk(prepared),
+        diff: editDiff(path, content.toString('utf8'), next.toString('utf8')),
+        run: async (runSignal) => {
+            await editor.apply(prepared, runSignal);
+            reads.record(target.absolute, hashOf(next));
+            return describeModification(path, content.toString('utf8'), next.toString('utf8'));
+        },
+    };
+}
+//# sourceMappingURL=trackedEdits.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trackedEdits.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/trackedEdits.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACN,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,QAAQ,GACR,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAc3C,SAAS,MAAM,CAAC,OAAe;IAC9B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACvC,MAAuB,EACvB,OAAoB,EACpB,MAAmB,EACnB,EAAE,GAAG,EAAE,KAAK,EAAmB;IAE/B,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IAEzB,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CACpC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,EAClD,MAAM,CACN,CAAC;QACF,OAAO;YACN,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC;YACxB,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACjE,GAAG,EAAE,KAAK,EAAC,SAAS,EAAC,EAAE;gBACtB,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;gBACxC,kDAAkD;gBAClD,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;gBAChE,OAAO,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;YAChD,CAAC;SACD,CAAC;IACH,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtE,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC5C,MAAM,IAAI,gBAAgB,CAAC,IAAI,IAAI,kBAAkB,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC9C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,gBAAgB,CAAC,wBAAwB,IAAI,sBAAsB,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,IAAI,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;QACzB,MAAM,IAAI,gBAAgB,CAAC,gBAAgB,IAAI,4CAA4C,CAAC,CAAC;IAC9F,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;QACxF,OAAO;YACN,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC;YACxB,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;YACzD,GAAG,EAAE,KAAK,EAAC,SAAS,EAAC,EAAE;gBACtB,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;gBACxC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBAC9B,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;SACD,CAAC;IACH,CAAC;IAED,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CACpC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,EACxD,MAAM,CACN,CAAC;IACF,OAAO;QACN,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC;QACxB,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACrE,GAAG,EAAE,KAAK,EAAC,SAAS,EAAC,EAAE;YACtB,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YACxC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;YAC5C,OAAO,oBAAoB,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACpF,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["import { createHash } from 'node:crypto';\nimport {\n\tdescribeCreation,\n\tdescribeDeletion,\n\tdescribeModification,\n\teditDiff,\n} from '../domain/editResponse.ts';\nimport { EditRefusedError } from '../domain/fileEdits.ts';\nimport type { PreparedCall } from '../domain/preparedCall.ts';\nimport type { ToolCallContext } from '../domain/readRegistry.ts';\nimport { editRisk } from './fileEditor.ts';\nimport type { WorkspaceWrites } from './workspaceWrites.ts';\n\n/**\n * One edit, as an edit format asks for it, with the path as the model wrote it. A modification\n * works its new content out from what the file holds now, the version the model read; it throws\n * `EditRefusedError` with what the model needs to fix the call, such as a text that matched\n * twice.\n */\nexport type EditRequest =\n\t| { kind: 'create'; path: string; content: Buffer }\n\t| { kind: 'modify'; path: string; change: (current: Buffer) => Buffer }\n\t| { kind: 'delete'; path: string };\n\nfunction hashOf(content: Buffer): string {\n\treturn createHash('sha256').update(content).digest('hex');\n}\n\n/**\n * Prepares an edit from the version of the file this conversation read, and only from it:\n *\n * - a file it never read is `READ_REQUIRED`;\n * - a file changed since it read it is `STALE_FILE`;\n * - a new file needs a path that does not exist.\n *\n * Once applied, the conversation knows the file as the edit left it, so it can edit it again\n * without reading it. What it returns to the model is short: the lines around a change, or a\n * confirmation.\n */\nexport async function prepareTrackedEdit(\n\twrites: WorkspaceWrites,\n\trequest: EditRequest,\n\tsignal: AbortSignal,\n\t{ run, reads }: ToolCallContext,\n): Promise<PreparedCall> {\n\tconst editor = writes.editorFor(run);\n\tconst { path } = request;\n\n\tif (request.kind === 'create') {\n\t\tconst prepared = await editor.prepare(\n\t\t\t{ kind: 'create', path, content: request.content },\n\t\t\tsignal,\n\t\t);\n\t\treturn {\n\t\t\trisk: editRisk(prepared),\n\t\t\tdiff: editDiff(path, undefined, request.content.toString('utf8')),\n\t\t\trun: async runSignal => {\n\t\t\t\tawait editor.apply(prepared, runSignal);\n\t\t\t\t// It wrote the content itself, so it has seen it.\n\t\t\t\treads.record(prepared.target.absolute, hashOf(request.content));\n\t\t\t\treturn describeCreation(path, request.content);\n\t\t\t},\n\t\t};\n\t}\n\n\tconst { target, state, content } = await editor.current(path, signal);\n\tif (!state.exists || content === undefined) {\n\t\tthrow new EditRefusedError(`\"${path}\" does not exist`);\n\t}\n\tconst seen = reads.versionOf(target.absolute);\n\tif (seen === undefined) {\n\t\tthrow new EditRefusedError(`READ_REQUIRED: read \"${path}\" before changing it`);\n\t}\n\tif (seen !== state.hash) {\n\t\tthrow new EditRefusedError(`STALE_FILE: \"${path}\" changed since you read it; read it again`);\n\t}\n\n\tif (request.kind === 'delete') {\n\t\tconst prepared = await editor.prepare({ kind: 'delete', path, expected: seen }, signal);\n\t\treturn {\n\t\t\trisk: editRisk(prepared),\n\t\t\tdiff: editDiff(path, content.toString('utf8'), undefined),\n\t\t\trun: async runSignal => {\n\t\t\t\tawait editor.apply(prepared, runSignal);\n\t\t\t\treads.forget(target.absolute);\n\t\t\t\treturn describeDeletion(path);\n\t\t\t},\n\t\t};\n\t}\n\n\tconst next = request.change(content);\n\tconst prepared = await editor.prepare(\n\t\t{ kind: 'replace', path, content: next, expected: seen },\n\t\tsignal,\n\t);\n\treturn {\n\t\trisk: editRisk(prepared),\n\t\tdiff: editDiff(path, content.toString('utf8'), next.toString('utf8')),\n\t\trun: async runSignal => {\n\t\t\tawait editor.apply(prepared, runSignal);\n\t\t\treads.record(target.absolute, hashOf(next));\n\t\t\treturn describeModification(path, content.toString('utf8'), next.toString('utf8'));\n\t\t},\n\t};\n}\n"]}

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

@@ -0,0 +1,21 @@
+import type { AccessPolicy, AllowedPath } from '../domain/accessPolicy.ts';
+import type { PreparingTool } from '../domain/preparedCall.ts';
+import type { RunReads } from '../domain/readRegistry.ts';
+/**
+ * Reads lines `from` to `from + count - 1` of a file the policy allowed, and records the version
+ * of the whole file the model saw. The file is read once, so the version recorded is the content
+ * shown. A partial read counts: the model saw this version, and can read the rest.
+ */
+export declare function readTracked({ target, path, from, count, reads, signal, }: {
+    target: AllowedPath;
+    path: string;
+    from: number;
+    count: number;
+    reads: RunReads;
+    signal: AbortSignal;
+}): Promise<string>;
+/**
+ * `readFile` for an agent that edits: the same tool for the model, through the access policy,
+ * and it records the version of the file the model saw, so an edit starts only from it.
+ */
+export declare function createTrackedReadFile(policy: AccessPolicy): PreparingTool;

package/dist/tools/infrastructure/trackedReadFile.js

@@ -0,0 +1,79 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile } from 'node:fs/promises';
+import { isText } from '#src/recovery/domain/runChanges';
+import { definePreparingTool } from "./defineTool.js";
+import { readFileDescription, readFileInput, readFileSummary, readRange, renderLines, } from "./workspaceTools.js";
+// The same bound as an edit: a file too large to change need not be read whole to track it.
+const maxFileBytes = 5 * 1024 * 1024;
+/**
+ * The lines of a text, split as the diff an edit returns splits them, so their numbers agree: on
+ * `\n`, with a `\r` before it dropped. A final newline ends the last line; it starts no other.
+ */
+function lines(text) {
+    if (text === '')
+        return [];
+    const all = text.split('\n').map(line => (line.endsWith('\r') ? line.slice(0, -1) : line));
+    if (all.at(-1) === '')
+        all.pop();
+    return all;
+}
+function code(error) {
+    return error.code ?? 'an unknown error';
+}
+/**
+ * Reads lines `from` to `from + count - 1` of a file the policy allowed, and records the version
+ * of the whole file the model saw. The file is read once, so the version recorded is the content
+ * shown. A partial read counts: the model saw this version, and can read the rest.
+ */
+export async function readTracked({ target, path, from, count, reads, signal, }) {
+    signal.throwIfAborted();
+    const stats = await lstat(target.absolute).catch((error) => {
+        if (code(error) === 'ENOENT')
+            return undefined;
+        // Its own message would name the host path.
+        throw new Error(`Could not read ${path} (${code(error)})`);
+    });
+    // One answer for every file it cannot show, as the read tools give.
+    if (!stats?.isFile())
+        throw new Error(`No such file: ${path}`);
+    if (stats.size > maxFileBytes) {
+        throw new Error(`${path} is larger than ${String(maxFileBytes / 1024 / 1024)} MB, too large to read`);
+    }
+    const content = await readFile(target.absolute, { signal }).catch((error) => {
+        signal.throwIfAborted();
+        throw new Error(`Could not read ${path} (${code(error)})`);
+    });
+    if (!isText(content))
+        throw new Error(`Not a text file: ${path}`);
+    const all = lines(content.toString('utf8'));
+    const shown = all.slice(from - 1, from - 1 + count);
+    reads.record(target.absolute, createHash('sha256').update(content).digest('hex'));
+    return renderLines({
+        path,
+        lines: shown,
+        from,
+        totalLines: all.length,
+        truncated: from - 1 + shown.length < all.length,
+    });
+}
+/**
+ * `readFile` for an agent that edits: the same tool for the model, through the access policy,
+ * and it records the version of the file the model saw, so an edit starts only from it.
+ */
+export function createTrackedReadFile(policy) {
+    return definePreparingTool({
+        name: 'readFile',
+        description: readFileDescription,
+        input: readFileInput,
+        summarize: readFileSummary,
+        prepare: async ({ path, fromLine, lineCount }, signal, { reads }) => {
+            const { from, count } = readRange({ fromLine, lineCount });
+            const target = await policy.check(path, 'read', signal);
+            return {
+                risk: 'safe',
+                run: runSignal => readTracked({ target, path, from, count, reads, signal: runSignal }),
+            };
+        },
+    });
+}
+//# sourceMappingURL=trackedReadFile.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trackedReadFile.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/trackedReadFile.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from 'node:crypto';\nimport { lstat, readFile } from 'node:fs/promises';\nimport { isText } from '#src/recovery/domain/runChanges';\nimport type { AccessPolicy, AllowedPath } from '../domain/accessPolicy.ts';\nimport type { PreparingTool } from '../domain/preparedCall.ts';\nimport type { RunReads } from '../domain/readRegistry.ts';\nimport { definePreparingTool } from './defineTool.ts';\nimport {\n\treadFileDescription,\n\treadFileInput,\n\treadFileSummary,\n\treadRange,\n\trenderLines,\n} from './workspaceTools.ts';\n\n// The same bound as an edit: a file too large to change need not be read whole to track it.\nconst maxFileBytes = 5 * 1024 * 1024;\n\n/**\n * The lines of a text, split as the diff an edit returns splits them, so their numbers agree: on\n * `\\n`, with a `\\r` before it dropped. A final newline ends the last line; it starts no other.\n */\nfunction lines(text: string): string[] {\n\tif (text === '') return [];\n\tconst all = text.split('\\n').map(line => (line.endsWith('\\r') ? line.slice(0, -1) : line));\n\tif (all.at(-1) === '') all.pop();\n\treturn all;\n}\n\nfunction code(error: unknown): string {\n\treturn (error as NodeJS.ErrnoException).code ?? 'an unknown error';\n}\n\n/**\n * Reads lines `from` to `from + count - 1` of a file the policy allowed, and records the version\n * of the whole file the model saw. The file is read once, so the version recorded is the content\n * shown. A partial read counts: the model saw this version, and can read the rest.\n */\nexport async function readTracked({\n\ttarget,\n\tpath,\n\tfrom,\n\tcount,\n\treads,\n\tsignal,\n}: {\n\ttarget: AllowedPath;\n\tpath: string;\n\tfrom: number;\n\tcount: number;\n\treads: RunReads;\n\tsignal: AbortSignal;\n}): Promise<string> {\n\tsignal.throwIfAborted();\n\tconst stats = await lstat(target.absolute).catch((error: unknown) => {\n\t\tif (code(error) === 'ENOENT') return undefined;\n\t\t// Its own message would name the host path.\n\t\tthrow new Error(`Could not read ${path} (${code(error)})`);\n\t});\n\t// One answer for every file it cannot show, as the read tools give.\n\tif (!stats?.isFile()) throw new Error(`No such file: ${path}`);\n\tif (stats.size > maxFileBytes) {\n\t\tthrow new Error(\n\t\t\t`${path} is larger than ${String(maxFileBytes / 1024 / 1024)} MB, too large to read`,\n\t\t);\n\t}\n\tconst content = await readFile(target.absolute, { signal }).catch((error: unknown) => {\n\t\tsignal.throwIfAborted();\n\t\tthrow new Error(`Could not read ${path} (${code(error)})`);\n\t});\n\tif (!isText(content)) throw new Error(`Not a text file: ${path}`);\n\n\tconst all = lines(content.toString('utf8'));\n\tconst shown = all.slice(from - 1, from - 1 + count);\n\treads.record(target.absolute, createHash('sha256').update(content).digest('hex'));\n\treturn renderLines({\n\t\tpath,\n\t\tlines: shown,\n\t\tfrom,\n\t\ttotalLines: all.length,\n\t\ttruncated: from - 1 + shown.length < all.length,\n\t});\n}\n\n/**\n * `readFile` for an agent that edits: the same tool for the model, through the access policy,\n * and it records the version of the file the model saw, so an edit starts only from it.\n */\nexport function createTrackedReadFile(policy: AccessPolicy): PreparingTool {\n\treturn definePreparingTool({\n\t\tname: 'readFile',\n\t\tdescription: readFileDescription,\n\t\tinput: readFileInput,\n\t\tsummarize: readFileSummary,\n\t\tprepare: async ({ path, fromLine, lineCount }, signal, { reads }) => {\n\t\t\tconst { from, count } = readRange({ fromLine, lineCount });\n\t\t\tconst target = await policy.check(path, 'read', signal);\n\t\t\treturn {\n\t\t\t\trisk: 'safe',\n\t\t\t\trun: runSignal => readTracked({ target, path, from, count, reads, signal: runSignal }),\n\t\t\t};\n\t\t},\n\t});\n}\n"]}

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

@@ -1,4 +1,38 @@
+import { z } from 'zod';
 import type { Tool } from '../domain/tool.ts';
 import type { Workspace } from '../domain/workspace.ts';
+/**
+ * Lines of a file as the model reads them: each numbered, a line too long cut, and a notice for
+ * what was cut or lies beyond.
+ */
+export declare function renderLines({ path, lines, from, totalLines, truncated, }: {
+    /** The file, which decides how long a line may be. */
+    path: string;
+    lines: string[];
+    from: number;
+    totalLines: number;
+    truncated: boolean;
+}): string;
+/** What `readFile` takes, shared with the harness's own version of it. */
+export declare const readFileDescription = "Reads lines of a file, each prefixed with its number.";
+export declare const readFileInput: z.ZodObject<{
+    path: z.ZodString;
+    fromLine: z.ZodNullable<z.ZodNumber>;
+    lineCount: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+/** The range a `readFile` call asks for, checked: strict mode allows the schema no minimum. */
+export declare function readRange({ fromLine, lineCount, }: {
+    fromLine: number | null;
+    lineCount: number | null;
+}): {
+    from: number;
+    count: number;
+};
+/** A stable description of a read request, using only the range the model supplied. */
+export declare function readFileSummary({ path, fromLine, lineCount, }: {
+    path: string;
+    fromLine: number | null;
+    lineCount: number | null;
+}): string;
 /** The three read-only tools an agent explores a repository with. */
 export declare function createWorkspaceTools(workspace: Workspace): Tool[];

package/dist/tools/infrastructure/workspaceTools.js

@@ -1,19 +1,73 @@
 import { z } from 'zod';
 import { defineTool } from "./defineTool.js";
+import { cutLine, maxLineLength } from "../domain/lineLength.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".'),
+    glob: z
+        .string()
+        .nullable()
+        .describe('Only paths matching this glob, relative to the root. "*" stays inside one folder and "**" crosses folders: "**/*.ts" is every TypeScript file, "*.ts" only those at the top.'),
 };
-/** 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;
+/**
+ * Lines of a file as the model reads them: each numbered, a line too long cut, and a notice for
+ * what was cut or lies beyond.
+ */
+export function renderLines({ path, lines, from, totalLines, truncated, }) {
+    // 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(path, text)}`);
+    const max = maxLineLength(path);
+    const cut = lines.filter(text => text.length > max).length;
+    const notices = [
+        ...(cut > 0
+            ? [`[${String(cut)} lines were longer than ${String(max)} 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');
+}
+/** What `readFile` takes, shared with the harness's own version of it. */
+export const readFileDescription = 'Reads lines of a file, each prefixed with its number.';
+export const readFileInput = 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)}.`),
+});
+/** The range a `readFile` call asks for, checked: strict mode allows the schema no minimum. */
+export function readRange({ fromLine, lineCount, }) {
+    const from = fromLine ?? 1;
+    const requested = lineCount ?? maxLines;
+    assertPositiveInteger('fromLine', from);
+    assertPositiveInteger('lineCount', requested);
+    return { from, count: Math.min(requested, maxLines) };
+}
+/** A stable description of a read request, using only the range the model supplied. */
+export function readFileSummary({ path, fromLine, lineCount, }) {
+    const suppliedFrom = fromLine ?? 1;
+    const from = Number.isInteger(suppliedFrom) && suppliedFrom > 0 ? suppliedFrom : 1;
+    const suppliedCount = lineCount ?? maxLines;
+    const requested = Number.isInteger(suppliedCount) && suppliedCount > 0 ? suppliedCount : maxLines;
+    const count = Math.min(requested, maxLines);
+    return `${path}:${String(from)}-${String(from + count - 1)}`;
+}
+function scopeSummary(path, glob) {
+    const scopePath = path ?? '.';
+    return glob ? `${scopePath === '.' ? '' : `${scopePath}/`}${glob}` : scopePath;
 }
 function assertPositiveInteger(name, value) {
     if (!Number.isInteger(value) || value < 1) {
@@ -28,6 +82,7 @@ export function createWorkspaceTools(workspace) {
             description: 'Lists the files of the repository, sorted. Ignored files such as dependencies are left out.',
             risk: 'safe',
             input: z.object(scope),
+            summarize: ({ path, glob }) => scopeSummary(path, glob),
             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);
@@ -50,6 +105,7 @@ export function createWorkspaceTools(workspace) {
                 ignoreCase: z.boolean().nullable().describe('Match regardless of case. Defaults to false.'),
                 ...scope,
             }),
+            summarize: ({ path, glob, pattern }) => `"${pattern}" in ${scopeSummary(path, glob)}`,
             execute: async ({ path, glob, ignoreCase, pattern }, signal) => {
                 const { matches, total, truncated } = await workspace.searchText({
                     path: path ?? undefined,
@@ -61,7 +117,7 @@ export function createWorkspaceTools(workspace) {
                 if (matches.length === 0) {
                     return 'No matches.';
                 }
-                const results = matches.map(match => `${match.path}:${String(match.line)}: ${cutLine(match.text)}`);
+                const results = matches.map(match => `${match.path}:${String(match.line)}: ${cutLine(match.path, match.text)}`);
                 const notice = truncated
                     ? `\n[Showing ${String(results.length)} of ${String(total)} matches. Narrow the path or glob to see the rest.]`
                     : '';
@@ -70,42 +126,15 @@ export function createWorkspaceTools(workspace) {
         }),
         defineTool({
             name: 'readFile',
-            description: 'Reads lines of a file, each prefixed with its number.',
+            description: readFileDescription,
             risk: 'safe',
-            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)}.`),
-            }),
+            input: readFileInput,
+            summarize: readFileSummary,
             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');
+                // Checked before reading.
+                const { from, count } = readRange({ fromLine, lineCount });
+                const { lines, totalLines, truncated } = await workspace.readFile({ path, fromLine: from, lineCount: count }, signal);
+                return renderLines({ path, lines, from, totalLines, truncated });
             },
         }),
     ];