@inflexa-ai/harness 0.44.0 → 0.45.1

package/dist/tools/research/web-search.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `web_search` — the web step of the conversation agent's research.
+ *
+ * The tool queries a `WebSearchEngine` the embedder injects at the composition
+ * root; the SearXNG realization ships beside it in `searxng-engine.ts`. The
+ * tool owns the input contract and the search semantics the spec pins — the
+ * domain-filter terms and the host re-filter, the queries merge, the bound —
+ * and every engine failure rides the ok channel as a data-status variant,
+ * never as an error of the turn.
+ */
+import { type Result } from "neverthrow";
+export interface WebSearchAnswer {
+    readonly answer?: string;
+    readonly url?: string;
+}
+export interface WebSearchResult {
+    readonly title: string;
+    readonly url: string;
+    readonly snippet?: string;
+}
+export type WebSearchOutput = {
+    readonly status: "ok";
+    readonly answers: readonly WebSearchAnswer[];
+    readonly results: readonly WebSearchResult[];
+} | {
+    readonly status: "http_error";
+    readonly httpStatus: number;
+    readonly text: string;
+} | {
+    readonly status: "retryable_status";
+    readonly httpStatus: number;
+    readonly text: string;
+} | {
+    readonly status: "schema_mismatch";
+    readonly text: string;
+} | {
+    readonly status: "not_json";
+    readonly text: string;
+    readonly detail?: string;
+};
+/** One query with its terms already composed: the engine adds transport, not semantics. */
+export interface WebSearchRequest {
+    /** The final query text, `site:` / `-site:` terms included. */
+    readonly query: string;
+    readonly recencyFilter?: "day" | "week" | "month" | "year";
+}
+/** What one query returned: the mapped answers and the mapped result rows. */
+export type WebSearchPage = {
+    readonly answers: readonly WebSearchAnswer[];
+    readonly results: readonly WebSearchResult[];
+};
+/** The error side of the engine result: the data-status variants the tool reports as normal results. */
+export type WebSearchEngineError = Exclude<WebSearchOutput, {
+    readonly status: "ok";
+}>;
+/**
+ * The injected web-search engine: an embedder supplies one realization, and the
+ * conversation agent attaches `web_search` iff it did. `search` gets the final
+ * query terms and the optional recency filter, and resolves to the page or to
+ * the error variant that names the failure.
+ */
+export interface WebSearchEngine {
+    search(request: WebSearchRequest): Promise<Result<WebSearchPage, WebSearchEngineError>>;
+}
+export interface WebSearchToolDeps {
+    /** The web-search engine the embedder injected. */
+    readonly engine: WebSearchEngine;
+}
+export declare function createWebSearchTool(deps: WebSearchToolDeps): import("../define-tool.js").Tool<{
+    numResults: number;
+    query?: string | undefined;
+    queries?: string[] | undefined;
+    recencyFilter?: "year" | "day" | "week" | "month" | undefined;
+    domainFilter?: string | undefined;
+}, WebSearchOutput>;

package/dist/tools/research/web-search.js

@@ -0,0 +1,112 @@
+/**
+ * `web_search` — the web step of the conversation agent's research.
+ *
+ * The tool queries a `WebSearchEngine` the embedder injects at the composition
+ * root; the SearXNG realization ships beside it in `searxng-engine.ts`. The
+ * tool owns the input contract and the search semantics the spec pins — the
+ * domain-filter terms and the host re-filter, the queries merge, the bound —
+ * and every engine failure rides the ok channel as a data-status variant,
+ * never as an error of the turn.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+function parseDomainFilter(raw) {
+    const trimmed = (raw ?? "").trim().toLowerCase();
+    if (trimmed === "" || trimmed === "-")
+        return null;
+    if (trimmed.startsWith("-")) {
+        const domain = trimmed.slice(1).trim();
+        return domain === "" ? null : { include: false, domain };
+    }
+    return { include: true, domain: trimmed };
+}
+function queryTerms(query, filter) {
+    if (!filter)
+        return query;
+    return `${query} ${filter.include ? "" : "-"}site:${filter.domain}`;
+}
+/** A domain matches a host and each subdomain of the domain. */
+function hostMatchesDomain(host, domain) {
+    return host === domain || host.endsWith(`.${domain}`);
+}
+function hostOf(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return null;
+    }
+}
+/** Filter the merged rows by host again, because an engine can ignore `site:`. */
+function applyDomainFilter(results, filter) {
+    if (!filter)
+        return [...results];
+    return results.filter((result) => {
+        const host = hostOf(result.url);
+        if (host === null)
+            return !filter.include;
+        const matches = hostMatchesDomain(host, filter.domain);
+        return filter.include ? matches : !matches;
+    });
+}
+export function createWebSearchTool(deps) {
+    return defineTool({
+        id: "web_search",
+        description: "Search the web for pages: titles, URLs, and short snippets, plus any direct answers the engines returned. " +
+            "Give `query` for one search, or `queries` (at most 5) for one pass whose answers and results merge into a single " +
+            "list of at most `numResults` results, duplicates by URL removed. `domainFilter` restricts the search to one domain " +
+            'and a leading "-" excludes it, for example "-pinterest.com". `recencyFilter` keeps only results from the last day, ' +
+            "week, month, or year. Read one of the returned pages with `web_fetch`.\n" +
+            "ABSENCE IS NORMAL: an empty results array means no page matched, and a status of http_error, retryable_status, " +
+            "schema_mismatch, or not_json names a search that did not answer. Report either one and continue, do not retry unchanged.",
+        inputSchema: z
+            .object({
+            query: z.string().min(1).optional().describe("One free-text search, for example a method name with its domain."),
+            queries: z
+                .array(z.string().min(1))
+                .min(1)
+                .max(5)
+                .optional()
+                .describe("Up to 5 searches that run in one pass. Answers and results merge into one bounded list."),
+            numResults: z.number().int().min(1).max(20).default(5).describe("Maximum merged results (1–20, default 5)."),
+            recencyFilter: z.enum(["day", "week", "month", "year"]).optional().describe("Keep only results from this recency."),
+            domainFilter: z
+                .string()
+                .optional()
+                .describe('One domain the search stays in, for example "nih.gov". A leading "-" excludes the domain instead.'),
+        })
+            .refine((input) => (input.query !== undefined) !== (input.queries !== undefined), {
+            message: "Give exactly one of `query` or `queries`.",
+        }),
+        describeCall: "none",
+        execute: async ({ query, queries, numResults, recencyFilter, domainFilter }) => {
+            const filter = parseDomainFilter(domainFilter);
+            // The input refine guarantees exactly one of `query` and `queries`.
+            const queryList = queries ?? [query];
+            const requests = queryList.map((raw) => deps.engine.search({ query: queryTerms(raw, filter), ...(recencyFilter ? { recencyFilter } : {}) }));
+            const responses = [];
+            for (const response of await Promise.all(requests)) {
+                // An engine failure is the data-status variant the tool reports, not a turn error.
+                if (response.isErr())
+                    return ok(response.error);
+                responses.push(response.value);
+            }
+            const answers = [];
+            const seen = new Set();
+            const results = [];
+            for (const response of responses) {
+                answers.push(...response.answers);
+                for (const result of applyDomainFilter(response.results, filter)) {
+                    if (results.length >= numResults)
+                        break;
+                    if (seen.has(result.url))
+                        continue;
+                    seen.add(result.url);
+                    results.push(result);
+                }
+            }
+            return ok({ status: "ok", answers, results });
+        },
+    });
+}

package/dist/tools/sandbox/list-available-packages.d.ts

@@ -41,13 +41,16 @@ export declare function trackOfLockSubtree(subtree: string): Track | undefined;
  */
 export declare function lockSections(lock: FarmLock): Section[];
 /**
- * Group the image record into its two sections, in the order of the record.
- * An empty track yields no section, so the report never carries a heading
- * with nothing under it.
+ * Group the image record into its sections, in the order of the record. An
+ * empty or absent track yields no section, so the report never carries a
+ * heading with nothing under it.
  *
  * A `system_tools` row renders its `executable` name where the record gives
  * one, because an agent invokes the binary rather than the conda package
- * (the manifest `binaries:` map holds the pairs that differ).
+ * (the manifest `binaries:` map holds the pairs that differ). The `r_base`
+ * rows are the R track: a `names` lookup of `survival` or `MASS` resolves
+ * there, with the version the runtime ships, and the `language: "r"` filter
+ * lists them beside the farm packages.
  */
 export declare function imageSections(record: ImagePackages): Section[];
 /** One package entry of a section, with the store identity where the source records it. */

package/dist/tools/sandbox/list-available-packages.js

@@ -53,6 +53,8 @@ const DEFAULT_IMAGE_PACKAGES_FILE = `${LIBS_CONTAINER_PATH}/${IMAGE_PACKAGES_FIL
  */
 const CLI_TITLE = "System tools (CLI)";
 const NODE_TITLE = "Node (npm)";
+/** The R packages that ship with the R runtime of the image: the base and the recommended packages. */
+const R_BASE_TITLE = "R (ships with R)";
 /** The section title of each known lock track. An unknown track titles itself. */
 const TRACK_TITLES = {
     python: "Python (pip)",
@@ -101,16 +103,22 @@ export function lockSections(lock) {
     });
 }
 /**
- * Group the image record into its two sections, in the order of the record.
- * An empty track yields no section, so the report never carries a heading
- * with nothing under it.
+ * Group the image record into its sections, in the order of the record. An
+ * empty or absent track yields no section, so the report never carries a
+ * heading with nothing under it.
  *
  * A `system_tools` row renders its `executable` name where the record gives
  * one, because an agent invokes the binary rather than the conda package
- * (the manifest `binaries:` map holds the pairs that differ).
+ * (the manifest `binaries:` map holds the pairs that differ). The `r_base`
+ * rows are the R track: a `names` lookup of `survival` or `MASS` resolves
+ * there, with the version the runtime ships, and the `language: "r"` filter
+ * lists them beside the farm packages.
  */
 export function imageSections(record) {
     const sections = [];
+    if (record.r_base !== undefined && record.r_base.length > 0) {
+        sections.push({ title: R_BASE_TITLE, track: "r", packages: record.r_base.map((pkg) => ({ name: pkg.name, version: pkg.version })) });
+    }
     if (record.system_tools.length > 0) {
         sections.push({
             title: CLI_TITLE,

package/dist/tools/sandbox/list-available-refs.d.ts

@@ -90,7 +90,28 @@ interface RawScan {
     readonly receipts?: unknown[];
     readonly legacyEntries?: unknown[];
 }
+/**
+ * The dataset ids the install receipts of the store report, for a caller that must know whether a
+ * declared dataset is present BEFORE a run starts.
+ *
+ * `undefined` means the store itself could not be answered for: an unreadable root, a `.inflexa`
+ * that crosses a symlink, or a receipts directory that exists and cannot be listed. That is NOT an
+ * empty install, and a caller must never collapse the two — every dataset would read as absent, and
+ * a launch would be refused over data that is sitting in the store.
+ *
+ * An empty set is a real answer: the store is readable and it holds no receipt.
+ */
+export declare function readInstalledDatasetIds(deps: ListAvailableRefsDeps): Promise<ReadonlySet<string> | undefined>;
 /** Create reference discovery over the host-visible reference store. */
+/**
+ * The whole enriched inventory of the store, for a host-side join: which
+ * collection a procedure names is present, and where. No envelope bound,
+ * because the caller keeps the join and drops the listing.
+ */
+export declare function readReferenceInventory(storeRoot: string): Promise<{
+    readonly available: boolean;
+    readonly entries: readonly ReferenceInventoryEntry[];
+}>;
 export declare function createListAvailableRefsTool(deps: ListAvailableRefsDeps): import("../define-tool.js").Tool<{
     path?: string | undefined;
     category?: string | undefined;

package/dist/tools/sandbox/list-available-refs.js

@@ -205,6 +205,54 @@ async function readReceipts(root) {
     }
     return receipts;
 }
+/**
+ * The dataset ids the install receipts of the store report, for a caller that must know whether a
+ * declared dataset is present BEFORE a run starts.
+ *
+ * `undefined` means the store itself could not be answered for: an unreadable root, a `.inflexa`
+ * that crosses a symlink, or a receipts directory that exists and cannot be listed. That is NOT an
+ * empty install, and a caller must never collapse the two — every dataset would read as absent, and
+ * a launch would be refused over data that is sitting in the store.
+ *
+ * An empty set is a real answer: the store is readable and it holds no receipt.
+ */
+export async function readInstalledDatasetIds(deps) {
+    const storeRoot = deps.refStorePath ?? REFS_ROOT;
+    try {
+        await lstat(storeRoot);
+    }
+    catch {
+        return undefined;
+    }
+    if (await crossesSymlink(storeRoot, ".inflexa"))
+        return undefined;
+    const receiptsDirectory = hostJoin(storeRoot, ".inflexa", "receipts");
+    let names;
+    try {
+        names = (await readdir(receiptsDirectory)).slice(0, MAX_RECEIPT_FILES);
+    }
+    catch (error) {
+        // An absent directory is a readable store with nothing installed. Any other failure is the
+        // store declining to answer, which is a different fact and gets the honest `undefined`.
+        if (error.code === "ENOENT")
+            return new Set();
+        return undefined;
+    }
+    const ids = new Set();
+    for (const name of names) {
+        // Per-file, so one malformed receipt costs only its own dataset. A shared try would drop
+        // every receipt after the bad one and read as a store that holds almost nothing.
+        try {
+            const receipt = parseReferenceInstallReceipt(JSON.parse(await readFile(hostJoin(receiptsDirectory, name), "utf-8")));
+            if (receipt)
+                ids.add(receipt.datasetId);
+        }
+        catch {
+            continue;
+        }
+    }
+    return ids;
+}
 /** Labels from a `registry.json` an externally-provisioned store may carry. */
 async function readLegacyEntries(root) {
     const legacyEntries = [];
@@ -465,8 +513,8 @@ function collectCategories(entries) {
 }
 function renderContent(path, scan, entries) {
     if (scan.state === "unavailable")
-        return ("No reference store is provisioned. Nothing in the analysis environment can fetch reference data — the host stages it, " +
-            "so a store provisioned through the host's own path will show up on a later call.");
+        return ("No reference store is provisioned for this session. Nothing in the analysis environment can fetch reference data, and a later call " +
+            "in this run gives the same answer. Plan with the data at hand, or ask for the reference by what it is.");
     if (scan.state === "not_found")
         return `Reference path does not exist: ${path}`;
     if (scan.state === "not_a_directory")
@@ -499,6 +547,15 @@ function renderContent(path, scan, entries) {
     return lines.join("\n");
 }
 /** Create reference discovery over the host-visible reference store. */
+/**
+ * The whole enriched inventory of the store, for a host-side join: which
+ * collection a procedure names is present, and where. No envelope bound,
+ * because the caller keeps the join and drops the listing.
+ */
+export async function readReferenceInventory(storeRoot) {
+    const raw = await scanStore(storeRoot, ".", true);
+    return { available: raw.state !== "unavailable", entries: enrichEntries(raw.entries, raw) };
+}
 export function createListAvailableRefsTool(deps) {
     const storeRoot = deps.refStorePath ?? REFS_ROOT;
     return defineTool({
@@ -516,7 +573,7 @@ export function createListAvailableRefsTool(deps) {
             "pass a group label as `query`, because `category` inspects a top-level directory by name and a label that is not a directory reads as `not_found`; " +
             "`limit` caps the entries returned. The response carries `returned`, `total`, and `hasMore`, so truncation is never silent. " +
             "An empty result means the dataset is absent right now — not that it is unobtainable. Say so; never guess a path, and never silently substitute a different dataset. " +
-            "The store is provisioned by the host and is NOT frozen: datasets can be added through the host's own provisioning path, and whatever is added shows up on a later call.",
+            "The store is provisioned by the host and is NOT frozen: datasets can be added through the host's own provisioning path between runs, and whatever is added shows up in a later run. Within one run the listing does not change, thus one call per question is enough.",
         inputSchema: ListAvailableRefsInputSchema,
         // `execute` resolves `path ?? category` for the subtree it inspects, and
         // it ignores `category` when `path` is present. `query` is an ADDITIVE

package/dist/tools/sandbox/report-blocker.js

@@ -18,10 +18,11 @@
  * runs in durable steps, so it reads the blocker back from the transcript
  * (`recordedBlocker`) on replay, not only from its cell.
  */
-import { ok } from "neverthrow";
+import { err, ok } from "neverthrow";
 import { z } from "zod";
 import { repairToolInput } from "../../lib/zod-issues.js";
 import { toolOutcomeForOutputType } from "../../loop/tool-outcome.js";
+import { degenerateTerminalText } from "../terminal-text.js";
 import { defineTool } from "../define-tool.js";
 export const REPORT_BLOCKER_TOOL_ID = "report_blocker";
 export function createBlockerHolder() {
@@ -46,6 +47,9 @@ export function createReportBlockerToolFor(deps) {
         inputSchema: ReportBlockerInputSchema,
         describeCall: "none",
         execute: async (input) => {
+            const degenerate = degenerateTerminalText(input.reason);
+            if (degenerate)
+                return err({ error: `${degenerate} Give the real reason, or continue the work.`, retryable: true });
             deps.record({ kind: "blocker", reason: input.reason });
             return ok({
                 recorded: true,

package/dist/tools/terminal-text.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The text of a terminal call: a clarification question or a blocker reason.
+ *
+ * A terminal call whose text is a placeholder ends a run with nothing. A small
+ * model emits such a call when it drafts several calls at once and fills the
+ * text later, or never. The guard names the fault, the tool refuses the call,
+ * and the loop continues with the real work.
+ */
+export declare const MIN_TERMINAL_TEXT = 4;
+/** The reason a text cannot end a run, or undefined when it can. */
+export declare function degenerateTerminalText(text: string): string | undefined;

package/dist/tools/terminal-text.js

@@ -0,0 +1,19 @@
+/**
+ * The text of a terminal call: a clarification question or a blocker reason.
+ *
+ * A terminal call whose text is a placeholder ends a run with nothing. A small
+ * model emits such a call when it drafts several calls at once and fills the
+ * text later, or never. The guard names the fault, the tool refuses the call,
+ * and the loop continues with the real work.
+ */
+const PLACEHOLDER_TEXT = /^\s*(?:placeholder|todo|tbd|skip|n\/?a|none|null|test|x+|\.+|-+)\b/i;
+export const MIN_TERMINAL_TEXT = 4;
+/** The reason a text cannot end a run, or undefined when it can. */
+export function degenerateTerminalText(text) {
+    const trimmed = text.trim();
+    if (trimmed.length < MIN_TERMINAL_TEXT)
+        return `The text has ${trimmed.length} characters, and a real question or reason has at least ${MIN_TERMINAL_TEXT}.`;
+    if (PLACEHOLDER_TEXT.test(trimmed) || /\bplaceholder\b/i.test(trimmed))
+        return "The text is a placeholder.";
+    return undefined;
+}

package/dist/tools/workspace/decision-record.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The decision record of a rendered script, as the file tools keep it true
+ * after the render. `knowledge_template` writes the record beside the
+ * script with the digest of the bytes it wrote. A later change of the
+ * script through `edit_file` appends an entry to `unvetted_edits` with the
+ * digest after the change, and `execute_command` compares the script it is
+ * about to run with the last recorded digest, thus a change by any other
+ * path is recorded before the script runs. The record then connects the
+ * cited decision to the bytes that ran, and an empty `unvetted_edits` is a
+ * fact and not an assumption.
+ */
+import type { AgentSession } from "../../auth/types.js";
+import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
+import type { MutateToolName, WorkspaceMutator, WriteRecord } from "./mutator.js";
+/**
+ * The path of the decision record of one rendered script inside the step:
+ * `output/decision_record_<script stem>.json`. One record per render, thus a
+ * step that renders two scripts keeps both records.
+ */
+export declare function decisionRecordPath(scriptFile: string): string;
+/**
+ * The record path of a script path, or `undefined` when the path is not a
+ * script under `scripts/`. A relative `scripts/x.R` gives the relative
+ * record path, and an absolute `/<analysisId>/.../scripts/x.R` gives the
+ * absolute one, beside it in the same step.
+ */
+export declare function decisionRecordPathFor(scriptPath: string): string | undefined;
+export declare function scriptSha256(content: string | Uint8Array): string;
+/** One change of a script after its render, as the record keeps it. */
+export interface UnvettedEdit {
+    readonly path: string;
+    readonly note: string;
+    /** The digest of the script after the change. */
+    readonly sha256: string;
+}
+/** The digest the record expects of the script now: the last recorded change, else the bytes the render wrote. */
+export declare function expectedScriptSha256(record: Readonly<Record<string, unknown>>): string | undefined;
+export interface NoteScriptChangeArgs {
+    readonly filesystem: WorkspaceFilesystem;
+    readonly mutator: WorkspaceMutator;
+    readonly session: AgentSession;
+    /** Absolute host base for a relative path; the analysis root when absent. */
+    readonly workingDir?: string;
+    readonly invocationId: string;
+    /** The tool that made the change, for the provenance of the record write. */
+    readonly toolName: MutateToolName;
+    /** The script path as the tool received it, relative or absolute. */
+    readonly scriptPath: string;
+    readonly note: string;
+    /** The digest of the script after the change. */
+    readonly sha256: string;
+}
+/**
+ * The outcome of a change note. `noted` carries the record of the write,
+ * thus the calling tool carries it as its call record, and its fold hands it
+ * to `recordWrite`.
+ */
+export type ScriptChangeNote = {
+    readonly status: "noted";
+    readonly write: WriteRecord;
+} | {
+    readonly status: "no_record" | "refused";
+};
+/**
+ * Append a change to the record of a script. `no_record` when the path is
+ * not a script under `scripts/`, or when no record exists for it, which is
+ * the state of every script an agent wrote itself. `refused` when the
+ * mutator refused the write of the record, for example a record of another
+ * step, outside the writable prefix of this one.
+ */
+export declare function noteScriptChange(args: NoteScriptChangeArgs): Promise<ScriptChangeNote>;
+export type ReconcileScriptRecordArgs = Omit<NoteScriptChangeArgs, "note" | "sha256">;
+/**
+ * Compare a script with the digest its record expects, before the script
+ * runs. A difference is a change that no tool of the host recorded, and it
+ * is noted with the digest of the bytes that are about to run. `unchanged`
+ * when the digests agree, `no_record` when the script has no record.
+ */
+export declare function reconcileScriptRecord(args: ReconcileScriptRecordArgs): Promise<ScriptChangeNote | {
+    readonly status: "unchanged";
+}>;

package/dist/tools/workspace/decision-record.js

@@ -0,0 +1,117 @@
+/**
+ * The decision record of a rendered script, as the file tools keep it true
+ * after the render. `knowledge_template` writes the record beside the
+ * script with the digest of the bytes it wrote. A later change of the
+ * script through `edit_file` appends an entry to `unvetted_edits` with the
+ * digest after the change, and `execute_command` compares the script it is
+ * about to run with the last recorded digest, thus a change by any other
+ * path is recorded before the script runs. The record then connects the
+ * cited decision to the bytes that ran, and an empty `unvetted_edits` is a
+ * fact and not an assumption.
+ */
+import { createHash } from "node:crypto";
+import { posix as posixPath } from "node:path";
+import { unwrapOrThrow } from "../../lib/result.js";
+/**
+ * The path of the decision record of one rendered script inside the step:
+ * `output/decision_record_<script stem>.json`. One record per render, thus a
+ * step that renders two scripts keeps both records.
+ */
+export function decisionRecordPath(scriptFile) {
+    const stem = scriptFile.replace(/\.[A-Za-z0-9]+$/, "");
+    return `output/decision_record_${stem}.json`;
+}
+/**
+ * The record path of a script path, or `undefined` when the path is not a
+ * script under `scripts/`. A relative `scripts/x.R` gives the relative
+ * record path, and an absolute `/<analysisId>/.../scripts/x.R` gives the
+ * absolute one, beside it in the same step.
+ */
+export function decisionRecordPathFor(scriptPath) {
+    const dir = posixPath.dirname(scriptPath);
+    if (posixPath.basename(dir) !== "scripts")
+        return undefined;
+    const record = decisionRecordPath(posixPath.basename(scriptPath));
+    return dir === "scripts" ? record : posixPath.join(posixPath.dirname(dir), record);
+}
+export function scriptSha256(content) {
+    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+/** The digest the record expects of the script now: the last recorded change, else the bytes the render wrote. */
+export function expectedScriptSha256(record) {
+    const edits = Array.isArray(record.unvetted_edits) ? record.unvetted_edits : [];
+    const last = edits[edits.length - 1]?.sha256;
+    if (typeof last === "string")
+        return last;
+    return typeof record.written_sha256 === "string" ? record.written_sha256 : undefined;
+}
+/**
+ * Append a change to the record of a script. `no_record` when the path is
+ * not a script under `scripts/`, or when no record exists for it, which is
+ * the state of every script an agent wrote itself. `refused` when the
+ * mutator refused the write of the record, for example a record of another
+ * step, outside the writable prefix of this one.
+ */
+export async function noteScriptChange(args) {
+    const recordPath = decisionRecordPathFor(args.scriptPath);
+    if (!recordPath)
+        return { status: "no_record" };
+    const read = unwrapOrThrow(await args.filesystem.readFile({ session: args.session, path: recordPath, ...(args.workingDir !== undefined ? { workingDir: args.workingDir } : {}) }));
+    if (read.kind !== "ok")
+        return { status: "no_record" };
+    let record;
+    try {
+        const parsed = JSON.parse(read.content.toString("utf8"));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            return { status: "no_record" };
+        record = parsed;
+    }
+    catch {
+        return { status: "no_record" };
+    }
+    const edits = Array.isArray(record.unvetted_edits) ? record.unvetted_edits : [];
+    const entry = { path: args.scriptPath, note: args.note, sha256: args.sha256 };
+    const next = { ...record, unvetted_edits: [...edits, entry] };
+    const written = await args.mutator.writeFile({
+        path: recordPath,
+        content: `${JSON.stringify(next, null, 2)}\n`,
+        toolName: args.toolName,
+        invocationId: args.invocationId,
+        session: args.session,
+    });
+    return written.status === "ok" ? { status: "noted", write: written.record } : { status: "refused" };
+}
+/**
+ * Compare a script with the digest its record expects, before the script
+ * runs. A difference is a change that no tool of the host recorded, and it
+ * is noted with the digest of the bytes that are about to run. `unchanged`
+ * when the digests agree, `no_record` when the script has no record.
+ */
+export async function reconcileScriptRecord(args) {
+    const recordPath = decisionRecordPathFor(args.scriptPath);
+    if (!recordPath)
+        return { status: "no_record" };
+    const base = args.workingDir !== undefined ? { workingDir: args.workingDir } : {};
+    const record = unwrapOrThrow(await args.filesystem.readFile({ session: args.session, path: recordPath, ...base }));
+    if (record.kind !== "ok")
+        return { status: "no_record" };
+    let expected;
+    try {
+        const parsed = JSON.parse(record.content.toString("utf8"));
+        if (parsed === null || typeof parsed !== "object")
+            return { status: "no_record" };
+        expected = expectedScriptSha256(parsed);
+    }
+    catch {
+        return { status: "no_record" };
+    }
+    if (expected === undefined)
+        return { status: "no_record" };
+    const script = unwrapOrThrow(await args.filesystem.readFile({ session: args.session, path: args.scriptPath, ...base }));
+    if (script.kind !== "ok")
+        return { status: "no_record" };
+    const actual = scriptSha256(script.content);
+    if (actual === expected)
+        return { status: "unchanged" };
+    return noteScriptChange({ ...args, note: "the script changed by a path no file tool recorded, before it ran", sha256: actual });
+}

package/dist/tools/workspace/edit-file.d.ts

@@ -51,7 +51,9 @@ export type EditFileResult = {
     readonly bytesWritten: number;
     /** Regex mode only: 1-based line numbers where the matches started. */
     readonly lines?: readonly number[];
-}, WriteRecord>;
+    /** True when the file is a rendered script and its decision record now lists this edit. */
+    readonly decision_record_noted?: true;
+}, readonly WriteRecord[]>;
 export interface EditFileDeps {
     readonly mutator: WorkspaceMutator;
     /** Read seam used to fetch current file content for search/replace. */