@inflexa-ai/harness 0.46.0 → 0.47.0

package/dist/tools/script/run-script.js

@@ -0,0 +1,326 @@
+/**
+ * `run_script` — the agent writes one JavaScript script that calls its script tools as functions.
+ *
+ * The script runs in QuickJS (`@earendil-works/pi-codemode`), a WASM VM in a worker thread. The VM has no files, no
+ * network, and no timers. Its only capability is a call of a script tool, and each call runs the `execute` of that
+ * tool with the context of the `run_script` call. Only what the script prints or returns reaches the model, thus a
+ * script can join and filter large lookup results and tables before the model reads them.
+ *
+ * The whole script is one durable step: a replay returns the cached result and runs no lookup again. A step that
+ * did not complete runs the whole script again, thus a script tool that writes must accept the same write again.
+ *
+ * Each nested call streams its start and its end under the `run_script` call, thus a surface shows what the script
+ * does while it runs. With a scratch directory, the script is saved before it runs, each derived file is shown to
+ * the user in one file card with the script, and the files that the script read and wrote reach provenance.
+ */
+import { CodemodeSandbox, loadQuickJSWasm, renderToolSample, renderToolSignature, schemaToType, } from "@earendil-works/pi-codemode";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { createSubAgentActivityTracker } from "../../contracts/subagent-activity.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { parseJsonAs } from "../../lib/parse-json.js";
+import { parseUnknownRecord, UnknownArraySchema } from "../../lib/unknown-containers.js";
+import { computeDetail, computeResultDetail } from "../../loop/tool-detail.js";
+import { buildFileReferenceCardData, MAX_FILES } from "../../memory/card-builders.js";
+import { defineTool, readToolCallRecord, readToolResultImages, withToolCallRecord, } from "../define-tool.js";
+import { ScriptFileEffectSchema } from "./file-tools.js";
+import { recordScriptRun } from "./metrics.js";
+export const RUN_SCRIPT_TOOL_ID = "run_script";
+/** The deadline of one script, for each lookup in it together. */
+const SCRIPT_TIMEOUT_MS = 180_000;
+/** The heap of the VM. A script holds lookup results and tables of up to the read cap, not datasets. */
+const SCRIPT_MEMORY_BYTES = 256 * 1024 * 1024;
+/** The text of a result that reaches the model. A longer output keeps its head and its tail. */
+const MAX_RESULT_CHARS = 24_000;
+const inputSchema = z.object({
+    description: z.string().max(200).optional().describe("One short line that tells the user what the script does, for example 'Top 20 genes by padj'."),
+    code: z
+        .string()
+        .min(1)
+        .describe("The body of an async JavaScript function. Call a tool as `await tools.<name>({...})`, print with `text(value)` or `console.log`, and `return` a value."),
+});
+/** The first sentence of a description, for the catalog line of a tool. */
+function firstSentence(description) {
+    const line = description.split("\n")[0] ?? "";
+    const stop = line.indexOf(". ");
+    return stop === -1 ? line : line.slice(0, stop + 1);
+}
+function bounded(text) {
+    if (text.length <= MAX_RESULT_CHARS)
+        return text;
+    const half = MAX_RESULT_CHARS / 2;
+    return `${text.slice(0, half)}\n[... ${text.length - MAX_RESULT_CHARS} characters cut ...]\n${text.slice(-half)}`;
+}
+/** The JSON form of a tool result: the plain data, without the symbol keys of the loop. */
+function plainJson(value) {
+    return value === undefined ? null : parseJsonAs(JSON.stringify(value), z.json());
+}
+function describeTool(tool) {
+    return renderToolSample({ name: tool.id, description: tool.description, inputSchema: tool.jsonSchema, outputSchema: tool.outputJsonSchema });
+}
+function issuesOf(error) {
+    return error.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ");
+}
+/** Keep the files of the call record of one nested call. A record of another shape carries no file. */
+function collectEffect(state, value) {
+    const effect = ScriptFileEffectSchema.safeParse(readToolCallRecord(value));
+    if (!effect.success)
+        return;
+    state.reads.push(...(effect.data.reads ?? []));
+    state.writes.push(...(effect.data.writes ?? []));
+}
+/**
+ * A script tool as the VM calls it. Each call gets its own invocation id, `<id of run_script>:<n>` in call order: a
+ * tool keys what it stores by its invocation id (`web_fetch` keeps the cut text of a page under it), thus two calls of
+ * one script must not share it. The script is one step, thus a replay calls nothing and the ids stay as recorded.
+ *
+ * The script gets the JSON of a result, and the JSON has no pictures. Thus a result with pictures is a failed call: the
+ * script would otherwise read the result as complete.
+ */
+function scriptToolOf(tool, ctx, state, log, inCallContext) {
+    return {
+        name: tool.id,
+        description: tool.description,
+        inputSchema: tool.jsonSchema,
+        outputSchema: tool.outputJsonSchema,
+        execute: (args, options) => inCallContext(() => runNestedCall(tool, ctx, state, log, args, options.signal)),
+    };
+}
+async function runNestedCall(tool, ctx, state, log, args, signal) {
+    const invocationId = state.nextInvocationId();
+    const detail = computeDetail(tool, args, log);
+    const started = performance.now();
+    const startFrame = { type: "tool-started", source: state.source, toolUseId: invocationId, name: tool.id, input: args, detail };
+    state.observe(startFrame);
+    await ctx.emit(startFrame);
+    const finish = async (outcome, finishedDetail) => {
+        state.calls.push({ tool: tool.id, ok: outcome === "ok" });
+        const endFrame = {
+            type: "tool-finished",
+            source: state.source,
+            toolUseId: invocationId,
+            name: tool.id,
+            outcome,
+            durationMs: Math.round(performance.now() - started),
+            detail: finishedDetail,
+        };
+        state.observe(endFrame);
+        await ctx.emit(endFrame);
+    };
+    const parsed = tool.inputSchema.safeParse(args);
+    if (!parsed.success) {
+        await finish("error", detail);
+        throw new Error(`${tool.id}: ${issuesOf(parsed.error)}`);
+    }
+    const result = await tool.execute(parsed.data, {
+        ...ctx,
+        invocationId,
+        signal: AbortSignal.any([ctx.signal, signal]),
+        script: { code: state.code },
+    });
+    if (result.isErr()) {
+        await finish("error", detail);
+        throw new Error(`${tool.id}: ${result.error.error}`);
+    }
+    if (readToolResultImages(result.value).length > 0) {
+        await finish("error", detail);
+        throw new Error(`${tool.id}: the result holds pictures, and a script cannot carry pictures. Call ${tool.id} directly, not from a script.`);
+    }
+    collectEffect(state, result.value);
+    if (tool.foldCallRecord !== undefined) {
+        const record = readToolCallRecord(result.value);
+        if (record !== undefined)
+            state.nested.push({ tool: tool.id, record });
+    }
+    await finish("ok", computeResultDetail(tool, parsed.data, result.value, log) ?? detail);
+    return plainJson(result.value);
+}
+/** A JSON schema without its prose: the types and the constraints stay, the descriptions and the examples go. */
+function withoutProse(schema) {
+    const array = UnknownArraySchema.safeParse(schema);
+    if (array.success)
+        return array.data.map(withoutProse);
+    const record = parseUnknownRecord(schema);
+    if (record === undefined)
+        return schema;
+    return Object.fromEntries(Object.entries(record)
+        .filter(([key]) => key !== "description" && key !== "examples")
+        .map(([key, value]) => [key, withoutProse(value)]));
+}
+/** The longest result type that the catalog shows. A longer type shows as `unknown`, and `describe()` gives it whole. */
+const MAX_CATALOG_RESULT_TYPE_CHARS = 800;
+/** One catalog entry: the first sentence of the description, then the signature with no prose. */
+function catalogEntry(tool) {
+    const output = tool.outputJsonSchema === undefined ? undefined : parseUnknownRecord(withoutProse(tool.outputJsonSchema));
+    const resultType = output === undefined ? "unknown" : schemaToType(output, { maxChars: MAX_CATALOG_RESULT_TYPE_CHARS });
+    // pi renders a signature with no result schema as `...: Promise<unknown>;`, thus the catalog puts its capped type there.
+    const untyped = renderToolSignature({ name: tool.id, inputSchema: parseUnknownRecord(withoutProse(tool.jsonSchema)) ?? {} });
+    const signature = `${untyped.slice(0, -"unknown>;".length)}${resultType}>;`;
+    return `/** ${firstSentence(tool.description)} */\n${signature}`;
+}
+/** The description of the tool: the script API, then one catalog entry for each script tool. */
+function descriptionOf(tools) {
+    const catalog = tools.map(catalogEntry).join("\n");
+    return ("Run a JavaScript script that calls the tools below as functions, in a JavaScript VM on the host with no files and no network. " +
+        "Use it for lookups and for light work on tables: call several tools in parallel with Promise.all, filter, join, and count their results, and print only what you need. " +
+        "Only the printed output and the returned value come back to you.\n" +
+        "API: `await tools.<name>(args)` returns the JSON result of the tool and throws an Error on a failed call. " +
+        '`await describe("<name>")` returns the full description of a tool, with the meaning of each argument. ' +
+        "`text(value)` and `console.log` print. `return` gives a value. There are no timers, no fetch, and no modules.\n" +
+        `Tools (the result is the JSON that the tool returns):\n${catalog}`);
+}
+function sandboxRuntimeOf(runtime) {
+    const options = {};
+    if (runtime.wasmPath !== undefined)
+        options.wasm = loadQuickJSWasm(runtime.wasmPath);
+    if (runtime.workerUrl !== undefined)
+        options.workerUrl = runtime.workerUrl;
+    return options;
+}
+/** The failure of a script, for the metrics. The VM reports an exhausted heap as an error of the script. */
+function failureOf(error) {
+    if (error.kind === "script")
+        return error.message.includes("out of memory") ? "memory" : "script";
+    return error.kind;
+}
+/** The card of the files that a script derived, with the script beside them. A card holds at most ten files. */
+function filesCard(description, writes, script) {
+    const files = [...new Map(writes.map((write) => [write.path, { path: write.path }])).values()];
+    const room = script === undefined ? MAX_FILES : MAX_FILES - 1;
+    const shown = files.slice(0, room);
+    if (script !== undefined)
+        shown.push({ path: script.path, caption: "The script that derived these files." });
+    return buildFileReferenceCardData({ title: description ?? "Derived files", files: shown });
+}
+/** The `run_script` tool over the script tools of an agent. */
+export function createRunScriptTool(scriptTools, runtime = {}, options = {}) {
+    const vm = sandboxRuntimeOf(runtime);
+    const byId = new Map(scriptTools.map((tool) => [tool.id, tool]));
+    const log = (options.logger ?? createNoopLogger()).named("run-script");
+    const { scratch } = options;
+    return defineTool({
+        id: RUN_SCRIPT_TOOL_ID,
+        description: descriptionOf(scriptTools),
+        inputSchema,
+        describeCall: ({ description }) => description,
+        describeResult: ({ description }, result) => {
+            const tools = result.calls.length === 0 ? undefined : result.calls.map((call) => call.tool).join(", ");
+            return description === undefined ? tools : tools === undefined ? description : `${description} (${tools})`;
+        },
+        foldCallRecord: (record) => {
+            if (record.run !== undefined)
+                scratch?.recordRun(record.run);
+            for (const entry of record.nested) {
+                try {
+                    byId.get(entry.tool)?.foldCallRecord?.(entry.record);
+                }
+                catch (err) {
+                    log.error("the call record of a nested call did not fold", { tool: entry.tool, ...log.errorFields(err) });
+                }
+            }
+        },
+        execute: async ({ description, code }, ctx) => {
+            const startedAt = performance.now();
+            const script = await scratch?.saveScript({ session: ctx.session, invocationId: ctx.invocationId, code });
+            const caller = ctx.session.provenance;
+            const tracker = createSubAgentActivityTracker();
+            // The tracker reads the call of the script first, thus each nested call belongs to it. Only a call of the
+            // root agent has an activity part: the tracker keeps no root for a deeper caller.
+            tracker.track({
+                type: "tool-started",
+                toolUseId: ctx.invocationId,
+                name: RUN_SCRIPT_TOOL_ID,
+                source: { agentId: caller.agentId, callPath: [...caller.callPath] },
+            }, Date.now());
+            const tracked = { part: null };
+            let started = 0;
+            const state = {
+                code,
+                calls: [],
+                reads: [],
+                writes: [],
+                nested: [],
+                nextInvocationId: () => `${ctx.invocationId}:${++started}`,
+                source: { agentId: RUN_SCRIPT_TOOL_ID, callPath: [...caller.callPath, RUN_SCRIPT_TOOL_ID], invocationId: ctx.invocationId },
+                observe: (frame) => {
+                    tracked.part = tracker.track(frame, Date.now()) ?? tracked.part;
+                },
+            };
+            // The VM calls a tool from a message event of its worker, and such an event runs outside the async context
+            // of this call. A nested call runs in the snapshot of this context, thus it sees what the call sees, for
+            // example the durable step of the call, which DBOS keeps in an AsyncLocalStorage.
+            const inCallContext = AsyncLocalStorage.snapshot();
+            const sandbox = new CodemodeSandbox({
+                tools: scriptTools.map((tool) => scriptToolOf(tool, ctx, state, log, inCallContext)),
+                globals: [
+                    {
+                        name: "describe",
+                        execute: (name) => {
+                            const tool = typeof name === "string" ? byId.get(name) : undefined;
+                            if (tool === undefined)
+                                throw new Error(`no script tool ${JSON.stringify(name)}; the tools are ${[...byId.keys()].join(", ")}`);
+                            return describeTool(tool);
+                        },
+                    },
+                ],
+                timeoutMs: SCRIPT_TIMEOUT_MS,
+                memoryLimitBytes: SCRIPT_MEMORY_BYTES,
+                ...vm,
+            });
+            try {
+                const result = await sandbox.execute(code, { signal: ctx.signal });
+                // A cancel of the call is no result of the script: the loop must see the abort and end the run.
+                ctx.signal.throwIfAborted();
+                const output = bounded(result.output
+                    .filter((item) => item.type === "text")
+                    .map((item) => item.text)
+                    .join("\n"));
+                const failure = result.ok ? "none" : failureOf(result.error);
+                recordScriptRun(caller.agentId, failure);
+                log.info("a script ran", {
+                    invocationId: ctx.invocationId,
+                    failure,
+                    durationMs: Math.round(performance.now() - startedAt),
+                    calls: state.calls.length,
+                    reads: state.reads.length,
+                    writes: state.writes.length,
+                });
+                if (tracked.part !== null)
+                    await ctx.emit({ type: tracked.part.type, data: tracked.part });
+                if (state.writes.length > 0) {
+                    const card = filesCard(description, state.writes, script);
+                    if (card !== null)
+                        await ctx.emit({ type: "data-file-reference", source: caller, data: card });
+                }
+                const run = {
+                    analysisId: ctx.session.scope.analysisId,
+                    threadId: ctx.session.scope.threadId,
+                    invocationId: ctx.invocationId,
+                    script,
+                    reads: state.reads,
+                    writes: state.writes,
+                    tools: state.calls.map((call) => call.tool),
+                    ok: result.ok,
+                };
+                const files = state.writes.length === 0 ? undefined : state.writes.map((write) => write.path);
+                const outcome = result.ok
+                    ? {
+                        ok: true,
+                        output,
+                        value: result.value === undefined ? undefined : plainJson(result.value),
+                        calls: state.calls,
+                        script: script?.path,
+                        files,
+                    }
+                    : { ok: false, output, error: `${result.error.kind}: ${result.error.message}`, calls: state.calls, script: script?.path, files };
+                // Only a scratch directory folds the run into provenance, thus a script with none records no run.
+                const record = { run: scratch === undefined ? undefined : run, nested: state.nested };
+                return ok(record.run === undefined && record.nested.length === 0 ? outcome : withToolCallRecord(outcome, record));
+            }
+            finally {
+                await sandbox.close();
+            }
+        },
+    });
+}

package/dist/tools/script/scratch.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The scratch directory of a session: the scripts that `run_script` ran, and the files that those scripts derived.
+ *
+ * A conversation keeps them at `conversation-sessions/{threadId}/`. `scripts/` holds each script under the id of
+ * its call, saved before the script runs, thus a failed script is on record too. `derived/` holds each file that a
+ * script wrote, and it is the one place where a script can write: an input and a run output stay out of its reach.
+ *
+ * A derived name holds one file for the life of the session, because a reply can cite the file as its evidence.
+ * A second write of the name with other bytes is refused. The same bytes again pass with no write, thus a step that
+ * runs its script again after a crash lands nothing new.
+ */
+import type { AgentSession } from "../../auth/types.js";
+import type { Logger } from "../../lib/logger.js";
+import { type ProvenanceSeam } from "../../provenance/seam.js";
+import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
+/** The cap of one derived file. It matches the cap of a table read, thus a script can read back what it wrote. */
+export declare const DERIVED_FILE_CAP_BYTES: number;
+/** The cap of the derived files of one session together. */
+export declare const DERIVED_SESSION_CAP_BYTES: number;
+/** One file of the scratch directory: the analysis-relative path, and the hash and the size of its bytes. */
+export type ScratchFile = {
+    readonly path: string;
+    readonly hash: string;
+    readonly size: number;
+};
+/** A file that a script read: the analysis-relative path and the hash of the bytes that it read. */
+export type ScriptRead = {
+    readonly path: string;
+    readonly hash: string;
+};
+export type DerivedWrite = {
+    readonly status: "written";
+    readonly file: ScratchFile;
+} | {
+    readonly status: "refused";
+    readonly reason: string;
+};
+/**
+ * What one script did to files, for provenance. The harness writes the script before it runs, and each script tool
+ * that reads or writes a file gives its part as the call record of the nested call.
+ */
+export type ScriptRunRecord = {
+    readonly analysisId: string;
+    readonly threadId?: string;
+    /** The id of the `run_script` call. */
+    readonly invocationId: string;
+    /** The saved script. Absent when the session has no thread, thus no scratch directory. */
+    readonly script?: ScratchFile;
+    readonly reads: readonly ScriptRead[];
+    readonly writes: readonly ScratchFile[];
+    /** Each tool that the script called, in the order of the calls. */
+    readonly tools: readonly string[];
+    readonly ok: boolean;
+};
+export type ScriptScratch = {
+    /** Save the code of one script before it runs. Gives `undefined` when the scope of the session names no thread. */
+    saveScript(args: {
+        readonly session: AgentSession;
+        readonly invocationId: string;
+        readonly code: string;
+    }): Promise<ScratchFile | undefined>;
+    /** Write one derived file. A refusal is data that the script reads as a failed call. */
+    writeDerived(args: {
+        readonly session: AgentSession;
+        readonly invocationId: string;
+        readonly name: string;
+        /** Text lands as UTF-8. */
+        readonly content: string | Uint8Array;
+    }): Promise<DerivedWrite>;
+    /** Record what one script did to files. A script that read and wrote nothing records nothing. */
+    recordRun(record: ScriptRunRecord): void;
+};
+export type ScriptScratchDeps = {
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    /** The scratch directory of one thread, workspace-root-relative, for example `conversationSessionDir`. */
+    readonly sessionDir: (threadId: string) => string;
+    /** The provenance seam. An unbound session emit records nothing, and the scripts run the same. */
+    readonly provenance?: ProvenanceSeam;
+    readonly logger?: Logger;
+};
+export declare function createScriptScratch(deps: ScriptScratchDeps): ScriptScratch;

package/dist/tools/script/scratch.js

@@ -0,0 +1,142 @@
+/**
+ * The scratch directory of a session: the scripts that `run_script` ran, and the files that those scripts derived.
+ *
+ * A conversation keeps them at `conversation-sessions/{threadId}/`. `scripts/` holds each script under the id of
+ * its call, saved before the script runs, thus a failed script is on record too. `derived/` holds each file that a
+ * script wrote, and it is the one place where a script can write: an input and a run output stay out of its reach.
+ *
+ * A derived name holds one file for the life of the session, because a reply can cite the file as its evidence.
+ * A second write of the name with other bytes is refused. The same bytes again pass with no write, thus a step that
+ * runs its script again after a crash lands nothing new.
+ */
+import { lstat, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { computeSha256, computeSha256File } from "../../lib/fs-helpers.js";
+import { tryFs } from "../../lib/fs-result.js";
+import { unwrapOrThrow } from "../../lib/result.js";
+import { bindSessionEmit } from "../../provenance/seam.js";
+import { isSafeId } from "../../workspace/paths.js";
+import { confinedWrite } from "../workspace/mutator.js";
+/** The cap of one derived file. It matches the cap of a table read, thus a script can read back what it wrote. */
+export const DERIVED_FILE_CAP_BYTES = 16 * 1024 * 1024;
+/** The cap of the derived files of one session together. */
+export const DERIVED_SESSION_CAP_BYTES = 256 * 1024 * 1024;
+/** The file name of a script. A call id that is not a safe file name is hashed, thus each id gives one name. */
+function scriptFileName(invocationId) {
+    const stem = isSafeId(invocationId) ? invocationId : computeSha256(Buffer.from(invocationId, "utf8")).slice(0, 32);
+    return `${stem}.js`;
+}
+/** A derived name is one file name: no directory, no separator, no traversal, and no hidden file. */
+function isDerivedName(name) {
+    return isSafeId(name) && !name.startsWith(".") && name.length <= 128;
+}
+async function existingAt(absolute) {
+    const stats = unwrapOrThrow(await tryFs("scratch.lstatDerived", () => lstat(absolute), { path: absolute, onAbsent: () => null }));
+    if (stats === null)
+        return { kind: "absent" };
+    if (!stats.isFile())
+        return { kind: "other" };
+    return { kind: "file", hash: await computeSha256File(absolute) };
+}
+/** The bytes of the regular files of one directory. A directory that is not there holds none. */
+async function directoryBytes(absolute) {
+    const entries = unwrapOrThrow(await tryFs("scratch.readDerived", () => readdir(absolute, { withFileTypes: true }), { path: absolute, onAbsent: () => [] }));
+    let total = 0;
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const path = join(absolute, entry.name);
+        const stats = unwrapOrThrow(await tryFs("scratch.lstatEntry", () => lstat(path), { path, onAbsent: () => null }));
+        total += stats?.size ?? 0;
+    }
+    return total;
+}
+export function createScriptScratch(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("script-scratch");
+    const observe = bindSessionEmit(deps.provenance, logger);
+    async function land(session, dir, name, content, invocationId) {
+        const { analysisId } = session.scope;
+        const workspaceRoot = await deps.resolveWorkspaceRoot(analysisId);
+        const landed = await confinedWrite({
+            workspaceRoot,
+            analysisId,
+            workingDir: join(workspaceRoot, dir),
+            path: name,
+            content,
+            invocationId,
+            beforeLand: undefined,
+            refuseStagedInputs: true,
+        });
+        if (landed.status !== "ok")
+            return { refused: `the write of ${dir}/${name} was refused (${landed.status})` };
+        return { path: landed.relative, hash: computeSha256(landed.bytes), size: landed.bytes.length };
+    }
+    return {
+        async saveScript({ session, invocationId, code }) {
+            const { threadId } = session.scope;
+            if (threadId === undefined)
+                return undefined;
+            const saved = await land(session, `${deps.sessionDir(threadId)}/scripts`, scriptFileName(invocationId), code, invocationId);
+            if ("refused" in saved)
+                throw new Error(saved.refused);
+            return saved;
+        },
+        async writeDerived({ session, invocationId, name, content }) {
+            const { analysisId, threadId } = session.scope;
+            if (threadId === undefined)
+                return { status: "refused", reason: "this session has no thread, thus a script has no directory to write in" };
+            if (!isDerivedName(name)) {
+                return {
+                    status: "refused",
+                    reason: "a name is one file name of letters, digits, '.', '_', and '-', with no directory, for example de_top50.csv",
+                };
+            }
+            const data = typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content);
+            const bytes = data.length;
+            if (bytes > DERIVED_FILE_CAP_BYTES) {
+                return {
+                    status: "refused",
+                    reason: `the file is ${String(bytes)} bytes, and the cap of a derived file is ${String(DERIVED_FILE_CAP_BYTES)} bytes`,
+                };
+            }
+            const dir = `${deps.sessionDir(threadId)}/derived`;
+            const absoluteDir = join(await deps.resolveWorkspaceRoot(analysisId), dir);
+            const hash = computeSha256(data);
+            const existing = await existingAt(join(absoluteDir, name));
+            if (existing.kind === "other")
+                return { status: "refused", reason: `${dir}/${name} is not a regular file` };
+            if (existing.kind === "file") {
+                if (existing.hash === hash)
+                    return { status: "written", file: { path: `${dir}/${name}`, hash, size: bytes } };
+                return { status: "refused", reason: `this session already holds a different ${name}, thus this file takes a new name` };
+            }
+            const used = await directoryBytes(absoluteDir);
+            if (used + bytes > DERIVED_SESSION_CAP_BYTES) {
+                return { status: "refused", reason: `the derived files of this session would pass the cap of ${String(DERIVED_SESSION_CAP_BYTES)} bytes` };
+            }
+            const landed = await land(session, dir, name, content, invocationId);
+            if ("refused" in landed)
+                return { status: "refused", reason: landed.refused };
+            return { status: "written", file: landed };
+        },
+        recordRun(record) {
+            if (record.reads.length === 0 && record.writes.length === 0)
+                return;
+            const event = {
+                type: "run-script",
+                analysisId: record.analysisId,
+                invocationId: record.invocationId,
+                reads: record.reads.map((read) => ({ path: read.path, hash: read.hash })),
+                writes: record.writes.map((write) => ({ path: write.path, hash: write.hash, size: write.size })),
+                tools: [...record.tools],
+                ok: record.ok,
+            };
+            if (record.threadId !== undefined)
+                event.threadId = record.threadId;
+            if (record.script !== undefined)
+                event.script = { path: record.script.path, hash: record.script.hash, size: record.script.size };
+            observe(event);
+        },
+    };
+}

package/dist/tools/start-report-session.js

@@ -67,7 +67,7 @@ const startReportSessionInput = z.object({
     newSessionAnyway: z
         .boolean()
         .optional()
-        .describe("Set it to true to start a new session when the conversation holds no user turn of new work after the last report session. The default is false."),
+        .describe("Set it to true to start a new session when the conversation holds no user turn of new work after the last report session, and only when the user asks for a separate report. The default is false."),
 });
 /** The line that a call reads when the scope names no conversation thread. */
 const NO_THREAD_SCOPE_DETAIL = "the scope of the call names no conversation thread, thus the tool cannot start a child session";

package/dist/tools/workspace/edit-file.js

@@ -142,12 +142,13 @@ export function createEditFileTool(deps) {
     const stepKey = deps.stepKey ?? durableStepKey;
     return defineTool({
         id: "edit_file",
+        ownStep: true,
         description: "Edit a file in your working directory by replacing specific text. " +
             "Read the file first to get the exact text. When replace_all is false " +
             "(default), old_string must occur exactly once. For a bulk pattern " +
             "edit set regex=true: old_string is a JS regex, new_string may use $1 " +
             "references, and exactly one of replace_all=true or expected_matches " +
-            "gates the write. Returns `out_of_prefix` / `out_of_scope` / `symlink_denied` / " +
+            "gates the write. Returns `out_of_prefix` / `out_of_scope` / `symlink_denied` / `read_only` / " +
             "`file_not_found` / `not_found` / `not_unique` / `match_count_mismatch` / " +
             "`invalid_pattern` / `invalid_arguments` data variants — never throws on expected outcomes. " +
             "A data variant other than `ok` writes nothing.",

package/dist/tools/workspace/execute-command.d.ts

@@ -2,12 +2,11 @@
  * `execute_command` — the single chokepoint through which sandbox commands
  * run.
  *
- * Dependency-bearing factory (see the harness-durable-runtime spec): captures a
- * `SandboxClient` and the live `SandboxRef` for the step. No other tool, agent,
- * or workflow step is permitted to POST to sandbox-server's `/exec` directly —
- * `SandboxClient` is intentionally injected only here so the durability /
- * idempotency / liveness story `harness-sandbox-exec` owns holds uniformly
- * across all sandbox command execution.
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures the
+ * lease of the step. The sandbox module gives the machine of the lease, or a new
+ * one when the machine went away, thus the durability, idempotency, and liveness
+ * story of `harness-sandbox-exec` holds for each command. A command with no lease
+ * gives an error result that names `acquire_sandbox`.
  *
  * The loop runs each call as one durable step, and the exec runs inside it,
  * thus the exec id is the id of that step and a replay returns the cached
@@ -27,8 +26,8 @@
  */
 import { z } from "zod";
 import { type Tool, type WithToolCallRecord } from "../define-tool.js";
-import type { SandboxClient } from "../../sandbox/client.js";
-import type { ProvenanceFrame, SandboxRef } from "../../sandbox/types.js";
+import type { BoundLease } from "../../sandbox/leases.js";
+import type { ProvenanceFrame } from "../../sandbox/types.js";
 import type { ProvenanceCollector } from "../../provenance/collector.js";
 import type { WorkspaceMutator, WriteRecord } from "./mutator.js";
 import { type BoundedExecResult } from "./result-bounds.js";
@@ -55,11 +54,8 @@ type ExecuteCommandResult = {
 export type ExecuteCommandDeps = {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
-    readonly sandboxClient: SandboxClient;
-    /** Live sandbox handle for the step. Created once per step at composition root. */
-    readonly sandbox: SandboxRef;
-    /** Absolute unix-ms deadline of the exec. Typically derived from `step.timeout`. */
-    readonly deadlineMs: () => number;
+    /** The lease of the step: `acquire_sandbox` takes it, and each command runs on its machine. */
+    readonly lease: BoundLease;
     /**
      * In-sandbox absolute path of the agent's working directory (e.g.
      * `/{resourceId}/runs/{runId}/{stepId}`). Used as the default `cwd` so a