@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/tools/report-session/derive-table.js

@@ -5,10 +5,12 @@
  * table that a block can bind: a join, a pivot, or an aggregate. The agent writes the script, and the record
  * chains the derived table back to the evidence that made it.
  *
- * A session derivation is not an analysis run. It mints no run id, it registers no artifact, and it writes
+ * A session derivation is not an analysis run. It mints no run id, no mandate, and no artifact, and it writes
  * under the session directory alone. The rails are the rails of the value tier (`tasks/extract-values.ts`):
- * the injected exec runner, the identity mint, and the authorizer on every terminal path. The container is
- * ephemeral, and it goes away with the work.
+ * one ephemeral container inside the step of the call (`sandbox/step-sandbox.ts`), which goes away with the
+ * work. The container stays until the record lands, thus a rerun of the step before the record adopts the
+ * container and the exec record of the first attempt, and the script does not run again. A rerun after the
+ * record finds the record of its call, and it gives that table back.
  *
  * The container mounts the analysis tree read-only, and one write mount covers the `derived/` directory of
  * the session alone. The script writes its table into that mount directly, thus a large table makes no
@@ -25,24 +27,19 @@
  * The tool refuses an output name that the membership already holds. A record is immutable, and a second
  * derivation of one table takes a new name.
  *
- * A composition with no sandbox client and no run authorizer cannot derive at all. The tool reports that
- * condition one time, up front, the same discipline as the eyes. A per-attempt failure would instead read as
- * a transient fault, and it would invite a repeat of a call that can never pass.
- *
- * The container runs behind a seam, and never in the turn. An exec is a durable step of a workflow, and a
- * report turn is not a workflow. Thus the tool takes an injected runner, and a registered workflow owns the
- * container. The tool holds no sandbox client, and it imports no DBOS.
+ * A composition with no sandbox client cannot derive at all. The tool reports that condition one time, up
+ * front, the same discipline as the eyes. A per-attempt failure would instead read as a transient fault, and
+ * it would invite a repeat of a call that can never pass.
  */
 import { ok } from "neverthrow";
-import { unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { z } from "zod";
 import { createNoopLogger } from "../../lib/console-logger.js";
-import { deliverNotice, passGate } from "../../lib/hooks.js";
 import { classifyWithinRoot, computeSha256, computeSha256File } from "../../lib/fs-helpers.js";
 import { defaultErrorFields } from "../../lib/logger.js";
 import { snapshotEntry } from "../../report-model/reference-resolver.js";
-import { generateExecutionId } from "../../sandbox/execution-id.js";
+import { isWorkflowCancellation } from "../../runtime/dbos.js";
+import { passSpawnSession, withStepSandbox } from "../../sandbox/step-sandbox.js";
 import { isSafeId, reportSessionDerivedDir, toSandboxPath } from "../../workspace/paths.js";
 import { defineTool } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
@@ -55,17 +52,17 @@ const deriveTableInput = z.object({
     output: z.string().min(1),
 });
 /** The synthetic run id and step id of one derivation. Both are constants, and neither names a run row. */
-export const DERIVE_RUN_LITERAL = "derive-table";
-export const DERIVE_STEP_LITERAL = "derive";
+const DERIVE_RUN_LITERAL = "derive-table";
+const DERIVE_STEP_LITERAL = "derive";
 /** The provenance agent id. No agent loop runs in the container, thus this names the derivation pass. */
 const DERIVE_AGENT_ID = "table-deriver";
 /** The exec budget of one derivation. It matches the budget of the value tier. */
-export const DERIVATION_DEADLINE_MS = 300_000;
+const DERIVATION_DEADLINE_MS = 300_000;
 /**
  * The container size of one derivation. A join or a pivot loads each declared input into pandas at one
  * time, thus the container needs the headroom of the value tier.
  */
-export const DERIVATION_RESOURCES = { cpu: 2, memoryGb: 8 };
+const DERIVATION_RESOURCES = { cpu: 2, memoryGb: 8 };
 /** The cap of the script, in bytes. A reshaping script sits far under it, and the command line carries it. */
 const SCRIPT_CAP_BYTES = 64 * 1024;
 /** The cap of the declared inputs. One derivation reads the evidence of a few artifacts, and never a tree. */
@@ -74,12 +71,23 @@ const INPUT_CAP = 20;
 export const DERIVE_INPUT_ENV = "DERIVE_INPUTS";
 /** The environment variable that carries the container path of the output file into the container. */
 export const DERIVE_OUTPUT_ENV = "DERIVE_OUTPUT";
+/**
+ * The shell of the exec: clear the output path, then run the script. The script rides as the first
+ * positional argument, thus `python3 -c` gets it byte for byte.
+ *
+ * The clearance belongs to the exec, and not to the host. A failed derivation can leave a file at the name
+ * that this one declares, and a script that writes nothing must not adopt those bytes as its table.
+ * sandbox-server runs one exec id one time, thus a rerun that attaches to the exec of an earlier attempt
+ * keeps the table of that exec. A clearance on the host would remove it.
+ */
+const CLEAR_THEN_RUN = `rm -f -- "$${DERIVE_OUTPUT_ENV}" && exec python3 -c "$1"`;
 /** The cap of the failure detail that the tool copies out of the standard error of the script. */
 const STDERR_TAIL_CAP = 2_000;
 /** The line that the agent reads when the composition binds no sandbox rails. */
 const NO_SANDBOX_DETAIL = "the composition gives no sandbox, thus this session cannot derive a table";
 /**
- * Build the sandbox exec of one derivation. The command runs the script of the agent through `python3 -c`.
+ * Build the sandbox exec of one derivation. The command clears the output path, and then it runs the script
+ * of the agent through `python3 -c`.
  *
  * The working directory is the write mount, thus the script writes its table beside where it stands. Each
  * declared input rides as its mounted path, thus the script opens the file wherever it works from. The
@@ -89,7 +97,7 @@ const NO_SANDBOX_DETAIL = "the composition gives no sandbox, thus this session c
  */
 export function buildDerivationExec(args) {
     return {
-        command: ["python3", "-c", args.script],
+        command: ["sh", "-c", CLEAR_THEN_RUN, "derive_table", args.script],
         cwd: args.workingDir,
         env: {
             [DERIVE_INPUT_ENV]: JSON.stringify(args.inputs.map((input) => ({ path: input.path, hash: input.hash }))),
@@ -130,7 +138,20 @@ export function describeExecFailure(result) {
 export function createDeriveTableTool(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("derive-table");
     const observe = bindSessionEmit(deps.provenance, logger);
-    const { runDerivation, runAuthorizer } = deps;
+    const observeDerived = (analysisId, threadId, result) => {
+        if (result.outcome !== "derived")
+            return;
+        observe({
+            type: "run-derivation",
+            analysisId,
+            threadId,
+            outputPath: result.path,
+            outputHash: result.hash,
+            scriptHash: result.scriptHash,
+            sources: result.sources,
+        });
+    };
+    const { sandboxClient } = deps;
     return defineTool({
         id: "derive_table",
         description: "Derive one table from the pinned evidence with a Python script, and pin the result to this session. " +
@@ -149,15 +170,14 @@ export function createDeriveTableTool(deps) {
             "A failed script gives back exec-failed with the tail of its standard error. " +
             "The outcome unavailable means that this host cannot run a derivation, and a repeat gives the same outcome.",
         inputSchema: deriveTableInput,
-        executionMode: "inline",
         describeCall: (input) => `derive ${input.output}`,
         // The derived path is the one durable product of the call, thus the derived arm names it. Each other
         // arm is a condition that refused, and the kind of the arm is what a watcher must read.
         describeResult: (_input, result) => (result.outcome === "derived" ? result.path : result.outcome),
         execute: async (input, ctx) => {
             // The check runs before every read, thus one clear signal replaces a failure for each attempt.
-            // It also narrows the two rails below, thus the exec needs no assertion.
-            if (runDerivation === undefined || runAuthorizer === undefined) {
+            // It also narrows the rail below, thus the exec needs no assertion.
+            if (sandboxClient === undefined) {
                 logger.warn("the composition gives no sandbox, thus no derivation can run");
                 return ok({ outcome: "unavailable", detail: NO_SANDBOX_DETAIL });
             }
@@ -165,7 +185,7 @@ export function createDeriveTableTool(deps) {
             if (opened.isErr()) {
                 return ok({ outcome: "refused", refusal: opened.error });
             }
-            const { threadId, analysisId, state } = opened.value;
+            const { threadId, analysisId, state, derivations } = opened.value;
             const bytes = Buffer.byteLength(input.script, "utf8");
             if (bytes > SCRIPT_CAP_BYTES) {
                 return ok({
@@ -210,15 +230,6 @@ export function createDeriveTableTool(deps) {
             // compose from the session-directory builder, thus the layout has one owner.
             const writableTail = reportSessionDerivedDir(threadId);
             const outputPath = `${writableTail}/${input.output}`;
-            // The served membership carries each derivation of the session, thus this one test refuses a
-            // repeated name and a collision with a pinned artifact alike.
-            if (snapshotEntry(state.snapshot, outputPath) !== undefined) {
-                return ok({
-                    outcome: "repeated-name",
-                    outputPath,
-                    detail: `the evidence of this session already holds ${outputPath}, thus this derivation takes a new name`,
-                });
-            }
             let root;
             try {
                 root = await deps.resolveWorkspaceRoot(analysisId);
@@ -227,59 +238,56 @@ export function createDeriveTableTool(deps) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });
                 return ok({ outcome: "unavailable", detail: "the workspace root did not resolve, thus the derived table has no place to land" });
             }
-            const authorized = await passGate("RunAuthorizer.authorize", runAuthorizer.authorize({
-                auth: ctx.session.auth,
-                scope: { kind: "analysis", analysisId },
-                provenance: { agentId: DERIVE_AGENT_ID, callPath: [DERIVE_AGENT_ID] },
-                frame: { runId: DERIVE_RUN_LITERAL, stepId: DERIVE_STEP_LITERAL },
-            }));
-            if (authorized.isErr()) {
-                const { kind, reason } = authorized.error;
-                logger.error("the derivation was not authorized", { threadId, analysisId, reason, suspend: kind === "suspended" });
-                if (kind === "suspended")
-                    return ok({ outcome: "suspended", reason, detail: `the analysis is suspended (${reason}), thus the derivation did not run` });
-                return ok({ outcome: "unavailable", detail: `the derivation was not authorized: ${reason}` });
+            // A rerun of a call whose record landed gives that record back. The membership holds the output of
+            // the record by now, thus the name test below would refuse the call its own table.
+            const recorded = derivations.find((record) => record.toolCallId === ctx.invocationId);
+            if (recorded !== undefined) {
+                const replayed = {
+                    outcome: "derived",
+                    path: recorded.outputPath,
+                    hash: recorded.outputHash,
+                    scriptHash: recorded.scriptHash,
+                    sources: [...recorded.sources],
+                    columns: await readColumnsQuietly(outputPath, join(root, outputPath), logger),
+                };
+                // A crash between the record and the emit of the earlier run loses its event, thus the rerun
+                // emits again. A consumer can get the act two times, never zero times.
+                observeDerived(analysisId, threadId, replayed);
+                return ok(replayed);
             }
-            const authorization = authorized.value;
-            // The work sits inside the `try`, and the revoke sits in the `finally`. Thus the authorization
-            // revokes on every terminal path, the thrown one included: a path builder refuses a hostile
-            // stored path with a throw, and that throw must not leave an authorization standing.
-            let result;
-            try {
-                result = await derive({
-                    runDerivation,
-                    derivations: deps.derivations,
-                    root,
-                    threadId,
-                    analysisId,
-                    runSession: authorization.runSession,
-                    script: input.script,
-                    sources,
-                    writableTail,
+            // The served membership carries each derivation of the session, thus this one test refuses a
+            // repeated name and a collision with a pinned artifact alike.
+            if (snapshotEntry(state.snapshot, outputPath) !== undefined) {
+                return ok({
+                    outcome: "repeated-name",
                     outputPath,
-                    outputName: input.output,
-                    logger,
+                    detail: `the evidence of this session already holds ${outputPath}, thus this derivation takes a new name`,
                 });
-                // The record of the derivation lands before this point, thus the event states a table that
-                // the session already holds as evidence. Each other arm derived nothing.
-                if (result.outcome === "derived") {
-                    observe({
-                        type: "run-derivation",
-                        analysisId,
-                        threadId,
-                        outputPath: result.path,
-                        outputHash: result.hash,
-                        scriptHash: result.scriptHash,
-                        sources: result.sources,
-                    });
-                }
-                return ok(result);
-            }
-            finally {
-                // The revoke is a notice: its failure changes no outcome of the call, thus it reaches the log
-                // alone. An absent result means that the work threw, and a throw is a failed derivation.
-                await deliverNotice(logger.with({ threadId, analysisId }), "RunAuthorizer.revoke", runAuthorizer.revoke(authorization, result?.outcome === "derived" ? "derive-table-completed" : "derive-table-failed"));
             }
+            const result = await derive({
+                sandboxClient,
+                session: passSpawnSession(ctx.session, {
+                    analysisId,
+                    runId: DERIVE_RUN_LITERAL,
+                    stepId: DERIVE_STEP_LITERAL,
+                    agentId: DERIVE_AGENT_ID,
+                }),
+                derivations: deps.derivations,
+                root,
+                threadId,
+                analysisId,
+                toolCallId: ctx.invocationId,
+                script: input.script,
+                sources,
+                writableTail,
+                outputPath,
+                outputName: input.output,
+                logger,
+            });
+            // The record of the derivation lands before this point, thus the event states a table that the
+            // session already holds as evidence. Each other arm derived nothing.
+            observeDerived(analysisId, threadId, result);
+            return ok(result);
         },
     });
 }
@@ -288,62 +296,51 @@ export function createDeriveTableTool(deps) {
  *
  * The order is the order of the evidence. The script writes into the write mount, the host classifies the
  * file, the hash comes off the disk, and the record lands last. Thus the recorded hash is the hash of the
- * file that a verifier reads.
+ * file that a verifier reads. The container goes away after the record.
  *
  * The classification is the guard of the read. A script can leave a symbolic link at the output name, and a
  * link that resolves outside the tree would otherwise carry a host file into the evidence of the session.
- *
- * The output path clears before the exec. The host owns the `derived/` directory, and a failed attempt can
- * leave a file at the name that this attempt declares. Without the clearance a script that writes nothing
- * would adopt those bytes as its own table, and the record would chain a script to a file that it never
- * wrote. A clearance fault refuses the derivation, because the same doubt stands.
  */
 async function derive(args) {
-    const executionId = generateExecutionId(DERIVE_AGENT_ID);
     const absolute = join(args.root, args.outputPath);
     // The container sees the tree at its own mount point, thus each path that the script reads maps through
-    // the one host-to-container mapper and never through a formula here.
-    const workingDir = toSandboxPath(args.root, args.analysisId, join(args.root, args.writableTail));
-    // `unlink` removes a symbolic link as the link, and never the file that it names. An absent path is the
-    // normal condition, thus it is not a fault.
-    try {
-        await unlink(absolute);
-    }
-    catch (cause) {
-        if (cause.code !== "ENOENT") {
-            args.logger.error("the output path did not clear before the derivation", { threadId: args.threadId, ...defaultErrorFields(cause) });
-            return { outcome: "exec-failed", detail: `${args.outputName} already holds a file that did not clear, thus this derivation takes a new name` };
-        }
-    }
-    // The path mapper refuses a stored path that escapes the root, with a throw. It runs before the try,
-    // thus that refusal stays a throw and it never reads as a fault of the container.
-    const execInput = {
-        analysisId: args.analysisId,
-        runSession: args.runSession,
-        executionId,
+    // the one host-to-container mapper and never through a formula here. The mapper refuses a stored path
+    // that escapes the root with a throw. It runs before the try, thus that refusal stays a throw and it never
+    // reads as a fault of the container.
+    const request = buildDerivationExec({
         script: args.script,
-        writableTail: args.writableTail,
-        workingDir,
+        workingDir: toSandboxPath(args.root, args.analysisId, join(args.root, args.writableTail)),
         inputs: args.sources.map((source) => ({ path: toSandboxPath(args.root, args.analysisId, join(args.root, source.path)), hash: source.hash })),
         output: toSandboxPath(args.root, args.analysisId, absolute),
-    };
+    });
     let ran;
     try {
-        ran = await args.runDerivation(execInput);
+        ran = await withStepSandbox(args.sandboxClient, { session: args.session, spec: { resources: DERIVATION_RESOURCES, writableTail: args.writableTail } }, args.logger, async (exec) => {
+            const failure = describeExecFailure(await exec(request, DERIVATION_DEADLINE_MS));
+            if (failure !== undefined) {
+                return { outcome: "exec-failed", detail: failure };
+            }
+            return recordDerivedTable({ ...args, absolute });
+        });
     }
     catch (cause) {
+        if (isWorkflowCancellation(cause))
+            throw cause;
         args.logger.error("the derivation exec did not complete", { threadId: args.threadId, ...defaultErrorFields(cause) });
         return { outcome: "exec-failed", detail: "the derivation exec did not complete" };
     }
     if (ran.isErr()) {
-        return { outcome: "suspended", reason: ran.error.reason, detail: `the analysis is suspended (${ran.error.reason}), thus the derivation did not run` };
-    }
-    const executed = ran.value;
-    const failure = describeExecFailure(executed);
-    if (failure !== undefined) {
-        return { outcome: "exec-failed", detail: failure };
+        return {
+            outcome: "suspended",
+            reason: ran.error.reason,
+            detail: `the host refused the sandbox (${ran.error.reason}), thus the derivation did not run`,
+        };
     }
-    const verdict = await classifyWithinRoot(args.root, absolute).catch((cause) => {
+    return ran.value;
+}
+/** Classify, hash, and record the table that a green script wrote. */
+async function recordDerivedTable(args) {
+    const verdict = await classifyWithinRoot(args.root, args.absolute).catch((cause) => {
         args.logger.error("the derived table did not classify", { threadId: args.threadId, ...defaultErrorFields(cause) });
         return "escaped";
     });
@@ -361,7 +358,7 @@ async function derive(args) {
     }
     let outputHash;
     try {
-        outputHash = await computeSha256File(absolute);
+        outputHash = await computeSha256File(args.absolute);
     }
     catch (cause) {
         args.logger.error("the derived table did not hash", { threadId: args.threadId, ...defaultErrorFields(cause) });
@@ -373,6 +370,7 @@ async function derive(args) {
         sources: [...args.sources],
         scriptHash: computeSha256(Buffer.from(args.script, "utf8")),
         script: args.script,
+        toolCallId: args.toolCallId,
     };
     const appended = await args.derivations.appendDerivation(args.threadId, record);
     if (appended.isErr()) {
@@ -394,14 +392,14 @@ async function derive(args) {
     }
     // The columns describe the derived table the same way as the listing describes a pinned one. A file that
     // gives no header gives no columns, and absence is a normal condition here.
-    const columns = await readColumnsQuietly(args.outputPath, absolute, args.logger);
+    const columns = await readColumnsQuietly(args.outputPath, args.absolute, args.logger);
     return {
         outcome: "derived",
         path: args.outputPath,
         hash: outputHash,
         scriptHash: record.scriptHash,
         sources: [...args.sources],
-        ...(columns === undefined ? {} : { columns }),
+        columns,
     };
 }
 /**

package/dist/tools/report-session/examine-page.d.ts

@@ -56,12 +56,12 @@ import { type ChromeConfig } from "../../lib/chrome.js";
 import type { GateFailure } from "../../lib/hooks.js";
 import { type AcquireEyes } from "../../lib/eyes.js";
 import { type Logger } from "../../lib/logger.js";
-import { type CaptureCoverage, type CapturePage, type FailedRequest, type PageCapture } from "../../lib/page-capture.js";
+import { type CaptureCoverage, type CapturePage } from "../../lib/page-capture.js";
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
 import { type Tool } from "../define-tool.js";
 import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
 import { type ConsoleErrorEntry, type FailedRequestEntry } from "./page-faults.js";
-export type { CaptureCoverage, CapturePage, FailedRequest, PageCapture };
+export type { CaptureCoverage, CapturePage, FailedRequest, PageCapture } from "../../lib/page-capture.js";
 /**
  * The URL formation of one look. It maps the page of the thread onto the URL that the browser opens.
  * A composition whose browser cannot reach the workspace tree binds a resolver that names a served URL.
@@ -80,11 +80,11 @@ declare const examinePageInput: z.ZodObject<{
 }, z.core.$strip>;
 export type ExaminePageInput = z.infer<typeof examinePageInput>;
 /** The document range of one slice of a tiled look, in the order that the pictures ride. */
-export interface ExaminedTile {
+export type ExaminedTile = {
     index: number;
     fromY: number;
     toY: number;
-}
+};
 /**
  * The typed outcome of the eyes tool. Each arm is ok-channel data, thus the tool never throws for a
  * degraded condition. `examined` carries the coverage of the look, the digest of the console errors and the
@@ -137,7 +137,7 @@ export type ExaminePageResult = {
  * tree names a served URL instead. `capture` is optional and it replaces the whole transport, thus a test
  * injects a seam that reads no browser.
  */
-export interface ExaminePageToolDeps {
+export type ExaminePageToolDeps = {
     readonly gateway: ReportSessionStateGateway;
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     readonly chrome: ChromeConfig;
@@ -154,7 +154,7 @@ export interface ExaminePageToolDeps {
         readonly acquireMs?: number;
         readonly releaseMs?: number;
     };
-}
+};
 /**
  * Make the eyes tool over the session-state gateway, the workspace-root seam, and the eyes of the composition.
  *

package/dist/tools/report-session/examine-page.js

@@ -49,12 +49,16 @@
  * deadline. A realization that hangs while it starts a browser would otherwise hold the whole agent turn,
  * and no outcome would ever arrive.
  */
+import { errorMessageOf } from "../../lib/thrown.js";
+import { textOf } from "../../lib/unknown-text.js";
 import { err, ok } from "neverthrow";
 import { access } from "node:fs/promises";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { setTimeout as sleep } from "node:timers/promises";
 import { z } from "zod";
 import { hasBrowserUrl } from "../../lib/chrome.js";
+import { errnoOf } from "../../lib/fs-result.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
 import { createStaticEyes } from "../../lib/eyes.js";
 import { defaultErrorFields } from "../../lib/logger.js";
@@ -114,7 +118,7 @@ const ACQUIRE_DEADLINE_MS = 60_000;
  * provisions.
  */
 const RELEASE_DEADLINE_MS = 10_000;
-/** The win of the timer arm. A symbol cannot collide with a value that the operation gives. */
+/** The win of the expiry arm. A symbol cannot collide with a value that the operation gives. */
 const EXPIRED = Symbol("expired");
 /**
  * Run one operation against a deadline, and give the value, the cause, or the expiry.
@@ -122,19 +126,17 @@ const EXPIRED = Symbol("expired");
  * The eyes seam takes no abort signal, thus a race is the whole bound. The loser of the race stays in
  * flight, and the caller of an expired operation owns whatever arrives late.
  *
- * Each path clears the timer. `sleep` of `async-utils.ts` holds a timer that nothing can clear. Thus an
- * operation that wins its race would still keep the process alive for the rest of the budget.
+ * The abort after the race clears the wait of a settled operation, so no armed timer outlives the budget.
  */
 async function withDeadline(work, ms) {
-    let timer;
     // The settled arm never rejects. Thus a fault that arrives after the expiry stays contained here, and it
     // never reaches the process as an unhandled rejection.
     const settled = work.then((value) => ok(value), (cause) => err({ kind: "threw", cause }));
-    const expiry = new Promise((resolve) => {
-        timer = setTimeout(() => resolve(EXPIRED), ms);
-    });
+    const gate = new AbortController();
+    // The rejection arm answers the abort of a settled race, and its value is never read.
+    const expiry = sleep(ms, undefined, { signal: gate.signal }).then(() => EXPIRED, () => EXPIRED);
     const winner = await Promise.race([settled, expiry]);
-    clearTimeout(timer);
+    gate.abort();
     return winner === EXPIRED ? err({ kind: "expired" }) : winner;
 }
 /** The cause of one such fault. An expiry names its budget, thus the detail of the outcome names it too. */
@@ -153,6 +155,7 @@ function startSeamCall(call) {
         return call();
     }
     catch (cause) {
+        // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- the rejection reason is the thrown value itself; the awaiter reads its identity, and a wrapper would erase it.
         return Promise.reject(cause);
     }
 }
@@ -251,7 +254,6 @@ export function createExaminePageTool(deps) {
             "The outcomes no-page and missed-stamp mean that no preview rendered the current page: run preview_report, then look again. " +
             "The outcome no-browser means that this host gives no browser, and a repeat gives the same outcome.",
         inputSchema: examinePageInput,
-        executionMode: "inline",
         describeCall: (input) => {
             const blockId = input.blockId ?? undefined;
             return blockId === undefined ? "look at the page" : `look at ${blockId}`;
@@ -288,7 +290,7 @@ export function createExaminePageTool(deps) {
                 await access(pagePath);
             }
             catch (cause) {
-                if (cause.code === "ENOENT") {
+                if (errnoOf(cause) === "ENOENT") {
                     // No preview wrote the page yet. The agent runs the preview first.
                     return ok({ outcome: "no-page" });
                 }
@@ -330,7 +332,7 @@ export function createExaminePageTool(deps) {
             if (looked.isErr()) {
                 const { stage, cause } = looked.error;
                 logger.warn(LOOK_FAULT_MESSAGE[stage], { threadId, analysisId, ...defaultErrorFields(cause) });
-                return ok({ outcome: "capture-failed", detail: cause instanceof Error ? cause.message : String(cause) });
+                return ok({ outcome: "capture-failed", detail: errorMessageOf(cause) ?? textOf(cause) });
             }
             const captured = looked.value;
             if (blockId !== undefined && captured.coverage.kind === "no-block") {
@@ -360,7 +362,7 @@ export function createExaminePageTool(deps) {
             return ok(withToolResultImages({
                 outcome: "examined",
                 coverage: captured.coverage,
-                ...(tiles.length === 0 ? {} : { tiles }),
+                tiles: tiles.length === 0 ? undefined : tiles,
                 ...digestPageFaults(captured.consoleErrors, captured.failedRequests),
                 pagePath: relativePagePath,
             }, captured.screenshots.map((shot) => ({ base64: shot.base64, mediaType: SCREENSHOT_MEDIA_TYPE }))));

package/dist/tools/report-session/list-artifacts.d.ts

@@ -38,12 +38,12 @@ export type ListPinnedArtifactsInput = z.infer<typeof listPinnedArtifactsInput>;
  * only for a header that the read recovered, thus their absence says nothing about the content of the file.
  * The listing gives `columnCount`, and a call with a path gives `columns` as well.
  */
-export interface PinnedArtifact {
+export type PinnedArtifact = {
     path: string;
     fileType?: string;
     columnCount?: number;
     columns?: string[];
-}
+};
 /**
  * One pinned citation of the listing: the key, and the short citation of its pinned record.
  *
@@ -51,10 +51,10 @@ export interface PinnedArtifact {
  * the pin recorded no citation for carries none, because absence is a normal condition. The description of
  * the record stays out, because the listing is an orientation surface.
  */
-export interface PinnedCitation {
+export type PinnedCitation = {
     key: string;
     citation?: string;
-}
+};
 /**
  * The typed outcome of the listing tool. Each arm is ok-channel data, thus the tool never throws for one
  * of them.
@@ -87,11 +87,11 @@ export type ListPinnedArtifactsResult = {
  * `resolveWorkspaceRoot` maps the analysis of the call onto its workspace root, thus one singleton tool
  * serves every analysis and it resolves the root per call from the scope.
  */
-export interface ListPinnedArtifactsToolDeps {
+export type ListPinnedArtifactsToolDeps = {
     readonly gateway: ReportSessionStateGateway;
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     readonly logger?: Logger;
-}
+};
 /**
  * The header columns of a file on disk, or `undefined` when the file gives none.
  *

package/dist/tools/report-session/list-artifacts.js

@@ -27,9 +27,10 @@ import { extname } from "node:path";
 import { z } from "zod";
 import { resolveWorkspacePath } from "../../workspace/paths.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
+import { splitLines } from "../../lib/text.js";
 import { tryFs } from "../../lib/fs-result.js";
 import { defaultErrorFields } from "../../lib/logger.js";
-import { citationRecordOf, fileTypeHoldsNoCell } from "../../report-model/reference-resolver.js";
+import { citationRecordOf, fileTypeHoldsNoCell, snapshotEntry } from "../../report-model/reference-resolver.js";
 import { defineTool } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
 /** No path lists the pinned set. A path gives the header columns of that one pinned artifact. */
@@ -87,7 +88,7 @@ async function readHeaderLine(absolute) {
     if (head === undefined) {
         return undefined;
     }
-    const line = head.text.split(/\r?\n/, 1)[0];
+    const [line = ""] = splitLines(head.text).slice(0, 1);
     if (line.length === 0) {
         return undefined;
     }
@@ -147,7 +148,6 @@ export function createListPinnedArtifactsTool(deps) {
             "Read the listing to orient before you bind a block. Read the columns of one artifact to choose the column that a locator names. " +
             "A reference names the path alone: the session stamps the hash from this evidence, thus the tool gives no hash.",
         inputSchema: listPinnedArtifactsInput,
-        executionMode: "inline",
         describeCall: (input) => input.path ?? "the pinned set",
         // The size of the listing is what a watcher reads, and the cap makes that size differ from the
         // pinned set. Thus a truncated listing names the total beside the count, and a whole listing names
@@ -180,8 +180,8 @@ export function createListPinnedArtifactsTool(deps) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });
             }
             const describe = async (path) => {
-                const fileType = state.snapshot.artifacts[path].fileType;
-                const artifact = { path, ...(typeof fileType === "string" ? { fileType } : {}) };
+                const fileType = snapshotEntry(state.snapshot, path)?.fileType ?? undefined;
+                const artifact = { path, fileType };
                 if (root === undefined || fileTypeHoldsNoCell(fileType)) {
                     return { artifact };
                 }

package/dist/tools/report-session/page-faults.d.ts

@@ -4,25 +4,25 @@
  */
 import type { FailedRequest } from "../../lib/page-capture.js";
 /** One distinct console error of a look, and how many times the page logged it. */
-export interface ConsoleErrorEntry {
+export type ConsoleErrorEntry = {
     text: string;
     count: number;
-}
+};
 /** One distinct failed request of a look, and how many times the page made it. */
-export interface FailedRequestEntry {
+export type FailedRequestEntry = {
     url: string;
     reason: string;
     count: number;
-}
+};
 /** The digest of one look. `omittedFaults` counts the distinct entries that the cap left out, thus a cut is never silent. */
-export interface PageFaults {
+export type PageFaults = {
     consoleErrors: ConsoleErrorEntry[];
     failedRequests: FailedRequestEntry[];
     omittedFaults?: {
         consoleErrors: number;
         failedRequests: number;
     };
-}
+};
 /** Shorten one fault text: the inline data becomes placeholders, and the text stops at the cap. */
 export declare function shortenFaultText(text: string): string;
 /** Digest the raw faults of one capture into the short lists that the agent reads. */