@inflexa-ai/harness 0.46.2 → 0.48.0

package/dist/workflows/pause.js

@@ -14,6 +14,7 @@ import { DBOS } from "@dbos-inc/dbos-sdk";
 import { z } from "zod";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { deliverNotice } from "../lib/hooks.js";
+import { trackWorkPaused } from "../lib/metrics.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { isTurnCredentialMissing } from "../loop/turn-credentials.js";
 import { modelFailureOf } from "../providers/errors.js";
@@ -123,30 +124,36 @@ export function workPause(scope) {
             await suspendCredential("pause.suspend");
         await scope.emit({ type: "data-pause", id: workflowId, ...work, state, cause, attempt, retryAt });
         log.warn("work paused", { workflowId, ...work, state, cause: cause.kind, attempt });
-        const waited = await waitForMessage(topic, delayMs, signal);
         let end;
-        if (waited === "hold") {
-            // A person held the work: the timer stops, and the work waits for a resume.
-            await DBOS.runStep(async () => unwrapOrThrow(await recordPause(scope.pool, {
-                workflowId,
-                ...work,
-                analysisId: scope.analysisId,
-                threadId: scope.threadId,
-                state: "paused",
-                cause,
-                attempt,
-                topic,
-                pausedAt: new Date(pausedAt).toISOString(),
-                runSession: scope.run?.session,
-            })), { name: "pause.hold" });
-            await suspendCredential("pause.hold.suspend");
-            await scope.emit({ type: "data-pause", id: workflowId, ...work, state: "paused", cause, attempt });
-            log.info("work held", { workflowId, ...work, attempt });
-            const held = await waitForMessage(topic, undefined, signal);
-            end = held === "hold" ? "resume" : held;
+        const untrack = trackWorkPaused({ workKind: scope.workKind });
+        try {
+            const waited = await waitForMessage(topic, delayMs, signal);
+            if (waited === "hold") {
+                // A person held the work: the timer stops, and the work waits for a resume.
+                await DBOS.runStep(async () => unwrapOrThrow(await recordPause(scope.pool, {
+                    workflowId,
+                    ...work,
+                    analysisId: scope.analysisId,
+                    threadId: scope.threadId,
+                    state: "paused",
+                    cause,
+                    attempt,
+                    topic,
+                    pausedAt: new Date(pausedAt).toISOString(),
+                    runSession: scope.run?.session,
+                })), { name: "pause.hold" });
+                await suspendCredential("pause.hold.suspend");
+                await scope.emit({ type: "data-pause", id: workflowId, ...work, state: "paused", cause, attempt });
+                log.info("work held", { workflowId, ...work, attempt });
+                const held = await waitForMessage(topic, undefined, signal);
+                end = held === "hold" ? "resume" : held;
+            }
+            else {
+                end = waited;
+            }
         }
-        else {
-            end = waited;
+        finally {
+            untrack();
         }
         await DBOS.runStep(async () => unwrapOrThrow(await clearPause(scope.pool, workflowId)), { name: "pause.clear" });
         await scope.emit({ type: "data-pause", id: workflowId, ...work, state: "running" });

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/dist/workspace/session-files.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The files that a session writes outside a run, and the host hook that keeps a copy of each.
+ *
+ * A run registers its step files through `ArtifactRegistry`. A chat thread and a report session write files too:
+ * the scripts and the derived files of `run_script`, and the files of `write_file` and `edit_file`. A host that
+ * keeps the files of an analysis elsewhere binds `syncSessionFile`, and each write reaches it with its bytes. The
+ * call runs inside the tool step of the write, thus a step that runs again after a crash calls the hook again with
+ * the same file.
+ */
+import type { ResultAsync } from "neverthrow";
+import type { AgentSession } from "../auth/types.js";
+import { type NoticeFailure } from "../lib/hooks.js";
+import type { Logger } from "../lib/logger.js";
+/** Who owns a session file. A file in the scratch directory of a thread belongs to that thread. */
+export type SessionFileOwner = {
+    readonly kind: "thread";
+    readonly threadId: string;
+} | {
+    readonly kind: "analysis";
+};
+export type SessionFileWrite = {
+    /** The session of the tool call that wrote the file. */
+    readonly session: AgentSession;
+    readonly owner: SessionFileOwner;
+    /** The analysis-relative path, and the hash and the size of the bytes. */
+    readonly path: string;
+    readonly hash: string;
+    readonly size: number;
+    /** The exact bytes that landed. */
+    readonly content: Uint8Array;
+};
+/** A notice: a failure is logged, and the write stays done. */
+export type SyncSessionFile = (write: SessionFileWrite) => ResultAsync<void, NoticeFailure>;
+/** Give one landed write to the hook of the host. An unbound hook does nothing. */
+export declare function syncWrittenFile(sync: SyncSessionFile | undefined, logger: Logger, write: SessionFileWrite): Promise<void>;

package/dist/workspace/session-files.js

@@ -0,0 +1,16 @@
+/**
+ * The files that a session writes outside a run, and the host hook that keeps a copy of each.
+ *
+ * A run registers its step files through `ArtifactRegistry`. A chat thread and a report session write files too:
+ * the scripts and the derived files of `run_script`, and the files of `write_file` and `edit_file`. A host that
+ * keeps the files of an analysis elsewhere binds `syncSessionFile`, and each write reaches it with its bytes. The
+ * call runs inside the tool step of the write, thus a step that runs again after a crash calls the hook again with
+ * the same file.
+ */
+import { deliverNotice } from "../lib/hooks.js";
+/** Give one landed write to the hook of the host. An unbound hook does nothing. */
+export async function syncWrittenFile(sync, logger, write) {
+    if (sync === undefined)
+        return;
+    await deliverNotice(logger.with({ analysisId: write.session.scope.analysisId, path: write.path }), "syncSessionFile", sync(write));
+}