@inflexa-ai/harness 0.25.0 → 0.26.1

package/dist/runtime/boot.js

@@ -20,27 +20,24 @@
  *      misconfigured pool fails loudly at boot, not under load.
  *   5. `assembleCoreRuntime(core)` — registers the durable-workflow cohort and
  *      builds the conversation agent (register-before-launch invariant).
- *   6. `backfillConversationDisplayEnvelopes(...)` — validates every stored
- *      display envelope and freezes one for each legacy turn that has none, so
- *      the runtime read path never meets a row without a display projection.
- *      Runs AFTER assembly because migrating a legacy call's one-line detail
- *      needs the assembled conversation roster, embedder-contributed tools
- *      included; assembly starts no traffic, so this is still before any read.
- *   7. `beforeLaunch()` — embedder hook for host-specific pre-launch work that
+ *   6. `beforeLaunch()` — embedder hook for host-specific pre-launch work that
  *      must attach before DBOS launch re-emits events (scheduled sweeps, an
  *      legacy-workflow reap, an agent-switch install). Runs after registration
  *      so it may close over the registered callables.
- *   8. `launchDbos(...)` — the last registration-dependent step.
+ *   7. `launchDbos(...)` — the last registration-dependent step.
+ *
+ * No step reads or rewrites stored conversation display. A boot that validated
+ * every `messages` row is what let a single retired part key fail startup for a
+ * whole deployment; the read tolerates such a row by itself now
+ * (`parseStoredDisplayEnvelope`), which is where a per-row concern belongs.
  *
  * Boot-step errors PROPAGATE (the embedder's composition root catches them and
  * releases whatever it acquired). Only `shutdown` swallows per-step failures —
  * once shutdown starts, exiting takes precedence (see `runShutdownSequence`).
  */
-import { unwrapOrThrow } from "../lib/result.js";
 import { SANDBOX_AGENT_META } from "../agents/sandbox/index.js";
 import { validateAgentSkills } from "../agents/sandbox/validate-skills.js";
 import { initCortexState } from "../state/init.js";
-import { backfillConversationDisplayEnvelopes } from "../memory/conversation-display-backfill.js";
 import { assembleCoreRuntime } from "./assemble.js";
 import { assertConnectionBudget } from "./connection-budget.js";
 import { launchDbos, shutdownDbos } from "./dbos.js";
@@ -57,15 +54,6 @@ export async function bootHarness(deps) {
     await initCortexState(pool);
     await assertConnectionBudget({ pool, logger, config: deps.connectionBudget });
     const runtime = assembleCoreRuntime(core);
-    // Assembly registers `conversation` unconditionally, so this resolution can
-    // never refuse; `unwrapOrThrow` turns the impossible error branch into a
-    // boot-propagating throw rather than threading a Result through the boot
-    // sequence, whose steps already fail by propagation.
-    const conversationAgent = unwrapOrThrow(runtime.agents.forThread("conversation"));
-    await backfillConversationDisplayEnvelopes({
-        pool,
-        tools: conversationAgent.tools,
-    });
     await deps.beforeLaunch?.();
     await launchDbos({ config: deps.dbos, logger });
     logger.named("boot").info("harness booted", { executorId: deps.dbos.executorId });

package/dist/sandbox/client.d.ts

@@ -1,5 +1,5 @@
 /**
- * `SandboxClient` — the five-method seam every sandbox-backed module in
+ * `SandboxClient` — the seam every sandbox-backed module in
  * the harness sits on. Implementations are backend-selected
  * (`docker`/`k8s`) by `createSandboxClient()` in `create-sandbox.ts` and
  * injected at the composition root as a construction-time dependency
@@ -17,20 +17,16 @@
  *   Many execs may fire against the same machine.
  * - The **exec** lifetime is one `submitExec → awaitExec`.
  *
- * `awaitExec` runs in the workflow body (not as a DBOS step) because
- * `DBOS.recv` and `DBOS.writeStream` are body-only.
+ * **Every caller of `awaitExec` runs inside a DBOS workflow body.** `DBOS.recv`
+ * and `DBOS.writeStream` are body-only, thus the callback transport cannot
+ * settle anywhere else, and the poll transport reaches for `DBOS.runStep` and
+ * `DBOS.sleepms` defaults. A caller that starts from a live chat turn registers
+ * its own workflow and starts it: `tasks/extract-values.ts` and
+ * `tasks/derive-table-exec.ts` are the two worked examples. No type carries this
+ * rule yet, thus a new caller must read this paragraph.
  */
-import type { CreateSandboxMeta, ExecEmit, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxTransport, SubmitExecBody } from "./types.js";
+import type { CreateSandboxMeta, ExecEmit, ExecResult, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SubmitExecBody } from "./types.js";
 export interface SandboxClient {
-    /**
-     * The result transport this client awaits under, fixed at construction. A caller that runs outside a
-     * workflow body reads it: `callback` awaits through `DBOS.recv`, which is body-only, thus such a caller
-     * must refuse before it starts a container it can never await.
-     *
-     * Optional, because a hand-written realization states nothing here. Absent means unknown, and a caller
-     * treats it as the poll default rather than refusing every composition that omits it.
-     */
-    readonly transport?: SandboxTransport;
     /**
      * DBOS step (`sandbox.create`) — the spawn half of the two-step create
      * (see the harness-sandbox-exec spec). Launches the sandbox-base container/Job under the

package/dist/sandbox/client.js

@@ -1,5 +1,5 @@
 /**
- * `SandboxClient` — the five-method seam every sandbox-backed module in
+ * `SandboxClient` — the seam every sandbox-backed module in
  * the harness sits on. Implementations are backend-selected
  * (`docker`/`k8s`) by `createSandboxClient()` in `create-sandbox.ts` and
  * injected at the composition root as a construction-time dependency
@@ -17,7 +17,12 @@
  *   Many execs may fire against the same machine.
  * - The **exec** lifetime is one `submitExec → awaitExec`.
  *
- * `awaitExec` runs in the workflow body (not as a DBOS step) because
- * `DBOS.recv` and `DBOS.writeStream` are body-only.
+ * **Every caller of `awaitExec` runs inside a DBOS workflow body.** `DBOS.recv`
+ * and `DBOS.writeStream` are body-only, thus the callback transport cannot
+ * settle anywhere else, and the poll transport reaches for `DBOS.runStep` and
+ * `DBOS.sleepms` defaults. A caller that starts from a live chat turn registers
+ * its own workflow and starts it: `tasks/extract-values.ts` and
+ * `tasks/derive-table-exec.ts` are the two worked examples. No type carries this
+ * rule yet, thus a new caller must read this paragraph.
  */
 export {};

package/dist/sandbox/create-sandbox.js

@@ -127,7 +127,6 @@ export function createSandboxClient(config) {
     // poll loop's escalation probe are the same backend inspect.
     const isAlive = async (ref) => unwrapOrThrow(await ops.isAlive(ref));
     return {
-        transport,
         createSandbox: async (meta, identity) => {
             // The config states an engine fact (binds preserve host ownership);
             // which remediation that fact demands — today, a world-writable step

package/dist/tasks/derive-table-exec.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The container of one report-session derivation, as a registered DBOS workflow.
+ *
+ * The `derive_table` tool runs inside one live chat turn, and a chat turn is not a workflow body. An await
+ * of an exec under the callback transport calls `DBOS.recv`, which a workflow body alone can call. Thus the
+ * container lives here, behind a registered workflow, and the tool starts it and awaits the handle.
+ *
+ * The shape is the shape of `tasks/extract-values.ts`: a body that a test drives directly, a registration
+ * that closes over the construction-time deps, and a trigger that starts the workflow and gives the result
+ * back. The tool holds the trigger as a plain function, thus no module under `tools/` imports DBOS.
+ *
+ * The body owns the whole machine lifetime. It creates the container, submits one exec, awaits the terminal
+ * result, and tears the container down on both paths. A teardown fault reaches the log alone, because the
+ * work is done by then.
+ */
+import type { Logger } from "../lib/logger.js";
+import type { SandboxClient } from "../sandbox/client.js";
+import type { ExecResult } from "../sandbox/types.js";
+import { type DeriveTableExecInput } from "../tools/report-session/derive-table.js";
+/** The construction-time deps of the body. The registration closes over them, thus the trigger holds none. */
+export interface DeriveTableExecDeps {
+    readonly sandboxClient: SandboxClient;
+    /**
+     * The checkpointed clock of the deadline. It defaults to `DBOS.now()`, which a replay reads again from
+     * the checkpoint. A test injects a fixed clock, thus it drives this body with no launched runtime.
+     */
+    readonly now?: () => Promise<number>;
+    readonly logger?: Logger;
+}
+/**
+ * The body, exported so a test drives it without a registered workflow.
+ *
+ * A fault of any seam call throws. The tool reads a rejection as one short detail, thus the caller needs no
+ * result type here.
+ */
+export declare function runDeriveTableExecBody(input: DeriveTableExecInput, deps: DeriveTableExecDeps): Promise<ExecResult>;
+/**
+ * Register the derivation workflow with DBOS. It gives back the registered callable, thus a trigger
+ * dispatches with `DBOS.startWorkflow`.
+ */
+export declare function registerDeriveTableExecWorkflow(deps: DeriveTableExecDeps): (input: DeriveTableExecInput) => Promise<ExecResult>;
+/** The per-attempt workflow id. The execution id is unique already, and the nonce keeps a retry distinct. */
+export declare function deriveTableExecWorkflowId(executionId: string, nonce: string): string;
+/**
+ * The async edge. It starts the registered workflow and it awaits the terminal result.
+ *
+ * The tool authorizes the derivation before this call and it revokes after, thus this edge holds no
+ * lifecycle of its own. A workflow fault rejects the returned promise.
+ */
+export declare function triggerDeriveTableExec(workflow: (input: DeriveTableExecInput) => Promise<ExecResult>, input: DeriveTableExecInput): Promise<ExecResult>;

package/dist/tasks/derive-table-exec.js

@@ -0,0 +1,84 @@
+/**
+ * The container of one report-session derivation, as a registered DBOS workflow.
+ *
+ * The `derive_table` tool runs inside one live chat turn, and a chat turn is not a workflow body. An await
+ * of an exec under the callback transport calls `DBOS.recv`, which a workflow body alone can call. Thus the
+ * container lives here, behind a registered workflow, and the tool starts it and awaits the handle.
+ *
+ * The shape is the shape of `tasks/extract-values.ts`: a body that a test drives directly, a registration
+ * that closes over the construction-time deps, and a trigger that starts the workflow and gives the result
+ * back. The tool holds the trigger as a plain function, thus no module under `tools/` imports DBOS.
+ *
+ * The body owns the whole machine lifetime. It creates the container, submits one exec, awaits the terminal
+ * result, and tears the container down on both paths. A teardown fault reaches the log alone, because the
+ * work is done by then.
+ */
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { randomUUID } from "node:crypto";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { mintSandboxIdentity } from "../sandbox/identity.js";
+import { buildDerivationExec, DERIVATION_DEADLINE_MS, DERIVATION_RESOURCES, DERIVE_RUN_LITERAL, DERIVE_STEP_LITERAL, } from "../tools/report-session/derive-table.js";
+/** The awaitExec callback. A derivation reports no live activity, thus the callback drops each event. */
+const noopEmit = () => { };
+/**
+ * The body, exported so a test drives it without a registered workflow.
+ *
+ * A fault of any seam call throws. The tool reads a rejection as one short detail, thus the caller needs no
+ * result type here.
+ */
+export async function runDeriveTableExecBody(input, deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("derive-table-exec").with({ analysisId: input.analysisId });
+    const workflowId = DBOS.workflowID ?? `${DERIVE_RUN_LITERAL}:${input.executionId}`;
+    const sandbox = await deps.sandboxClient.createSandbox({
+        runId: DERIVE_RUN_LITERAL,
+        stepId: DERIVE_STEP_LITERAL,
+        analysisId: input.analysisId,
+        childWorkflowId: workflowId,
+        resources: DERIVATION_RESOURCES,
+        writableTail: input.writableTail,
+    }, mintSandboxIdentity(DERIVE_RUN_LITERAL));
+    try {
+        // A checkpointed clock, not `Date.now()`: the await gates on this absolute deadline, and a
+        // wall-clock deadline that grew on replay would shift which loop iteration crosses it.
+        const deadline = (await (deps.now ?? (() => DBOS.now()))()) + DERIVATION_DEADLINE_MS;
+        await deps.sandboxClient.submitExec(sandbox, buildDerivationExec({
+            script: input.script,
+            execId: input.executionId,
+            workingDir: input.workingDir,
+            inputs: input.inputs,
+            output: input.output,
+        }));
+        return await deps.sandboxClient.awaitExec(sandbox, input.executionId, noopEmit, deadline);
+    }
+    finally {
+        try {
+            await deps.sandboxClient.teardown(sandbox);
+        }
+        catch (cause) {
+            logger.warn("the derivation sandbox did not tear down", logger.errorFields(cause));
+        }
+    }
+}
+/**
+ * Register the derivation workflow with DBOS. It gives back the registered callable, thus a trigger
+ * dispatches with `DBOS.startWorkflow`.
+ */
+export function registerDeriveTableExecWorkflow(deps) {
+    return DBOS.registerWorkflow((input) => runDeriveTableExecBody(input, deps), { name: "derive-table-exec" });
+}
+/** The per-attempt workflow id. The execution id is unique already, and the nonce keeps a retry distinct. */
+export function deriveTableExecWorkflowId(executionId, nonce) {
+    return `${DERIVE_RUN_LITERAL}:${executionId}:${nonce}`;
+}
+/**
+ * The async edge. It starts the registered workflow and it awaits the terminal result.
+ *
+ * The tool authorizes the derivation before this call and it revokes after, thus this edge holds no
+ * lifecycle of its own. A workflow fault rejects the returned promise.
+ */
+export async function triggerDeriveTableExec(workflow, input) {
+    const handle = (await DBOS.startWorkflow(workflow, {
+        workflowID: deriveTableExecWorkflowId(input.executionId, randomUUID()),
+    })(input));
+    return handle.getResult();
+}

package/dist/tools/define-tool.d.ts

@@ -39,9 +39,9 @@ export type ToolExecutionMode = "step" | "workflow" | "inline";
 /** Runtime guard — does a `Result`'s error value carry the `ToolError` shape? */
 export declare function isToolError(value: unknown): value is ToolError;
 /**
- * The picture that a tool ok value carries beside its JSON data. `base64` holds
+ * One picture that a tool ok value carries beside its JSON data. `base64` holds
  * the bytes, and `mediaType` names the IANA type, for example "image/png". The
- * loop splits the picture out of the JSON text, and it rides the tool result as
+ * loop splits each picture out of the JSON text, and it rides the tool result as
  * an image content block. Thus the model sees the picture, and the JSON text
  * holds no bytes.
  */
@@ -50,23 +50,34 @@ export interface ToolResultImage {
     readonly mediaType: string;
 }
 /**
- * The reserved key that carries a picture on a tool ok value. It is a symbol,
+ * The reserved key that carries the pictures on a tool ok value. It is a symbol,
  * thus it never collides with a data field. `JSON.stringify` also omits a symbol
  * key, thus the bytes never reach the JSON text by accident.
  */
 export declare const toolResultImageKey: unique symbol;
-/** A tool ok value that can carry a picture under the reserved key. */
+/** A tool ok value that can carry one picture or an ordered list of them under the reserved key. */
 export type WithToolResultImage<T> = T & {
-    readonly [toolResultImageKey]?: ToolResultImage;
+    readonly [toolResultImageKey]?: ToolResultImage | readonly ToolResultImage[];
 };
 /**
- * Attach a picture to a tool ok value. The value keeps its own fields, and the
+ * Attach one picture to a tool ok value. The value keeps its own fields, and the
  * picture rides under the reserved key. The loop reads the key, and it moves the
  * bytes into an image content block on the tool result.
  */
 export declare function withToolResultImage<T extends object>(value: T, image: ToolResultImage): WithToolResultImage<T>;
-/** Read the picture that a tool ok value carries, or undefined when it carries none. */
-export declare function readToolResultImage(value: unknown): ToolResultImage | undefined;
+/**
+ * Attach an ordered list of pictures to a tool ok value. The order is the order
+ * that the model reads, and the loop keeps it on the wire. A tool that slices a
+ * page attaches the slices in document order.
+ */
+export declare function withToolResultImages<T extends object>(value: T, images: readonly ToolResultImage[]): WithToolResultImage<T>;
+/**
+ * Read the pictures that a tool ok value carries, in order. A value with none
+ * gives the empty list. The one-picture shape reads as a list of one, thus a
+ * tool that attaches one picture and a tool that attaches a list meet the loop
+ * in the same shape.
+ */
+export declare function readToolResultImages(value: unknown): ToolResultImage[];
 /**
  * The request-scoped values passed to every tool's `execute`. No injected
  * dependencies (see the harness-durable-runtime spec) — invocation identity,

package/dist/tools/define-tool.js

@@ -21,30 +21,46 @@ export function isToolError(value) {
     return typeof value === "object" && value !== null && typeof value.error === "string" && typeof value.retryable === "boolean";
 }
 /**
- * The reserved key that carries a picture on a tool ok value. It is a symbol,
+ * The reserved key that carries the pictures on a tool ok value. It is a symbol,
  * thus it never collides with a data field. `JSON.stringify` also omits a symbol
  * key, thus the bytes never reach the JSON text by accident.
  */
 export const toolResultImageKey = Symbol("toolResultImage");
 /**
- * Attach a picture to a tool ok value. The value keeps its own fields, and the
+ * Attach one picture to a tool ok value. The value keeps its own fields, and the
  * picture rides under the reserved key. The loop reads the key, and it moves the
  * bytes into an image content block on the tool result.
  */
 export function withToolResultImage(value, image) {
     return { ...value, [toolResultImageKey]: image };
 }
-/** Read the picture that a tool ok value carries, or undefined when it carries none. */
-export function readToolResultImage(value) {
+/**
+ * Attach an ordered list of pictures to a tool ok value. The order is the order
+ * that the model reads, and the loop keeps it on the wire. A tool that slices a
+ * page attaches the slices in document order.
+ */
+export function withToolResultImages(value, images) {
+    return { ...value, [toolResultImageKey]: images };
+}
+/** Does one entry under the reserved key carry the picture shape? */
+function isToolResultImage(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return false;
+    const { base64, mediaType } = entry;
+    return typeof base64 === "string" && typeof mediaType === "string";
+}
+/**
+ * Read the pictures that a tool ok value carries, in order. A value with none
+ * gives the empty list. The one-picture shape reads as a list of one, thus a
+ * tool that attaches one picture and a tool that attaches a list meet the loop
+ * in the same shape.
+ */
+export function readToolResultImages(value) {
     if (typeof value !== "object" || value === null)
-        return undefined;
-    const image = value[toolResultImageKey];
-    if (typeof image !== "object" || image === null)
-        return undefined;
-    const { base64, mediaType } = image;
-    if (typeof base64 !== "string" || typeof mediaType !== "string")
-        return undefined;
-    return { base64, mediaType };
+        return [];
+    const carried = value[toolResultImageKey];
+    const entries = Array.isArray(carried) ? carried : [carried];
+    return entries.filter(isToolResultImage);
 }
 /**
  * Package a `Tool`. The emitted JSON Schema must have a top-level

package/dist/tools/report-session/derive-table.d.ts

@@ -7,7 +7,7 @@
  *
  * A session derivation is not an analysis run. It mints no run id, it registers no artifact, and it writes
  * under the session directory alone. The rails are the rails of the value tier (`tasks/extract-values.ts`):
- * the sandbox client, the identity mint, and the authorizer on every terminal path. The container is
+ * the injected exec runner, the identity mint, and the authorizer on every terminal path. The container is
  * ephemeral, and it goes away with the work.
  *
  * The container mounts the analysis tree read-only, and one write mount covers the `derived/` directory of
@@ -29,15 +29,14 @@
  * condition one time, up front, the same discipline as the eyes. A per-attempt failure would instead read as
  * a transient fault, and it would invite a repeat of a call that can never pass.
  *
- * The transport of the client is the second such bound. A derivation runs inside one live turn and not
- * inside a workflow body. The poll transport awaits with plain steps and a plain sleep, thus it settles
- * there. The callback transport awaits through `DBOS.recv`, which a workflow body alone can call, thus this
- * tool refuses up front under it rather than start a container that nothing can await.
+ * The container runs behind a seam, and never in the turn. An await of an exec is a workflow-body call
+ * under the callback transport, and a report turn is not a body. Thus the tool takes an injected runner,
+ * and a registered workflow owns the container. The tool holds no sandbox client, and it imports no DBOS.
  */
 import { z } from "zod";
 import type { RunAuthorizer } from "../../execution/run-authorizer.js";
 import { type Logger } from "../../lib/logger.js";
-import type { SandboxClient } from "../../sandbox/client.js";
+import type { ResourceSpec } from "../../config/resource-limits.js";
 import type { ExecResult, SubmitExecBody } from "../../sandbox/types.js";
 import type { DerivationSource, ReportSessionStateStore } from "../../state/report-session-state.js";
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
@@ -113,10 +112,20 @@ export interface DeriveTableToolDeps {
     readonly gateway: ReportSessionStateGateway;
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     readonly derivations: Pick<ReportSessionStateStore, "appendDerivation">;
-    readonly sandboxClient?: SandboxClient;
+    readonly runDerivation?: DeriveTableRunner;
     readonly runAuthorizer?: RunAuthorizer;
     readonly logger?: Logger;
 }
+/** The synthetic run id and step id of one derivation. Both are constants, and neither names a run row. */
+export declare const DERIVE_RUN_LITERAL: "derive-table";
+export declare const DERIVE_STEP_LITERAL: "derive";
+/** The exec budget of one derivation. It matches the budget of the value tier. */
+export declare const DERIVATION_DEADLINE_MS = 300000;
+/**
+ * The container size of one derivation. A join or a pivot loads each declared input into pandas at one
+ * time, thus the container needs the headroom of the value tier.
+ */
+export declare const DERIVATION_RESOURCES: ResourceSpec;
 /** The environment variable that carries the declared inputs into the container. */
 export declare const DERIVE_INPUT_ENV = "DERIVE_INPUTS";
 /** The environment variable that carries the container path of the output file into the container. */
@@ -152,6 +161,29 @@ export declare function buildDerivationExec(args: {
  * The function is pure, thus a test asserts the mapping without a sandbox.
  */
 export declare function describeExecFailure(result: ExecResult): string | undefined;
+/**
+ * The exec of one derivation, as a registered workflow reads it.
+ *
+ * Each field is plain data, thus the value crosses the workflow boundary and it survives a replay. The
+ * paths are container paths already: the host maps them one time, before the start.
+ */
+export interface DeriveTableExecInput {
+    readonly analysisId: string;
+    readonly executionId: string;
+    readonly script: string;
+    readonly writableTail: string;
+    readonly workingDir: string;
+    readonly inputs: readonly DerivationInputMount[];
+    readonly output: string;
+}
+/**
+ * Run one derivation exec and give the terminal result back.
+ *
+ * The composition realizes it over a registered workflow, thus the container lives inside a workflow body
+ * and the await is legal under each transport. A fault of the sandbox rejects the promise, and the tool
+ * turns that rejection into one short detail.
+ */
+export type DeriveTableRunner = (input: DeriveTableExecInput) => Promise<ExecResult>;
 /**
  * Make the derivation tool over the session-state gateway, the derivation ledger, and the sandbox rails.
  *

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

@@ -7,7 +7,7 @@
  *
  * A session derivation is not an analysis run. It mints no run id, it registers no artifact, and it writes
  * under the session directory alone. The rails are the rails of the value tier (`tasks/extract-values.ts`):
- * the sandbox client, the identity mint, and the authorizer on every terminal path. The container is
+ * the injected exec runner, the identity mint, and the authorizer on every terminal path. The container is
  * ephemeral, and it goes away with the work.
  *
  * The container mounts the analysis tree read-only, and one write mount covers the `derived/` directory of
@@ -29,12 +29,11 @@
  * condition one time, up front, the same discipline as the eyes. A per-attempt failure would instead read as
  * a transient fault, and it would invite a repeat of a call that can never pass.
  *
- * The transport of the client is the second such bound. A derivation runs inside one live turn and not
- * inside a workflow body. The poll transport awaits with plain steps and a plain sleep, thus it settles
- * there. The callback transport awaits through `DBOS.recv`, which a workflow body alone can call, thus this
- * tool refuses up front under it rather than start a container that nothing can await.
+ * The container runs behind a seam, and never in the turn. An await of an exec is a workflow-body call
+ * under the callback transport, and a report turn is not a body. Thus the tool takes an injected runner,
+ * and a registered workflow owns the container. The tool holds no sandbox client, and it imports no DBOS.
  */
-import { err, ok } from "neverthrow";
+import { ok } from "neverthrow";
 import { unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { z } from "zod";
@@ -43,7 +42,6 @@ import { classifyWithinRoot, computeSha256, computeSha256File } from "../../lib/
 import { defaultErrorFields } from "../../lib/logger.js";
 import { snapshotEntry } from "../../report-model/reference-resolver.js";
 import { generateExecutionId } from "../../sandbox/execution-id.js";
-import { mintSandboxIdentity } from "../../sandbox/identity.js";
 import { isSafeId, reportSessionDerivedDir, toSandboxPath } from "../../workspace/paths.js";
 import { defineTool } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
@@ -55,17 +53,17 @@ const deriveTableInput = z.object({
     output: z.string().min(1),
 });
 /** The synthetic run id and step id of one derivation. Both are constants, and neither names a run row. */
-const DERIVE_RUN_LITERAL = "derive-table";
-const DERIVE_STEP_LITERAL = "derive";
+export const DERIVE_RUN_LITERAL = "derive-table";
+export const DERIVE_STEP_LITERAL = "derive";
 /** The provenance agent id. No agent loop runs in the container, thus this names the derivation pass. */
 const DERIVE_AGENT_ID = "table-deriver";
 /** The exec budget of one derivation. It matches the budget of the value tier. */
-const DERIVATION_DEADLINE_MS = 300_000;
+export const DERIVATION_DEADLINE_MS = 300_000;
 /**
  * The container size of one derivation. A join or a pivot loads each declared input into pandas at one
  * time, thus the container needs the headroom of the value tier.
  */
-const DERIVATION_RESOURCES = { cpu: 2, memoryGb: 8 };
+export const DERIVATION_RESOURCES = { cpu: 2, memoryGb: 8 };
 /** The cap of the script, in bytes. A reshaping script sits far under it, and the command line carries it. */
 const SCRIPT_CAP_BYTES = 64 * 1024;
 /** The cap of the declared inputs. One derivation reads the evidence of a few artifacts, and never a tree. */
@@ -76,12 +74,8 @@ export const DERIVE_INPUT_ENV = "DERIVE_INPUTS";
 export const DERIVE_OUTPUT_ENV = "DERIVE_OUTPUT";
 /** The cap of the failure detail that the tool copies out of the standard error of the script. */
 const STDERR_TAIL_CAP = 2_000;
-/** The awaitExec callback. A derivation reports no live activity, thus the callback drops each event. */
-const noopEmit = () => { };
 /** The line that the agent reads when the composition binds no sandbox rails. */
 const NO_SANDBOX_DETAIL = "the composition gives no sandbox, thus this session cannot derive a table";
-/** The line that the agent reads when the sandbox client awaits under a transport that a turn cannot drive. */
-const CALLBACK_TRANSPORT_DETAIL = "the sandbox of this composition reports through callbacks, which a report turn cannot await, thus it derives no table";
 /**
  * Build the sandbox exec of one derivation. The command runs the script of the agent through `python3 -c`.
  *
@@ -126,58 +120,6 @@ export function describeExecFailure(result) {
     }
     return undefined;
 }
-/**
- * Run one derivation in an ephemeral container, and give the exec result back.
- *
- * The container mounts the analysis tree read-only, and the declared write tail is its one writable mount.
- * Thus the script reads the evidence and it writes into the `derived/` directory of the session and nowhere
- * else. The teardown runs on both paths, thus no machine outlives the call. A teardown fault reaches the log
- * alone, because the work is done.
- *
- * Each seam call is guarded, thus a fault of the sandbox becomes a short detail and the tool keeps its
- * no-throw contract.
- */
-async function runDerivationExec(args) {
-    let sandbox;
-    try {
-        sandbox = await args.client.createSandbox({
-            runId: DERIVE_RUN_LITERAL,
-            stepId: DERIVE_STEP_LITERAL,
-            analysisId: args.analysisId,
-            childWorkflowId: `${DERIVE_RUN_LITERAL}:${args.executionId}`,
-            resources: DERIVATION_RESOURCES,
-            writableTail: args.writableTail,
-        }, mintSandboxIdentity(DERIVE_RUN_LITERAL));
-    }
-    catch (cause) {
-        args.logger.error("the derivation sandbox did not start", args.logger.errorFields(cause));
-        return err("the derivation sandbox did not start");
-    }
-    try {
-        // The tool runs inside one live turn and it never replays, thus the wall clock is the deadline.
-        const deadline = Date.now() + DERIVATION_DEADLINE_MS;
-        await args.client.submitExec(sandbox, buildDerivationExec({
-            script: args.script,
-            execId: args.executionId,
-            workingDir: args.workingDir,
-            inputs: args.inputs,
-            output: args.output,
-        }));
-        return ok(await args.client.awaitExec(sandbox, args.executionId, noopEmit, deadline));
-    }
-    catch (cause) {
-        args.logger.error("the derivation exec did not complete", args.logger.errorFields(cause));
-        return err("the derivation exec did not complete");
-    }
-    finally {
-        try {
-            await args.client.teardown(sandbox);
-        }
-        catch (cause) {
-            args.logger.warn("the derivation sandbox did not tear down", args.logger.errorFields(cause));
-        }
-    }
-}
 /**
  * Make the derivation tool over the session-state gateway, the derivation ledger, and the sandbox rails.
  *
@@ -186,7 +128,7 @@ async function runDerivationExec(args) {
  */
 export function createDeriveTableTool(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("derive-table");
-    const { sandboxClient, runAuthorizer } = deps;
+    const { runDerivation, runAuthorizer } = deps;
     return defineTool({
         id: "derive_table",
         description: "Derive one table from the pinned evidence with a Python script, and pin the result to this session. " +
@@ -209,16 +151,10 @@ export function createDeriveTableTool(deps) {
         execute: async (input, ctx) => {
             // The check runs before every read, thus one clear signal replaces a failure for each attempt.
             // It also narrows the two rails below, thus the exec needs no assertion.
-            if (sandboxClient === undefined || runAuthorizer === undefined) {
+            if (runDerivation === undefined || runAuthorizer === undefined) {
                 logger.warn("the composition gives no sandbox, thus no derivation can run");
                 return ok({ outcome: "unavailable", detail: NO_SANDBOX_DETAIL });
             }
-            // The await of the callback transport is a workflow-body call, and a report turn is not one. An
-            // absent field states nothing, thus it reads as the poll default and it refuses nothing.
-            if (sandboxClient.transport === "callback") {
-                logger.warn("the sandbox client awaits through callbacks, thus no derivation can run in a turn");
-                return ok({ outcome: "unavailable", detail: CALLBACK_TRANSPORT_DETAIL });
-            }
             const opened = await openReportThread(deps.gateway, ctx.session.scope);
             if (opened.isErr()) {
                 return ok({ outcome: "refused", refusal: opened.error });
@@ -304,7 +240,7 @@ export function createDeriveTableTool(deps) {
             let result;
             try {
                 result = await derive({
-                    client: sandboxClient,
+                    runDerivation,
                     derivations: deps.derivations,
                     root,
                     threadId,
@@ -363,8 +299,9 @@ async function derive(args) {
             return { outcome: "exec-failed", detail: `${args.outputName} already holds a file that did not clear, thus this derivation takes a new name` };
         }
     }
-    const executed = await runDerivationExec({
-        client: args.client,
+    // The path mapper refuses a stored path that escapes the root, with a throw. It runs before the try,
+    // thus that refusal stays a throw and it never reads as a fault of the container.
+    const execInput = {
         analysisId: args.analysisId,
         executionId,
         script: args.script,
@@ -372,12 +309,16 @@ async function derive(args) {
         workingDir,
         inputs: args.sources.map((source) => ({ path: toSandboxPath(args.root, args.analysisId, join(args.root, source.path)), hash: source.hash })),
         output: toSandboxPath(args.root, args.analysisId, absolute),
-        logger: args.logger,
-    });
-    if (executed.isErr()) {
-        return { outcome: "exec-failed", detail: executed.error };
+    };
+    let executed;
+    try {
+        executed = await args.runDerivation(execInput);
+    }
+    catch (cause) {
+        args.logger.error("the derivation exec did not complete", { threadId: args.threadId, ...defaultErrorFields(cause) });
+        return { outcome: "exec-failed", detail: "the derivation exec did not complete" };
     }
-    const failure = describeExecFailure(executed.value);
+    const failure = describeExecFailure(executed);
     if (failure !== undefined) {
         return { outcome: "exec-failed", detail: failure };
     }