@inflexa-ai/harness 0.42.2 → 0.43.1

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

@@ -4,11 +4,12 @@
  *
  * A thin adapter over the `WorkspaceMutator` seam (see the harness-durable-runtime / harness-workspace-tools specs): the
  * mutator owns resolve + confine + hardened host write + provenance. This tool
- * only declares the input schema and forwards. `edit_file` rides the same seam.
+ * declares the input schema, forwards the write, and carries the record of the
+ * write to the fold. `edit_file` rides the same seam.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
-import { defineTool } from "../define-tool.js";
+import { defineTool, withToolCallRecord } from "../define-tool.js";
 const WriteFileInputSchema = z.object({
     path: z
         .string()
@@ -21,9 +22,6 @@ const WriteFileInputSchema = z.object({
 export function createWriteFileTool(deps) {
     return defineTool({
         id: "write_file",
-        // The mutator wraps the disk mutation in `ctx.runStep` itself, so the
-        // body runs unwrapped in the workflow body (see the harness-tools spec).
-        executionMode: "workflow",
         description: "Write a UTF-8 text file in your working directory. Relative paths " +
             "resolve against it. The write replaces an existing file whole, and it makes " +
             "missing parent directories. On success it returns `status: ok`, the absolute " +
@@ -34,13 +32,19 @@ export function createWriteFileTool(deps) {
         // The path only. `content` is a whole file and must never ride a display
         // channel, which the emit-site length cap enforces regardless.
         describeCall: ({ path }) => path,
-        execute: async ({ path, content }, ctx) => ok(await deps.mutator.writeFile({
-            path,
-            content,
-            toolName: "write_file",
-            invocationId: ctx.invocationId,
-            runStep: ctx.runStep,
-            session: ctx.session,
-        })),
+        execute: async ({ path, content }, ctx) => {
+            const write = await deps.mutator.writeFile({
+                path,
+                content,
+                toolName: "write_file",
+                invocationId: ctx.invocationId,
+                session: ctx.session,
+            });
+            if (write.status !== "ok")
+                return ok(write);
+            const { record, ...result } = write;
+            return ok(withToolCallRecord(result, record));
+        },
+        foldCallRecord: (record) => deps.mutator.recordWrite(record),
     });
 }

package/dist/workflows/sandbox-step.d.ts

@@ -91,8 +91,7 @@ export interface SandboxStepInput {
     readonly resources: ResourceSpec;
     /**
      * Per-step execution budget in seconds. The body translates this into the
-     * absolute unix-ms deadline that `awaitExec` honours as its durable
-     * backstop. Comes from the plan's `step.timeout` (defaulted on the parent
+     * absolute unix-ms deadline that each exec of the step honours. Comes from the plan's `step.timeout` (defaulted on the parent
      * side); falls back to `DEFAULT_STEP_TIMEOUT_SECONDS` when unset so a
      * client that omits the field still gets a non-pathological ceiling.
      */
@@ -184,17 +183,13 @@ export interface PostStepArtifacts {
 /**
  * Per-step coordinates the workflow body computes once and threads to the
  * deps factory. The parent supplies the durable inputs; the factory
- * supplies the live sandbox ref, the per-call function-id minter, and the
- * deadline.
+ * supplies the live sandbox ref and the deadline.
  */
 export interface SandboxAgentBuildContext {
     readonly input: SandboxStepInput;
     readonly session: RunSession;
     readonly sandbox: SandboxRef;
-    /** Workflow-id used to scope sandbox callbacks + workspace mutate provenance. */
-    readonly workflowId: string;
     readonly stepWritePrefix: string;
-    readonly nextFunctionId: () => string;
     readonly deadlineMs: () => number;
     /**
      * Step-scoped lineage collector. The body owns one per step and threads
@@ -302,10 +297,11 @@ export interface PostStepContext {
 export declare function readStepFileMetadata(checkpoint: StepFileMetadata | readonly FileMetadataEntry[]): StepFileMetadata;
 /**
  * Build the step's lineage collector from its durable input. The agent loop
- * feeds each exec's provenance frame into it; post-step registration reads the
- * resulting input/script edges. Reconstructed deterministically on replay — the
- * frames it consumes are cached recv outputs and the command strings are cached
- * LLM tool-use (see the harness-thread-store and harness-durable-runtime specs).
+ * feeds each exec's provenance frame and each file-tool write into it;
+ * post-step registration reads the resulting input/script edges.
+ * Reconstructed deterministically on replay — the loop folds the call record
+ * of each cached tool call into it again, in call order (see the
+ * harness-durable-runtime spec).
  *
  * Split out of the body, and taking only the fields it reads, so the seeding is
  * exercisable without a live workflow: `dependsOn` is what makes a same-run edge

package/dist/workflows/sandbox-step.js

@@ -69,10 +69,6 @@ export const CAPPED_OUT_EMPTY_REASON = "The step hit its iteration cap with no o
  */
 export const CHILD_SUSPENDED_TOPIC = "child-suspended";
 // ── Helpers ───────────────────────────────────────────────────────────
-function nextFunctionIdFactory() {
-    let n = 0;
-    return () => `fn-${(n++).toString(36)}`;
-}
 const NO_STEP_FILE_METADATA = { entries: [], messages: [] };
 /** Normalizes a pre-`messages` checkpoint (a bare entries array) for replay. */
 export function readStepFileMetadata(checkpoint) {
@@ -95,10 +91,11 @@ function userFacingStepFailure(errorClass) {
 }
 /**
  * Build the step's lineage collector from its durable input. The agent loop
- * feeds each exec's provenance frame into it; post-step registration reads the
- * resulting input/script edges. Reconstructed deterministically on replay — the
- * frames it consumes are cached recv outputs and the command strings are cached
- * LLM tool-use (see the harness-thread-store and harness-durable-runtime specs).
+ * feeds each exec's provenance frame and each file-tool write into it;
+ * post-step registration reads the resulting input/script edges.
+ * Reconstructed deterministically on replay — the loop folds the call record
+ * of each cached tool call into it again, in call order (see the
+ * harness-durable-runtime spec).
  *
  * Split out of the body, and taking only the fields it reads, so the seeding is
  * exercisable without a live workflow: `dependsOn` is what makes a same-run edge
@@ -181,15 +178,15 @@ export async function runSandboxStepBody(input, deps) {
     const session = forSubAgent(input.runSession, input.agentId);
     const writePrefix = deps.resolveWritePrefix(input);
     const lineageCollector = createLineageCollector(input);
-    // (2a) sandbox.mint — checkpoint the machine's identity (name + HMAC secret)
+    // (2a) sandbox.mint — checkpoint the machine's identity (its name)
     // BEFORE it is spawned (see the harness-sandbox-exec spec). Durable-before-create is what makes (2b)
     // idempotent: a crash between spawn and the spawn checkpoint re-runs (2b)
     // with the same identity, which adopts the already-created machine instead
     // of leaking a second one.
     const identity = await DBOS.runStep(() => Promise.resolve(mintSandboxIdentity(input.runId)), { name: "sandbox.mint" });
     // (2b) sandbox.create — spawn (or adopt) the machine under the minted
-    // identity. The handle (secret included) is cached so recovery picks the
-    // same machine back up without re-provisioning.
+    // identity. The handle is cached so recovery picks the same machine back up
+    // without re-provisioning.
     const sandboxSpec = {
         childWorkflowId,
         image: input.image,
@@ -215,9 +212,8 @@ export async function runSandboxStepBody(input, deps) {
     }, { name: "sandbox.recheck-alive" });
     // (3) runAgent — the harness loop with durableStep.
     // The step deadline is captured ONCE at step start from the checkpointed
-    // clock so it reproduces on replay — the `awaitExec` recv loop gates on this
-    // absolute deadline, so a raw `Date.now()` here would shift the recorded
-    // `DBOS.recv` sequence on recovery (see the harness-durable-runtime spec). `deadlineMs` is a getter so
+    // clock so it reproduces on replay — a raw `Date.now()` here would grow the
+    // deadline on each recovery (see the harness-durable-runtime spec). `deadlineMs` is a getter so
     // deps read the absolute ms without holding a captured value; returning a
     // fresh `now + timeout` per call would make a step with N tool calls runnable
     // for up to N × `timeoutSeconds`.
@@ -228,9 +224,7 @@ export async function runSandboxStepBody(input, deps) {
         input,
         session,
         sandbox,
-        workflowId: childWorkflowId,
         stepWritePrefix: writePrefix,
-        nextFunctionId: nextFunctionIdFactory(),
         deadlineMs: () => stepDeadlineMs,
         lineageCollector,
         blockerHolder,
@@ -251,15 +245,17 @@ export async function runSandboxStepBody(input, deps) {
     // `tool-finished`) and model-output deltas are wrapped under the
     // `data-loop-event` envelope so the SSE consumer can route them.
     //
-    // Every emit is `await`ed in body order (the loop awaits its own emits, and
-    // `awaitExec` awaits its sandbox-event emits), so each body-path
-    // `DBOS.writeStream` lands at a deterministic function-ID on replay
-    // (see the harness-durable-runtime spec) — no fire-and-forget tail racing the next real op for the
-    // counter. `safeEmit` swallows a stream-write failure: a dropped UI frame
-    // is non-fatal and must not fail the step.
+    // Every emit is `await`ed in order (the loop awaits its own emits, and the
+    // exec awaits its sandbox-event emits). A body-path `DBOS.writeStream` lands
+    // at a deterministic function-ID on replay (see the harness-durable-runtime
+    // spec) — no fire-and-forget tail racing the next real op for the counter.
+    // A sandbox event arrives from inside the step of its tool call; a write from
+    // a step takes no function-ID, and a recovered step writes its events again.
+    // `safeEmit` swallows a stream-write failure: a dropped UI frame is
+    // non-fatal and must not fail the step.
     // Pattern A (fan-in at route): write to the CHILD's own `"events"` stream.
-    // `DBOS.writeStream` is body-only, so cross-workflow writes aren't supported;
-    // the SSE route reads the parent's stream plus every active child's, addressed
+    // `DBOS.writeStream` writes only to the stream of its own workflow, so the
+    // SSE route reads the parent's stream plus every active child's, addressed
     // by `cortex_step_executions.child_workflow_id`.
     const emitToParentStream = (part) => DBOS.writeStream("events", part);
     const safeEmit = async (part) => {
@@ -328,9 +324,10 @@ export async function runSandboxStepBody(input, deps) {
     // of the step) and emits the FULL tree under a stable per-step reconciling
     // id — the terminal `walkArtifacts` tree reconciles onto the same id at step
     // end. Full-tree + reconciling means an observer reconnecting from offset 0
-    // still converges (raw deltas alone would not). REPLAY: the fold is a 1:1
-    // pure function of the checkpointed `awaitExec` recv sequence — do NOT add a
-    // timer/debounce here, that would re-break the harness-durable-runtime spec.
+    // still converges (raw deltas alone would not). The fold is live view only:
+    // a replayed tool call returns its cached result and folds no delta, thus
+    // after a recovery the live tree holds the deltas of the later execs until
+    // the terminal tree reconciles it.
     const treeFileId = stepPartId("step-file-tree", input.runId, input.stepId);
     const treeFiles = new Set();
     const emitFileTree = () => safeEmit({

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.42.2",
+    "version": "0.43.1",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -35,8 +35,10 @@
     "scripts": {
         "build": "tsc -p tsconfig.json && node scripts/copy-assets.mjs",
         "design:fixture": "bun scripts/render-fixture.ts",
+        "design:gallery": "bun scripts/render-gallery.ts",
         "format": "prettier --write src/",
         "format:file": "prettier --write",
+        "gallery:data": "bash scripts/gallery-data.sh",
         "lint": "eslint .",
         "lint:python": "ruff check src/input-scan/decoder && ruff format --check src/input-scan/decoder",
         "prepare": "tsc -p tsconfig.json && node scripts/copy-assets.mjs",
@@ -68,6 +70,8 @@
         "@opentelemetry/sdk-trace-base": "^2.9.0",
         "@opentelemetry/sdk-trace-node": "^2.9.0",
         "@opentelemetry/semantic-conventions": "^1.43.0",
+        "@types/dockerode": "^3.3.47",
+        "@types/pg": "^8.20.0",
         "ag-grid-community": "36.1.0",
         "ai": "^7.0.113",
         "cheerio": "^1.2.0",
@@ -99,10 +103,8 @@
         "@ai-sdk/amazon-bedrock": "^5.0.93",
         "@eslint/js": "^10.0.1",
         "@types/bun": "latest",
-        "@types/dockerode": "^3.3.47",
         "@types/node": "^24.13.3",
         "@types/pdf-parse": "^1.1.5",
-        "@types/pg": "^8.20.0",
         "csstree-validator": "^4.0.1",
         "eslint": "^10.7.0",
         "eslint-plugin-neverthrow": "^1.1.4",

package/dist/sandbox/await-exec.d.ts

@@ -1,143 +0,0 @@
-/**
- * `awaitExec` — awaits a submitted exec's terminal result, forwarding progress
- * events, under one of two transports selected by `options.transport`:
- *
- *   - `poll` (default): {@link awaitExecPoll} loops durable pull steps against
- *     `GET /exec/{execId}?since={cursor}`. The sandbox initiates nothing; the
- *     host asks. Inherently restart-proof — a recovered workflow just resumes
- *     polling from its current identity — so the recovery wedge (#41) does not
- *     apply. A machine that dies mid-exec fast-fails in-loop: sustained
- *     `unavailable` polls escalate to a backend-inspect probe (`liveness.ts`)
- *     and an observably dead machine returns the synthetic-failure result
- *     instead of waiting out the deadline.
- *   - `callback`: {@link awaitExecCallback} is the recv loop below, with the
- *     pull as its recovery backstop.
- *
- * Both run in the workflow body (NOT a step) — `DBOS.recv`, `DBOS.writeStream`,
- * and `DBOS.sleepms` are body-only — and both verify every result against the
- * per-sandbox HMAC, treating a bad/stale signature as a hard cancel.
- *
- * ## Callback mode: the recv loop
- *
- * On each received envelope:
- *
- *   1. If it carries `signature: null` and the payload is a
- *      `synthetic-failure` done-marker, accept it — the watchdog is an
- *      in-process trusted sender. Any other null-signature message
- *      hard-cancels.
- *   2. Otherwise HMAC-verify against the per-sandbox `callbackSecret`.
- *      A bad or stale signature throws `HardCancelError`, which DBOS
- *      treats as a fatal workflow error (no retry).
- *   3. If the verified payload is a done-marker, return its `result`.
- *   4. Otherwise forward the payload via `emit` and continue.
- *
- * `deadline` is an absolute unix-ms timestamp — the durable backstop
- * (typically `step.timeout`). `T` is liveness-agnostic recv pacing: we
- * use `min(5s, remaining)` so the loop returns often enough to honour
- * the deadline.
- *
- * ## Recv is not the only way home
- *
- * The completion callback is a *push* to an address baked into the container at
- * creation. A host that dies mid-exec comes back with a different ingress port,
- * so the push can never land — the sandbox retries into a void while the
- * recovered recv waits for a message that will never arrive. That is the
- * recovery wedge (#41), and it is silent: a `running` row that never advances.
- *
- * So whenever the topic falls quiet, this loop stops waiting and *asks*:
- * `GET /exec/{execId}` on the sandbox itself returns the terminal result,
- * signed fresh at request time. The bytes are the ones the callback would have
- * carried, so the provenance frame survives the recovery path intact and one
- * verification path serves both. Push remains the fast path; pull is what makes
- * the protocol durable rather than merely optimistic.
- *
- * The pull is a DBOS step, not a bare `fetch`: a body-level call whose result
- * varied between replays would desynchronise the recorded function-ID sequence.
- */
-import { type ExecEmit, type ExecResult, type SandboxLiveness, type SandboxRef, type SandboxTransport } from "./types.js";
-export declare class HardCancelError extends Error {
-    readonly execId: string;
-    readonly reason: "bad-signature" | "stale-timestamp" | "missing" | "synthetic-without-marker";
-    constructor(execId: string, reason: "bad-signature" | "stale-timestamp" | "missing" | "synthetic-without-marker", detail?: string);
-}
-export declare class ExecTimeoutError extends Error {
-    readonly execId: string;
-    constructor(execId: string);
-}
-/**
- * Dependency seams of the await loops — every member is an injectable effect
- * (clock, recv, fetch, durable step, durable sleep, warn sink) plus the
- * transport selector. Tuning values (freshness window, pull threshold, poll
- * cadence) are module constants, not options.
- */
-export interface AwaitExecOptions {
-    /**
-     * Clock source for the deadline check and HMAC freshness. Defaults to the
-     * checkpointed `DBOS.now()` so the loop's recv count is replay-stable (a raw
-     * `Date.now()` here drifts the recorded `DBOS.recv` function-ID sequence on
-     * recovery — see the harness-durable-runtime spec).
-     */
-    now?: () => number | Promise<number>;
-    /** Replaces `DBOS.recv` (callback mode). */
-    recv?: <T>(topic: string, timeoutSec: number) => Promise<T | null>;
-    /** Defaults to `globalThis.fetch`. */
-    fetch?: typeof fetch;
-    /** Defaults to `DBOS.runStep`. */
-    runStep?: <T>(fn: () => Promise<T>, config: {
-        name: string;
-    }) => Promise<T>;
-    /**
-     * Result transport. `poll` (default) runs the durable poll loop; `callback`
-     * runs the `DBOS.recv` loop with the pull as its recovery backstop. The
-     * composition root passes the same value it hands the container.
-     */
-    transport?: SandboxTransport;
-    /** Replaces the durable inter-poll sleep. Defaults to `DBOS.sleepms`. */
-    sleep?: (ms: number) => Promise<void>;
-    /**
-     * Sink for advisory warnings (poll-mode progress-event loss). Defaults to
-     * `DBOS.logger.warn`. Advisory only: the terminal result — not the event
-     * stream — is the authoritative outcome.
-     */
-    warn?: (message: string) => void;
-    /**
-     * Backend inspect for the poll loop's liveness escalation (`liveness.ts`).
-     * Wired by `createSandboxClient` from its backend ops; when absent the
-     * loop skips escalation and stays purely deadline-bounded. Throws on
-     * transient backend API errors — the escalation treats a throw as an
-     * inconclusive probe, never a failed exec.
-     */
-    isAlive?: (ref: SandboxRef) => Promise<SandboxLiveness>;
-}
-/**
- * Await a submitted exec's terminal result. Dispatches on transport — `poll`
- * (default) or `callback`. Both verify every result against the per-sandbox
- * HMAC and are bounded by `deadlineMs`.
- */
-export declare function awaitExec(ref: SandboxRef, execId: string, emit: ExecEmit, deadlineMs: number, options?: AwaitExecOptions): Promise<ExecResult>;
-/**
- * Body of the recv loop (callback transport). Hoisted so it's testable without
- * spinning up DBOS — `recv` is injectable and `now` is overridable.
- */
-export declare function awaitExecCallback(ref: SandboxRef, execId: string, emit: ExecEmit, deadlineMs: number, options?: AwaitExecOptions): Promise<ExecResult>;
-/**
- * Body of the poll loop (poll transport). No `DBOS.recv`, no per-exec topic, no
- * callback handler: a sequence of durable pull steps named
- * `sandbox.poll-exec-result.${execId}.${n}`, each fetching the signed
- * `{ status, events, cursor, result? }`, verifying it exactly as a pushed
- * completion is verified, forwarding new events via `emit`, advancing the
- * cursor, and returning `result` once terminal. `sleep`, `now`, `fetch`,
- * `runStep`, and `isAlive` are injectable so the loop is testable without DBOS.
- *
- * Liveness: when the `isAlive` seam is wired (the client always wires it),
- * consecutive `unavailable` polls past the module threshold escalate to a
- * durable probe step `sandbox.probe-liveness.${execId}.${k}`; a dead verdict
- * returns the synthetic-failure result in-loop — the poll-mode analogue of the
- * watchdog's synthetic-complete, minus the topic and the race gate, since the
- * verdict is produced and consumed by the same workflow in sequence.
- *
- * The `cursor`, `pollAttempt`, and `probeAttempt` counters are pure functions
- * of the cached step sequence, so a replay issues the same polls and probes in
- * the same order and the DBOS function-ID sequence stays stable.
- */
-export declare function awaitExecPoll(ref: SandboxRef, execId: string, emit: ExecEmit, deadlineMs: number, options?: AwaitExecOptions): Promise<ExecResult>;