@mikode13/harness 4.0.1 → 5.0.0

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

@@ -0,0 +1,23 @@
+import type { RunContext } from '#src/agent/domain/runContext';
+import type { RecoveryStore } from '#src/recovery/domain/recoveryStore';
+import type { AccessPolicy } from '../domain/accessPolicy.ts';
+import { FileEditor } from './fileEditor.ts';
+import { WriteSession } from './writeSession.ts';
+/**
+ * The writing side of a workspace, shared by every write tool built over it: one policy and
+ * one recovery store, and one `WriteSession` per run, ended with that run. A session lives
+ * only as long as its run's context, so nothing here outlives a run.
+ */
+export declare class WorkspaceWrites {
+    private readonly policy;
+    private readonly store;
+    private readonly sessions;
+    constructor({ policy, store }: {
+        policy: AccessPolicy;
+        store: RecoveryStore;
+    });
+    /** An editor over this run's session, created on the run's first write tool call. */
+    editorFor(context: RunContext): FileEditor;
+    /** Everything this run writes, its commands' changes included, created on its first write. */
+    sessionFor(context: RunContext): WriteSession;
+}

package/dist/tools/infrastructure/workspaceWrites.js

@@ -0,0 +1,42 @@
+import { FileEditor } from "./fileEditor.js";
+import { WriteSession } from "./writeSession.js";
+/**
+ * The writing side of a workspace, shared by every write tool built over it: one policy and
+ * one recovery store, and one `WriteSession` per run, ended with that run. A session lives
+ * only as long as its run's context, so nothing here outlives a run.
+ */
+export class WorkspaceWrites {
+    policy;
+    store;
+    sessions = new WeakMap();
+    constructor({ policy, store }) {
+        this.policy = policy;
+        this.store = store;
+    }
+    /** An editor over this run's session, created on the run's first write tool call. */
+    editorFor(context) {
+        return new FileEditor({ policy: this.policy, session: this.sessionFor(context) });
+    }
+    /** Everything this run writes, its commands' changes included, created on its first write. */
+    sessionFor(context) {
+        let session = this.sessions.get(context);
+        if (!session) {
+            const created = new WriteSession({
+                store: this.store,
+                // So every turn of the run, in every role, can be tied to what it wrote.
+                onStart: runId => {
+                    context.historyRun.runId = runId;
+                },
+                // A run that changed nothing is not in the history, so its turns wrote nothing.
+                onDiscard: () => {
+                    delete context.historyRun.runId;
+                },
+            });
+            context.onFinish(end => created.finish(end));
+            this.sessions.set(context, created);
+            session = created;
+        }
+        return session;
+    }
+}
+//# sourceMappingURL=workspaceWrites.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceWrites.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/workspaceWrites.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,OAAO,eAAe;IACV,MAAM,CAAe;IACrB,KAAK,CAAgB;IACrB,QAAQ,GAAG,IAAI,OAAO,EAA4B,CAAC;IAEpE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAkD;QAC5E,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;IAED,qFAAqF;IACrF,SAAS,CAAC,OAAmB;QAC5B,OAAO,IAAI,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACnF,CAAC;IAED,8FAA8F;IAC9F,UAAU,CAAC,OAAmB;QAC7B,IAAI,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,CAAC,OAAO,EAAE,CAAC;YACd,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC;gBAChC,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,yEAAyE;gBACzE,OAAO,EAAE,KAAK,CAAC,EAAE;oBAChB,OAAO,CAAC,UAAU,CAAC,KAAK,GAAG,KAAK,CAAC;gBAClC,CAAC;gBACD,gFAAgF;gBAChF,SAAS,EAAE,GAAG,EAAE;oBACf,OAAO,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC;gBACjC,CAAC;aACD,CAAC,CAAC;YACH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAC7C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACpC,OAAO,GAAG,OAAO,CAAC;QACnB,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;CACD","sourcesContent":["import type { RunContext } from '#src/agent/domain/runContext';\nimport type { RecoveryStore } from '#src/recovery/domain/recoveryStore';\nimport type { AccessPolicy } from '../domain/accessPolicy.ts';\nimport { FileEditor } from './fileEditor.ts';\nimport { WriteSession } from './writeSession.ts';\n\n/**\n * The writing side of a workspace, shared by every write tool built over it: one policy and\n * one recovery store, and one `WriteSession` per run, ended with that run. A session lives\n * only as long as its run's context, so nothing here outlives a run.\n */\nexport class WorkspaceWrites {\n\tprivate readonly policy: AccessPolicy;\n\tprivate readonly store: RecoveryStore;\n\tprivate readonly sessions = new WeakMap<RunContext, WriteSession>();\n\n\tconstructor({ policy, store }: { policy: AccessPolicy; store: RecoveryStore }) {\n\t\tthis.policy = policy;\n\t\tthis.store = store;\n\t}\n\n\t/** An editor over this run's session, created on the run's first write tool call. */\n\teditorFor(context: RunContext): FileEditor {\n\t\treturn new FileEditor({ policy: this.policy, session: this.sessionFor(context) });\n\t}\n\n\t/** Everything this run writes, its commands' changes included, created on its first write. */\n\tsessionFor(context: RunContext): WriteSession {\n\t\tlet session = this.sessions.get(context);\n\t\tif (!session) {\n\t\t\tconst created = new WriteSession({\n\t\t\t\tstore: this.store,\n\t\t\t\t// So every turn of the run, in every role, can be tied to what it wrote.\n\t\t\t\tonStart: runId => {\n\t\t\t\t\tcontext.historyRun.runId = runId;\n\t\t\t\t},\n\t\t\t\t// A run that changed nothing is not in the history, so its turns wrote nothing.\n\t\t\t\tonDiscard: () => {\n\t\t\t\t\tdelete context.historyRun.runId;\n\t\t\t\t},\n\t\t\t});\n\t\t\tcontext.onFinish(end => created.finish(end));\n\t\t\tthis.sessions.set(context, created);\n\t\t\tsession = created;\n\t\t}\n\t\treturn session;\n\t}\n}\n"]}

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

@@ -0,0 +1,35 @@
+import { type RecoveryStore, type RunJournal, type RunStatus } from '#src/recovery/domain/recoveryStore';
+/**
+ * Everything one top-level run writes, across all its roles and rounds. Its journal starts on
+ * the first write, so a run that only reads never holds the workspace, and ends with the run.
+ * Once a change could not be confirmed, the session refuses every further write: the record of
+ * what the run did must stay complete.
+ */
+export declare class WriteSession {
+    private readonly store;
+    private readonly maxChanges;
+    private readonly onStart;
+    private readonly onDiscard;
+    private journal;
+    private changes;
+    private stopped;
+    constructor({ store, maxChanges, onStart, onDiscard, }: {
+        store: RecoveryStore;
+        maxChanges?: number;
+        /** Told the run's id once its journal has started, before its first change is recorded. */
+        onStart?: (runId: string) => void;
+        /** Told when the run ended having changed nothing, so the history no longer has it. */
+        onDiscard?: () => void;
+    });
+    /** The journal for one more change, counted against the run's limit. */
+    journalForChange(): Promise<RunJournal>;
+    /** Refuses every further write, for this reason. The first reason given is kept. */
+    stop(reason: string): void;
+    /** The run's id once it has written, which is what an undo needs. */
+    runId(): Promise<string | undefined>;
+    /**
+     * Ends the run's record and releases the workspace. A run that never wrote has nothing to end,
+     * and one whose every change was abandoned leaves the history.
+     */
+    finish(status: Exclude<RunStatus, 'running' | 'interrupted'>): Promise<void>;
+}

package/dist/tools/infrastructure/writeSession.js

@@ -0,0 +1,81 @@
+import { WorkspaceBusyError, } from '#src/recovery/domain/recoveryStore';
+import { EditRefusedError } from "../domain/fileEdits.js";
+// Far more than a task needs; a run past it is more likely looping than working.
+const defaultMaxChanges = 500;
+/**
+ * Everything one top-level run writes, across all its roles and rounds. Its journal starts on
+ * the first write, so a run that only reads never holds the workspace, and ends with the run.
+ * Once a change could not be confirmed, the session refuses every further write: the record of
+ * what the run did must stay complete.
+ */
+export class WriteSession {
+    store;
+    maxChanges;
+    onStart;
+    onDiscard;
+    journal;
+    changes = 0;
+    stopped;
+    constructor({ store, maxChanges = defaultMaxChanges, onStart, onDiscard, }) {
+        this.store = store;
+        this.maxChanges = maxChanges;
+        this.onStart = onStart;
+        this.onDiscard = onDiscard;
+    }
+    /** The journal for one more change, counted against the run's limit. */
+    async journalForChange() {
+        if (this.stopped !== undefined)
+            throw new EditRefusedError(this.stopped);
+        if (this.changes >= this.maxChanges) {
+            throw new EditRefusedError(`This run has made ${String(this.maxChanges)} changes, the most one run may make`);
+        }
+        this.journal ??= this.store.startRun().then(started => {
+            this.onStart?.(started.runId);
+            return started;
+        });
+        let journal;
+        try {
+            journal = await this.journal;
+        }
+        catch (error) {
+            // A failed start is not kept, so the next change tries again.
+            this.journal = undefined;
+            if (error instanceof WorkspaceBusyError) {
+                throw new EditRefusedError('Another run, or a move through its history, holds this workspace, so nothing was changed', {
+                    cause: error,
+                });
+            }
+            throw new EditRefusedError('The harness could not start recording this run, so nothing was changed', { cause: error });
+        }
+        this.changes++;
+        return journal;
+    }
+    /** Refuses every further write, for this reason. The first reason given is kept. */
+    stop(reason) {
+        this.stopped ??= reason;
+    }
+    /** The run's id once it has written, which is what an undo needs. */
+    async runId() {
+        const journal = await this.journal?.catch(() => undefined);
+        return journal?.runId;
+    }
+    /**
+     * Ends the run's record and releases the workspace. A run that never wrote has nothing to end,
+     * and one whose every change was abandoned leaves the history.
+     */
+    async finish(status) {
+        const journal = await this.journal?.catch(() => undefined);
+        this.journal = undefined;
+        if (!journal)
+            return;
+        try {
+            await journal.finish(status);
+        }
+        finally {
+            // Even when finishing failed: a run that changed nothing is out of the history either way.
+            if (!journal.changed)
+                this.onDiscard?.();
+        }
+    }
+}
+//# sourceMappingURL=writeSession.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"writeSession.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/writeSession.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype RecoveryStore,\n\ttype RunJournal,\n\ttype RunStatus,\n\tWorkspaceBusyError,\n} from '#src/recovery/domain/recoveryStore';\nimport { EditRefusedError } from '../domain/fileEdits.ts';\n\n// Far more than a task needs; a run past it is more likely looping than working.\nconst defaultMaxChanges = 500;\n\n/**\n * Everything one top-level run writes, across all its roles and rounds. Its journal starts on\n * the first write, so a run that only reads never holds the workspace, and ends with the run.\n * Once a change could not be confirmed, the session refuses every further write: the record of\n * what the run did must stay complete.\n */\nexport class WriteSession {\n\tprivate readonly store: RecoveryStore;\n\tprivate readonly maxChanges: number;\n\tprivate readonly onStart: ((runId: string) => void) | undefined;\n\tprivate readonly onDiscard: (() => void) | undefined;\n\tprivate journal: Promise<RunJournal> | undefined;\n\tprivate changes = 0;\n\tprivate stopped: string | undefined;\n\n\tconstructor({\n\t\tstore,\n\t\tmaxChanges = defaultMaxChanges,\n\t\tonStart,\n\t\tonDiscard,\n\t}: {\n\t\tstore: RecoveryStore;\n\t\tmaxChanges?: number;\n\t\t/** Told the run's id once its journal has started, before its first change is recorded. */\n\t\tonStart?: (runId: string) => void;\n\t\t/** Told when the run ended having changed nothing, so the history no longer has it. */\n\t\tonDiscard?: () => void;\n\t}) {\n\t\tthis.store = store;\n\t\tthis.maxChanges = maxChanges;\n\t\tthis.onStart = onStart;\n\t\tthis.onDiscard = onDiscard;\n\t}\n\n\t/** The journal for one more change, counted against the run's limit. */\n\tasync journalForChange(): Promise<RunJournal> {\n\t\tif (this.stopped !== undefined) throw new EditRefusedError(this.stopped);\n\t\tif (this.changes >= this.maxChanges) {\n\t\t\tthrow new EditRefusedError(\n\t\t\t\t`This run has made ${String(this.maxChanges)} changes, the most one run may make`,\n\t\t\t);\n\t\t}\n\n\t\tthis.journal ??= this.store.startRun().then(started => {\n\t\t\tthis.onStart?.(started.runId);\n\t\t\treturn started;\n\t\t});\n\t\tlet journal: RunJournal;\n\t\ttry {\n\t\t\tjournal = await this.journal;\n\t\t} catch (error) {\n\t\t\t// A failed start is not kept, so the next change tries again.\n\t\t\tthis.journal = undefined;\n\t\t\tif (error instanceof WorkspaceBusyError) {\n\t\t\t\tthrow new EditRefusedError(\n\t\t\t\t\t'Another run, or a move through its history, holds this workspace, so nothing was changed',\n\t\t\t\t\t{\n\t\t\t\t\t\tcause: error,\n\t\t\t\t\t},\n\t\t\t\t);\n\t\t\t}\n\t\t\tthrow new EditRefusedError(\n\t\t\t\t'The harness could not start recording this run, so nothing was changed',\n\t\t\t\t{ cause: error },\n\t\t\t);\n\t\t}\n\t\tthis.changes++;\n\t\treturn journal;\n\t}\n\n\t/** Refuses every further write, for this reason. The first reason given is kept. */\n\tstop(reason: string): void {\n\t\tthis.stopped ??= reason;\n\t}\n\n\t/** The run's id once it has written, which is what an undo needs. */\n\tasync runId(): Promise<string | undefined> {\n\t\tconst journal = await this.journal?.catch(() => undefined);\n\t\treturn journal?.runId;\n\t}\n\n\t/**\n\t * Ends the run's record and releases the workspace. A run that never wrote has nothing to end,\n\t * and one whose every change was abandoned leaves the history.\n\t */\n\tasync finish(status: Exclude<RunStatus, 'running' | 'interrupted'>): Promise<void> {\n\t\tconst journal = await this.journal?.catch(() => undefined);\n\t\tthis.journal = undefined;\n\t\tif (!journal) return;\n\t\ttry {\n\t\t\tawait journal.finish(status);\n\t\t} finally {\n\t\t\t// Even when finishing failed: a run that changed nothing is out of the history either way.\n\t\t\tif (!journal.changed) this.onDiscard?.();\n\t\t}\n\t}\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mikode13/harness",
-	"version": "4.0.1",
+	"version": "5.0.0",
 	"description": "Test/agent harness utility",
 	"type": "module",
 	"license": "SEE LICENSE IN LICENSE",