@inflexa-ai/harness 0.46.0 → 0.47.0

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

@@ -6,7 +6,8 @@
  * replays from the cache instead of re-issuing work):
  *
  *  1. `mark-running`        — update `cortex_step_executions` to running.
- *  2. `createSandbox`       — provision the sandbox; persist its handle.
+ *  2. the lease             — bind the lease of the step. The agent acquires
+ *                             its sandbox with `acquire_sandbox`.
  *  3. `runLoop`             — the harness agent loop. Every model call and
  *                             tool call inside is its own durable step.
  *  4. `generateFileMetadata`— the file-metadata follow-up request of the step agent.
@@ -16,15 +17,16 @@
  *  7. `syncArtifacts`       — register provenance + upload missing file_ids
  *                             via the managed root (scoped to this run+step).
  *  8. `vector-index`        — index file descriptions + summary into pgvector.
- *  9. `teardown`            — destroy the sandbox + clear sandbox_ref.
+ *  9. `sandbox.release`     — release the lease, which removes its machine.
  * 10. `mark-terminal`       — write the final status, emit `data-step-activity`
  *                             onto the parent's DBOS stream.
  *
- * The parent owns sibling lifecycle. This child owns its own teardown and its
- * own pause (work-pause spec): a failed model request of the agent loop with a
- * cause of a pause, or a refusal with the suspend flag of the label gate or the
- * register gate. The child waits in place, and the run row stays `running`. The
- * other steps go on, and each one pauses at its own failure.
+ * The parent owns sibling lifecycle. This child releases its own lease, and it
+ * owns its own pause (work-pause spec): a failed model request of the agent loop
+ * with a cause of a pause, or a refusal with the suspend flag of the register
+ * gate. The child waits in place, and the run row stays `running`. The other
+ * steps go on, and each one pauses at its own failure. A refused spawn pauses
+ * the lease workflow under the run, not this child.
  */
 import type { TokenUsageRollup } from "@inflexa-ai/harness/contracts/usage.js";
 import type { Querier } from "../state/db.js";
@@ -39,13 +41,11 @@ import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { FileMetadataEntry } from "../execution/artifact-metadata.js";
 import type { ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
 import type { StepSummary } from "../schemas/step-summary.js";
-import type { SandboxClient } from "../sandbox/client.js";
+import type { SandboxLeases, BoundLease } from "../sandbox/leases.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import type { ArtifactRegistry } from "../execution/artifact-registry.js";
 import { type StepFileMetadata } from "../execution/post-step-pipeline.js";
-import type { ResourceSpec } from "../config/resource-limits.js";
-import type { SandboxRef } from "../sandbox/types.js";
 import { ProvenanceCollector } from "../provenance/collector.js";
 import { type FileMetadataCell } from "../tools/sandbox/submit-file-metadata.js";
 import type { TemplateBinding } from "../tools/knowledge/template.js";
@@ -89,15 +89,6 @@ export type SandboxStepInput = {
     readonly image?: string;
     /** Per-step env overrides forwarded to sandbox-server. */
     readonly extraEnv?: Record<string, string>;
-    /** Planner-estimated CPU/memory/GPU request for this step's sandbox. */
-    readonly resources: ResourceSpec;
-    /**
-     * Per-step execution budget in seconds. The body translates this into the
-     * 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.
-     */
-    readonly timeoutSeconds?: number;
     /**
      * Durable `RunSession` derived by the parent via `forStep`. Carries the
      * run-authorization credential, identity, scope, and `runFrame = { runId, stepId }`.
@@ -106,11 +97,6 @@ export type SandboxStepInput = {
      */
     readonly runSession: SpawnSession;
 };
-/**
- * Fallback when the plan step omits `timeout`. Plans that need 3-hour runs
- * declare it explicitly.
- */
-export declare const DEFAULT_STEP_TIMEOUT_SECONDS = 3600;
 /**
  * Deterministic `blocked_reason` for a loop that spent every iteration and
  * persisted no output files (see the harness-sandbox-agents spec). Fixed prose,
@@ -170,15 +156,15 @@ export type 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 and the deadline.
+ * deps factory. The parent supplies the durable inputs; the body supplies the
+ * lease of the step.
  */
 export type SandboxAgentBuildContext = {
     readonly input: SandboxStepInput;
     readonly session: RunSession;
-    readonly sandbox: SandboxRef;
+    /** The lease of the step. The agent tools acquire, release, and run commands through it. */
+    readonly lease: BoundLease;
     readonly stepWritePrefix: string;
-    readonly deadlineMs: () => number;
     /**
      * Step-scoped lineage collector. The body owns one per step and threads
      * it both here (so `execute_command` feeds each exec's provenance frame)
@@ -227,7 +213,8 @@ export type SandboxStepDeps = {
     readonly provider: ChatProvider;
     /** Write-side embedder for the post-step vector index. */
     readonly embedding: EmbeddingProvider;
-    readonly sandboxClient: SandboxClient;
+    /** The sandbox module. The step binds its lease, and releases it at the end. */
+    readonly leases: SandboxLeases;
     /**
      * External artifact registration + sync seam. The harness's post-step pipeline
      * registers each step's outputs through it (filesystem index in the
@@ -277,8 +264,6 @@ export type PostStepContext = {
     readonly fileMetadata: FileMetadataCell;
     /** Absolute path to the step's writable artifact directory. */
     readonly writePrefix: string;
-    /** Sandbox handle id — informational only, used in log lines. */
-    readonly sandboxId: string;
     /** Same step-scoped collector the agent loop fed each exec frame into. */
     readonly lineageCollector: ProvenanceCollector;
 };

package/dist/workflows/sandbox-step.js

@@ -6,7 +6,8 @@
  * replays from the cache instead of re-issuing work):
  *
  *  1. `mark-running`        — update `cortex_step_executions` to running.
- *  2. `createSandbox`       — provision the sandbox; persist its handle.
+ *  2. the lease             — bind the lease of the step. The agent acquires
+ *                             its sandbox with `acquire_sandbox`.
  *  3. `runLoop`             — the harness agent loop. Every model call and
  *                             tool call inside is its own durable step.
  *  4. `generateFileMetadata`— the file-metadata follow-up request of the step agent.
@@ -16,15 +17,16 @@
  *  7. `syncArtifacts`       — register provenance + upload missing file_ids
  *                             via the managed root (scoped to this run+step).
  *  8. `vector-index`        — index file descriptions + summary into pgvector.
- *  9. `teardown`            — destroy the sandbox + clear sandbox_ref.
+ *  9. `sandbox.release`     — release the lease, which removes its machine.
  * 10. `mark-terminal`       — write the final status, emit `data-step-activity`
  *                             onto the parent's DBOS stream.
  *
- * The parent owns sibling lifecycle. This child owns its own teardown and its
- * own pause (work-pause spec): a failed model request of the agent loop with a
- * cause of a pause, or a refusal with the suspend flag of the label gate or the
- * register gate. The child waits in place, and the run row stays `running`. The
- * other steps go on, and each one pauses at its own failure.
+ * The parent owns sibling lifecycle. This child releases its own lease, and it
+ * owns its own pause (work-pause spec): a failed model request of the agent loop
+ * with a cause of a pause, or a refusal with the suspend flag of the register
+ * gate. The child waits in place, and the run row stays `running`. The other
+ * steps go on, and each one pauses at its own failure. A refused spawn pauses
+ * the lease workflow under the run, not this child.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { isWorkflowCancellation } from "../runtime/dbos.js";
@@ -34,7 +36,7 @@ import { createNoopLogger } from "../lib/console-logger.js";
 import { deliverNotice } from "../lib/hooks.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { maskExcept } from "../loop/call-policy.js";
-import { runLoop } from "../loop/run-loop.js";
+import { runLoop, withRunScript } from "../loop/run-loop.js";
 import { READ_TOOL_OUTPUT_TOOL_ID } from "../loop/tool-output.js";
 import { lastExecOutcome } from "../sandbox/exec-outcome.js";
 import { activityEmission, activityForTool, applyTreeDelta, isChatDataPart, sandboxTreeDelta, stepPartId, toolActivityKey, } from "../sandbox/sandbox-step-translate.js";
@@ -42,17 +44,10 @@ import { createDetailResolver } from "../tools/detail-resolver.js";
 import { forSubAgent } from "../auth/types.js";
 import { walkStepArtifacts } from "../execution/post-step.js";
 import { collectStepOutputs, describeStepRegistrationFailure, generateStepFileMetadata, generateStepSummaryAndWrite, reconcileAndRegisterStepArtifacts, vectorIndexStepOutputs, } from "../execution/post-step-pipeline.js";
-import { mintSandboxIdentity } from "../sandbox/identity.js";
-import { keepSuspendingRefusal } from "../sandbox/sandbox-error.js";
 import { ProvenanceCollector } from "../provenance/collector.js";
 import { blockerOf } from "../tools/sandbox/report-blocker.js";
 import { createFileMetadataCell, SUBMIT_FILE_METADATA_TOOL_ID } from "../tools/sandbox/submit-file-metadata.js";
 import { pauseAtGate, workPause } from "./pause.js";
-/**
- * Fallback when the plan step omits `timeout`. Plans that need 3-hour runs
- * declare it explicitly.
- */
-export const DEFAULT_STEP_TIMEOUT_SECONDS = 3600;
 /**
  * Deterministic `blocked_reason` for a loop that spent every iteration and
  * persisted no output files (see the harness-sandbox-agents spec). Fixed prose,
@@ -157,7 +152,7 @@ export async function runSandboxStepBody(input, deps) {
             logger.warn("emitToParentStream failed (non-fatal)", logger.errorFields(err));
         }
     };
-    // The step waits in place, and the sandbox, if one stands, stays up for the resume.
+    // The step waits in place. The lease stays, and its machine goes away when the pause outlasts the idle period.
     const pause = workPause({
         pool: deps.pool,
         workId: input.runId,
@@ -175,57 +170,23 @@ export async function runSandboxStepBody(input, deps) {
     const session = forSubAgent(input.runSession, input.agentId);
     const writePrefix = await deps.resolveWritePrefix(input);
     const lineageCollector = createLineageCollector(input);
-    // (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 is cached so recovery picks the same machine back up
-    // without re-provisioning.
-    const sandboxSpec = {
-        childWorkflowId,
-        image: input.image,
-        extraEnv: input.extraEnv,
-        resources: input.resources,
-    };
-    const spawn = () => DBOS.runStep(async () => keepSuspendingRefusal(await deps.sandboxClient.createSandbox(session, sandboxSpec, identity)), {
-        name: "sandbox.create",
+    // (2) The lease of the step. The agent acquires its sandbox with `acquire_sandbox` when it needs one, and the
+    // sandbox module owns the machine: the admission, the spawn, a new machine after a pause or a death, and the
+    // pause of a refused spawn. The lease key is the id of this workflow.
+    const lease = deps.leases.bind({
+        leaseKey: childWorkflowId,
+        session: input.runSession,
+        work: { kind: "run", id: input.runId },
+        spawn: { image: input.image, extraEnv: input.extraEnv },
+        emit: safeEmit,
     });
-    let spawned = await spawn();
-    // A refusal of the label gate with the suspend flag waits in a pause, and the spawn runs again after the resume.
-    while (spawned.isErr()) {
-        await pauseAtGate(pause, spawned.error.reason);
-        spawned = await spawn();
-    }
-    const sandbox = spawned.value;
-    // Recovery path: re-check `isAlive` on the persisted ref before continuing.
-    // A classified-dead sandbox triggers a fresh `createSandbox` (task 4.6).
-    // For first execution this is a cheap no-op; on replay it's the seam
-    // that catches a dead pod between checkpoints.
-    await DBOS.runStep(async () => {
-        const liveness = await deps.sandboxClient.isAlive(sandbox);
-        if (!liveness.alive) {
-            const cause = liveness.oomKilled ? "was killed for exceeding its memory limit (sandbox-oom-killed)" : "no longer alive on replay";
-            throw new Error(`sandbox ${sandbox.sandboxId} ${cause} — caller must restart the step`);
-        }
-    }, { name: "sandbox.recheck-alive" });
     // (3) runLoop — the harness loop, each call a durable step.
-    // The step deadline is captured ONCE at step start from the checkpointed
-    // 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`.
-    const stepDeadlineMs = (await DBOS.now()) + (input.timeoutSeconds ?? DEFAULT_STEP_TIMEOUT_SECONDS) * 1000;
     const fileMetadata = createFileMetadataCell();
     const agent = await deps.buildAgent({
         input,
         session,
-        sandbox,
+        lease,
         stepWritePrefix: writePrefix,
-        deadlineMs: () => stepDeadlineMs,
         lineageCollector,
         reportsBlocker: true,
         fileMetadata,
@@ -237,7 +198,9 @@ export async function runSandboxStepBody(input, deps) {
     }
     // Built over THIS agent's tools, not a shared table: a sandbox agent's roster
     // differs per agent type, and each tool describes its own calls.
-    const resolveDetail = createDetailResolver(agent.tools, logger);
+    // The declared tools and `run_script` describe the calls of the agent, and its script tools describe the nested calls.
+    const declared = withRunScript(agent).tools;
+    const resolveDetail = createDetailResolver([...declared, ...(agent.scriptTools ?? [])], logger);
     // Forward every loop event onto the child's own DBOS `"events"` stream
     // (the route fans-in parent + every active child stream — Pattern A).
     // Pre-shaped chat data parts (e.g. `data-sandbox-event` from `run-exec.ts`)
@@ -275,7 +238,7 @@ export async function runSandboxStepBody(input, deps) {
     const failStep = async (errorClass, err) => {
         if (isWorkflowCancellation(err))
             throw err;
-        await tryTeardown(logger, deps, sandbox);
+        await tryRelease(logger, deps, childWorkflowId);
         const durationMs = (await DBOS.now()) - startedAt;
         // The scrub below is deliberate and load-bearing, which makes this record
         // the ONLY account of why the step died — the thrown error carries just the
@@ -283,7 +246,7 @@ export async function runSandboxStepBody(input, deps) {
         // `durationMs`, the iteration cap, and the last exec of the sandbox are
         // what separate a step that died in the model from one that died in the
         // machine. `lastExec` holds no stream text (see `exec-outcome.ts`).
-        const lastExec = lastExecOutcome(sandbox.sandboxId);
+        const lastExec = lastExecOutcome(childWorkflowId);
         logger.error("step failure", {
             errorClass,
             durationMs,
@@ -369,7 +332,7 @@ export async function runSandboxStepBody(input, deps) {
             // The agent declares the output tool of the file-metadata follow-up
             // request from its first request, and the task must not use it.
             policy: {
-                mask: maskExcept(agent.tools.map((tool) => tool.id), [SUBMIT_FILE_METADATA_TOOL_ID]),
+                mask: maskExcept(declared.map((tool) => tool.id), [SUBMIT_FILE_METADATA_TOOL_ID]),
             },
             // A blocker ends the step: the agent declared that it cannot do the work.
             stopWhen: (done) => blockerOf(done) !== null,
@@ -435,7 +398,7 @@ export async function runSandboxStepBody(input, deps) {
     const cappedOutEmpty = hitMaxSteps && manifest.length === 0;
     if (blockerOutcome || cappedOutEmpty) {
         const blockedReason = blockerOutcome?.reason ?? CAPPED_OUT_EMPTY_REASON;
-        await tryTeardown(logger, deps, sandbox);
+        await tryRelease(logger, deps, childWorkflowId);
         const durationMs = (await DBOS.now()) - startedAt;
         await DBOS.runStep(async () => {
             unwrapOrThrow(await updateStepExecution(deps.pool, input.runId, input.stepId, {
@@ -479,7 +442,6 @@ export async function runSandboxStepBody(input, deps) {
         agent,
         fileMetadata,
         writePrefix,
-        sandboxId: sandbox.sandboxId,
         lineageCollector,
     };
     await emitActivity("generating-metadata", "Describing output files");
@@ -552,8 +514,8 @@ export async function runSandboxStepBody(input, deps) {
     const stepOutputs = collectStepOutputs(postCtx, postArtifacts);
     await emitActivity("indexing", "Indexing outputs for search");
     await safeRun(logger, () => vectorIndexStepOutputs(deps, postCtx, postArtifacts), "post-step.vector-index");
-    // (9) teardown — destroy sandbox + clear sandbox_ref.
-    await DBOS.runStep(() => deps.sandboxClient.teardown(sandbox), { name: "sandbox.teardown" });
+    // (9) release — the lease workflow removes the machine of the step.
+    await deps.leases.release(childWorkflowId);
     // (10) mark-terminal + emit. The outcome metric is recorded inside the same
     // step as the ledger row: a replayed body reads the cached step and records
     // nothing again.
@@ -662,11 +624,14 @@ async function safeRunValue(logger, fn, label, fallback) {
         return fallback;
     }
 }
-async function tryTeardown(logger, deps, sandbox) {
+/** Release the lease of a step that failed or blocked. The owner test of the lease workflow covers a failed release. */
+async function tryRelease(logger, deps, leaseKey) {
     try {
-        await DBOS.runStep(() => deps.sandboxClient.teardown(sandbox), { name: "sandbox.teardown" });
+        await deps.leases.release(leaseKey);
     }
     catch (err) {
-        logger.warn("teardown failed (non-fatal)", logger.errorFields(err));
+        if (isWorkflowCancellation(err))
+            throw err;
+        logger.warn("release failed (non-fatal)", logger.errorFields(err));
     }
 }

package/dist/workflows/test/sql-writes.d.ts

@@ -7,7 +7,6 @@
 export declare const ANALYSIS_STATE_WRITE: RegExp;
 export declare const PAUSE_RECORD_WRITE: RegExp;
 export declare const PAUSE_CLEAR_WRITE: RegExp;
-export declare const PAUSES_OF_WORK_CLEAR_WRITE: RegExp;
 export declare const RUNS_STATUS_WRITE: RegExp;
 export declare const RUNS_STATUS_WRITE_ANY_CASE: RegExp;
 export declare const SYNTHESIS_STATUS_WRITE: RegExp;

package/dist/workflows/test/sql-writes.js

@@ -10,8 +10,6 @@ export const ANALYSIS_STATE_WRITE = /UPDATE\s+cortex_analysis_state/i;
 export const PAUSE_RECORD_WRITE = /INSERT INTO cortex_paused_work/i;
 // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the delete of the row of one waiting workflow
 export const PAUSE_CLEAR_WRITE = /DELETE FROM cortex_paused_work WHERE workflow_id = \$1/i;
-// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the delete of each row of a pause of one work
-export const PAUSES_OF_WORK_CLEAR_WRITE = /DELETE FROM cortex_paused_work WHERE work_id = \$1/i;
 // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the run status write, across wrapped SQL lines
 export const RUNS_STATUS_WRITE = /UPDATE cortex_runs\s+SET status/;
 // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the run status write in any letter case, across wrapped SQL lines

package/dist/workspace/filesystem.d.ts

@@ -5,8 +5,8 @@
  *
  * Reads resolve from the analysis's workspace root when the file is present and
  * fall back to an embedder-supplied presigned URL otherwise. The seam writes no
- * provenance — reads don't produce lineage — and does not depend on any
- * sandbox.
+ * provenance — a read tool records its reads in the lineage of a step itself —
+ * and does not depend on any sandbox.
  *
  * Scoping is enforced once, here, by `resolveWorkspacePath`: any path that
  * escapes the analysis's resolved workspace root is rejected before any I/O.

package/dist/workspace/filesystem.js

@@ -5,8 +5,8 @@
  *
  * Reads resolve from the analysis's workspace root when the file is present and
  * fall back to an embedder-supplied presigned URL otherwise. The seam writes no
- * provenance — reads don't produce lineage — and does not depend on any
- * sandbox.
+ * provenance — a read tool records its reads in the lineage of a step itself —
+ * and does not depend on any sandbox.
  *
  * Scoping is enforced once, here, by `resolveWorkspacePath`: any path that
  * escapes the analysis's resolved workspace root is rejected before any I/O.
@@ -37,7 +37,7 @@ import { scopeResource } from "../auth/types.js";
 import { tryFetch, tryFs, errnoOf } from "../lib/fs-result.js";
 import { splitLines } from "../lib/text.js";
 import { classifyWithinRoot } from "../lib/fs-helpers.js";
-import { resolveWorkspacePath } from "./paths.js";
+import { HARNESS_PRIVATE_DIR, resolveWorkspacePath } from "./paths.js";
 // ── Constructor ───────────────────────────────────────────────────────────
 export function createWorkspaceFilesystem(deps) {
     const { resolveWorkspaceRoot, presignedFallback } = deps;
@@ -77,7 +77,7 @@ export function createWorkspaceFilesystem(deps) {
                 op: "workspace.confineRealpath",
                 path: resolved.absolute,
                 cause,
-            })).map((verdict) => (verdict === "escaped" ? { kind: "out_of_scope" } : resolved));
+            })).map((verdict) => (verdict === "escaped" || isHarnessPrivate(resolved.relative) ? { kind: "out_of_scope" } : resolved));
         });
     }
     return {
@@ -159,7 +159,8 @@ export function createWorkspaceFilesystem(deps) {
                     return tryFs("workspace.list", () => fsReaddir(absolute, { withFileTypes: true }), { path: absolute, onAbsent: () => ({ notFound: true }) }).andThen((dirents) => {
                         if ("notFound" in dirents)
                             return okAsync({ kind: "not_found" });
-                        return collectEntries(absolute, dirents).map((entries) => ({ kind: "ok", entries }));
+                        const visible = resolved.relative === "" ? dirents.filter((d) => d.name !== HARNESS_PRIVATE_DIR) : dirents;
+                        return collectEntries(absolute, visible).map((entries) => ({ kind: "ok", entries }));
                     });
                 });
             });
@@ -190,6 +191,10 @@ export function createWorkspaceFilesystem(deps) {
     };
 }
 // ── Helpers ───────────────────────────────────────────────────────────────
+/** True for a root-relative path inside the private directory of the harness, which no workspace tool reaches. */
+function isHarnessPrivate(relative) {
+    return relative === HARNESS_PRIVATE_DIR || relative.startsWith(`${HARNESS_PRIVATE_DIR}/`);
+}
 /** A bare `ok(value)` as a `ResultAsync`, with no `fs` call to wrap. */
 function okAsync(value) {
     return new ResultAsync(Promise.resolve(ok(value)));

package/dist/workspace/paths.d.ts

@@ -181,6 +181,12 @@ export declare function toSandboxPath(workspaceRoot: string, resourceId: string,
  * the resolver as `out_of_scope`. A prefix would only make it look canonical.
  */
 export declare function toAnalysisRootPath(resourceId: string, path: string): string;
+/**
+ * Where the embedder stages the inputs of an analysis, workspace-root-relative
+ * (see the data-profile-init spec). The inputs are immutable: no file tool of the
+ * harness writes under this directory.
+ */
+export declare const STAGED_INPUT_ROOT = "data/inputs";
 /**
  * Parent of every report session, workspace-root-relative. Callers that
  * enumerate the sessions join this. Callers that address one join
@@ -199,10 +205,17 @@ export declare function reportSessionDir(threadId: string): string;
  * Directory of the derived tables of one report session, workspace-root-relative.
  *
  * The derivation writes its output here, and the record prunes an output that the recorded document does
- * not name. Both spell the segment through this helper, thus the write mount and the prune scope cannot
+ * not name. Both spell the segment through this helper, thus the write and the prune scope cannot
  * disagree.
  */
 export declare function reportSessionDerivedDir(threadId: string): string;
+/** Parent of the scratch directory of each conversation, workspace-root-relative. */
+export declare const CONVERSATION_SESSIONS_ROOT = "conversation-sessions";
+/**
+ * The scratch directory of one conversation, workspace-root-relative: the scripts that its turns ran, and the
+ * files that those scripts derived.
+ */
+export declare function conversationSessionDir(threadId: string): string;
 /**
  * True when `value` is a safe single path segment: the safe-id charset (word
  * chars, `.`, `-` — no slash, NUL, or shell-hostile char) AND not a pure-dot
@@ -221,6 +234,11 @@ export declare function isSafeId(value: string): boolean;
  * (the container-path source of truth) validate the same way.
  */
 export declare function assertSafeId(value: string, label: string): void;
+/**
+ * The directory of the harness under each workspace root: the exec records of the sandbox leases. No workspace tool
+ * lists or reads it, and no artifact walk reaches it.
+ */
+export declare const HARNESS_PRIVATE_DIR = ".sandbox";
 /** Root directory for a specific workflow run, workspace-root-relative. */
 export declare function runDir(runId: string): string;
 /** Step directory within a run, workspace-root-relative. */

package/dist/workspace/paths.js

@@ -197,6 +197,12 @@ function normalizeTail(tail) {
         return "";
     return normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
 }
+/**
+ * Where the embedder stages the inputs of an analysis, workspace-root-relative
+ * (see the data-profile-init spec). The inputs are immutable: no file tool of the
+ * harness writes under this directory.
+ */
+export const STAGED_INPUT_ROOT = "data/inputs";
 /**
  * Parent of every report session, workspace-root-relative. Callers that
  * enumerate the sessions join this. Callers that address one join
@@ -218,12 +224,22 @@ export function reportSessionDir(threadId) {
  * Directory of the derived tables of one report session, workspace-root-relative.
  *
  * The derivation writes its output here, and the record prunes an output that the recorded document does
- * not name. Both spell the segment through this helper, thus the write mount and the prune scope cannot
+ * not name. Both spell the segment through this helper, thus the write and the prune scope cannot
  * disagree.
  */
 export function reportSessionDerivedDir(threadId) {
     return `${reportSessionDir(threadId)}/derived`;
 }
+/** Parent of the scratch directory of each conversation, workspace-root-relative. */
+export const CONVERSATION_SESSIONS_ROOT = "conversation-sessions";
+/**
+ * The scratch directory of one conversation, workspace-root-relative: the scripts that its turns ran, and the
+ * files that those scripts derived.
+ */
+export function conversationSessionDir(threadId) {
+    assertSafeId(threadId, "threadId");
+    return `${CONVERSATION_SESSIONS_ROOT}/${threadId}`;
+}
 /**
  * For an analysis-rooted input (`/{analysisId}/...`), strip the leading
  * `/{analysisId}/` segment so it can be resolved relative to the analysis
@@ -275,6 +291,11 @@ export function assertSafeId(value, label) {
         throw new Error(`Invalid ${label}: ${value}`);
     }
 }
+/**
+ * The directory of the harness under each workspace root: the exec records of the sandbox leases. No workspace tool
+ * lists or reads it, and no artifact walk reaches it.
+ */
+export const HARNESS_PRIVATE_DIR = ".sandbox";
 /** Root directory for a specific workflow run, workspace-root-relative. */
 export function runDir(runId) {
     assertSafeId(runId, "runId");

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.46.0",
+    "version": "0.47.0",
     "description": "Host-agnostic bioinformatics agent harness — an agent loop on the AI SDK, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -11,6 +11,7 @@
             "types": "./dist/index.d.ts",
             "import": "./dist/index.js"
         },
+        "./tools/script/quickjs.wasm": "./dist/tools/script/quickjs.wasm",
         "./*.js": {
             "types": "./dist/*.d.ts",
             "import": "./dist/*.js"
@@ -58,6 +59,7 @@
         "@anthropic-ai/sdk": "^0.116.0",
         "@dbos-inc/dbos-sdk": "^5.3.0",
         "@dbos-inc/vercel-ai": "0.5.4",
+        "@earendil-works/pi-codemode": "1.4.0",
         "@fontsource-variable/space-grotesk": "5.1.1",
         "@fontsource/ibm-plex-mono": "5.1.1",
         "@inflexa-ai/tsprov": "0.6.0",
@@ -86,15 +88,17 @@
         "js-tiktoken": "^1.0.21",
         "kysely": "^0.29.6",
         "linkedom": "^0.18.14",
+        "marked": "^18.1.2",
         "mime": "^4.1.0",
         "nanoid": "^5.1.16",
         "neverthrow": "^8.2.0",
         "openai": "^7.4.0",
         "p-queue": "^9.3.3",
-        "pdf-parse": "^2.4.5",
+        "pdfmake": "^0.3.13",
         "pg": "^8.22.0",
         "puppeteer-core": "^23.11.1",
         "turndown": "^7.2.4",
+        "unpdf": "^1.9.1",
         "zod": "^4.4.3"
     },
     "overrides": {
@@ -111,7 +115,6 @@
         "@types/bun": "latest",
         "@types/json-schema": "^7.0.15",
         "@types/node": "^24.13.3",
-        "@types/pdf-parse": "^1.1.5",
         "@typescript/native": "npm:typescript@7.0.2",
         "csstree-validator": "^4.0.1",
         "html-validate": "^11.6.2",

package/dist/prompts/literature-reviewer.d.ts

@@ -1 +0,0 @@
-export declare const literatureReviewerPrompt = "# Literature Reviewer\n\nYou are a systematic biology investigator. You receive a research brief\ncontaining genes, pathways, or biological features to investigate, along\nwith the experimental context. Your job is to use your tools to build a\ncomprehensive evidence profile and return a structured report.\n\nYou are task-oriented \u2014 you do not interact with the user. You receive\na brief, investigate, and return results.\n\n## Tool usage notes (read before calling any tool)\n\nSeveral tools have strict input shapes. Mis-shaping your call wastes a\nturn and forces a retry.\n\n- `pubmed({action:\"search\"})` \u2014 pass a focused query string. Shape: `{ action: \"search\", query: \"BRCA1 AND breast cancer\", maxResults: 10 }`.\n- `pubmed({action:\"details\"})` \u2014 takes `pmids`, a non-empty array of\n  PMID strings. Shape: `{ action: \"details\", pmids: [\"12345678\", \"87654321\"] }`.\n- `search_interactions` \u2014 accepts up to **100 identifiers per call**. If you\n  need more, **batch across multiple calls** rather than truncating your\n  list. Shape: `{ identifiers: [\"TP53\", \"BRCA1\", ...], limit: 50 }`.\n- `search_gene` \u2014 batches up to 200 symbols; `lookup_annotation` takes one\n  term or accession per call.\n- `search_protein` \u2014 one gene symbol or UniProt accession per call. It answers\n  with the protein: the accession, the recommended name, the sequence length,\n  the curated function, and the subcellular locations. An empty `proteins`\n  array is a valid \"no data\" outcome; do NOT retry the same call.\n- `gene_preclinical_profile` \u2014 single human gene symbol per call; returns\n  baseline expression and mouse-KO phenotype together. Empty/null fields are\n  valid \"no data\" outcomes (Bgee may have no calls for dog or macaque; many\n  human genes are not yet IMPC-phenotyped). Do NOT retry on empty output.\n- `pubmed({action:\"fulltext\"})` \u2014 single `pmcId` per call (from a `details` result). Use sparingly.\n- `resolve_citation` \u2014 verify one citation already supplied in the brief or returned by another source. Use it for identity/metadata verification, not topical discovery. Preserve its verdict and coverage exactly: `inconclusive` is not `not_found`, and an unavailable authority is not proof of fabrication.\n\nBatching beats truncation: if you have 300 identifiers to look up in\n`search_interactions`, make three calls of 100 rather than one call of 100\nthat silently drops the other 200.\n\n## What Each Tool Answers\n\nPick the lookups that the brief's question needs for each target:\n\n- **The gene** \u2014 `search_gene`: its Ensembl ID, coordinates, biotype, and\n  aliases.\n- **The protein** \u2014 `search_protein`, when the claim is about the protein\n  rather than the locus: what it does, how long it is, and where in the cell\n  it acts.\n- **Pathway context** \u2014 `lookup_annotation({vocabulary:\"pathways\"})`. Note\n  which pathways connect multiple genes from the brief.\n- **Function** \u2014 `lookup_annotation({vocabulary:\"go\"})`, when the gene's\n  role is unclear from the gene search alone.\n- **Interaction partners** \u2014 `search_interactions`, especially partners\n  that also appear in the brief.\n- **Literature evidence** \u2014 `pubmed({action:\"search\"})` with queries that\n  combine the gene with the disease or condition from the brief, then\n  `details` for the most relevant hits, and `fulltext` only for papers\n  that need deeper reading.\n- **Preclinical grounding** \u2014 `gene_preclinical_profile`, when the brief\n  asks about tissue expression, model-organism suitability, or KO\n  consequences.\n\n## Depth Guidelines\n\n- **Top priority targets** (top DE genes, hub genes, user-specified) get\n  the deepest evidence profile.\n- **Supporting targets** (enriched pathways, interaction partners) need\n  the gene, its pathway context, and its literature; add function and\n  interactions only when those results are ambiguous.\n- **Limit PubMed searches**: max 2-3 queries per gene. Combine terms\n  effectively (e.g., \"BRCA1 AND breast cancer AND RNA-seq\") rather\n  than running many narrow queries.\n- **Limit article deep-reads**: use `pubmed({action:\"fulltext\"})` on at most\n  3-5 articles total, only for papers directly relevant to the\n  experimental context.\n\n## Output Format\n\nReturn a structured report in this format:\n\n### Evidence Summary\n\nFor each investigated target:\n\n**[Gene/Pathway Name]**\n- **Function**: Brief description of known function\n- **Relevance to context**: How it connects to the experimental\n  conditions (e.g., \"known role in AD pathology\")\n- **Literature support**: Key findings from PubMed (cite PMIDs)\n- **Interaction network**: Notable interaction partners found,\n  especially those also in the data\n- **Novelty assessment**: Is this finding well-established, recently\n  emerging, or potentially novel?\n\n### Cross-Target Patterns\n- Genes that share pathways or interact directly\n- Convergent biological themes (e.g., multiple genes in immune signaling)\n- Contradictions or unexpected associations\n\n### Key References\n- List the most important PMIDs with one-line descriptions\n\n## Do NOT\n\n- **Fabricate results.** If a search returns no results, say so.\n- **Turn resolver uncertainty into certainty.** Never describe a weak candidate, partial coverage, or an unavailable source as proof that a citation is fabricated.\n- **Skip tool calls.** Do not claim knowledge about a gene without\n  looking it up. Your value is in systematic, verified investigation.\n- **Over-read articles.** Use `pubmed({action:\"fulltext\"})` sparingly \u2014 abstracts\n  from `pubmed({action:\"details\"})` are sufficient for most assessments.\n- **Investigate targets not in the brief.** Stay focused on what was\n  requested. Note interesting leads for follow-up but do not chase them.\n- **Produce conversational text.** You are returning a structured report,\n  not chatting with a user.\n";