@inflexa-ai/harness 0.26.0 → 0.26.1

package/dist/agents/report-session-agent.d.ts

@@ -26,7 +26,7 @@ import type { Pool } from "pg";
 import type { AuthContext } from "../auth/types.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { AgentDefinition } from "../loop/types.js";
-import type { SandboxClient } from "../sandbox/client.js";
+import type { DeriveTableRunner } from "../tools/report-session/derive-table.js";
 import type { ReportSessionStateStore } from "../state/report-session-state.js";
 import type { EmbeddingProvider } from "../providers/types.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
@@ -65,10 +65,11 @@ export interface ReportSessionAgentDeps {
     /** Derivation ledger -- the derivation tool appends one record for each derived table. */
     readonly derivations: Pick<ReportSessionStateStore, "appendDerivation">;
     /**
-     * Sandbox seam -- the derivation tool runs one ephemeral container for each derived table. Omitted, the
-     * tool reports that the composition gives no sandbox, and it derives nothing.
+     * Derivation-exec seam -- the derivation tool runs one ephemeral container for each derived table, and
+     * the composition realizes this seam over a registered workflow. Omitted, the tool reports that the
+     * composition gives no sandbox, and it derives nothing.
      */
-    readonly sandboxClient?: SandboxClient;
+    readonly runDerivation?: DeriveTableRunner;
     /**
      * Run-authorization seam -- the derivation tool authorizes the exec and revokes on every terminal path.
      * Omitted, the tool derives nothing, the same as an absent sandbox client.

package/dist/agents/report-session-agent.js

@@ -39,7 +39,7 @@ const REPORT_SESSION_MAX_ITERATIONS = 75;
 /** Build the report `AgentDefinition` with every tool bound to its deps. */
 export function createReportSessionAgent(deps) {
     const { model, pool, embedding, workspaceFs, gateway, resolveWorkspaceRoot, store, threads, chrome, eyes, makeResolver, resolvePageAsset, logger } = deps;
-    const { derivations, sandboxClient, runAuthorizer, makeSessionPages, resolvePageUrl } = deps;
+    const { derivations, runDerivation, runAuthorizer, makeSessionPages, resolvePageUrl } = deps;
     const authoring = createReportAuthoringTools(gateway);
     const tools = [
         // The read surface toward the analysis. It roams the tree read-only.
@@ -73,7 +73,7 @@ export function createReportSessionAgent(deps) {
             gateway,
             resolveWorkspaceRoot,
             derivations,
-            ...(sandboxClient ? { sandboxClient } : {}),
+            ...(runDerivation ? { runDerivation } : {}),
             ...(runAuthorizer ? { runAuthorizer } : {}),
             ...(logger ? { logger } : {}),
         }),

package/dist/lib/zod-issues.d.ts

@@ -21,7 +21,9 @@
  *    caller's data; it distinguishes the two modes so the message the model
  *    reads matches the mistake it actually made. When neither mode explains the
  *    string it stays silent, because speculative advice to a model that is
- *    already misdiagnosing is worse than no advice at all.
+ *    already misdiagnosing is worse than no advice at all. It also measures a
+ *    string that broke a maximum length, because the Zod message gives the
+ *    bound and never the length that arrived.
  *  - `repairToolInput` — an **issue-guided** repair: only a path where the
  *    schema wanted an `object` or `array` and found a string is even considered,
  *    so a tool that legitimately declares a `z.string()` field is never touched.
@@ -46,9 +48,12 @@ import type { z } from "zod";
  * said. `input` is the raw value that failed validation — the same value handed
  * to `safeParse` — because the issue alone does not carry the offending value.
  *
- * Fires only for an `invalid_type` issue wanting an `object` or an `array` whose
- * path resolves to a string, and only when that string demonstrably *is* the
- * expected value:
+ * Fires for a `too_big` issue on a string, which yields the length that arrived
+ * and the count to remove.
+ *
+ * Fires otherwise only for an `invalid_type` issue wanting an `object` or an
+ * `array` whose path resolves to a string, and only when that string
+ * demonstrably *is* the expected value:
  *
  *  1. it parses in full as JSON of the expected type → double encoding, and
  *  2. it parses only once a wrapper artifact is stripped → the value is intact

package/dist/lib/zod-issues.js

@@ -21,7 +21,9 @@
  *    caller's data; it distinguishes the two modes so the message the model
  *    reads matches the mistake it actually made. When neither mode explains the
  *    string it stays silent, because speculative advice to a model that is
- *    already misdiagnosing is worse than no advice at all.
+ *    already misdiagnosing is worse than no advice at all. It also measures a
+ *    string that broke a maximum length, because the Zod message gives the
+ *    bound and never the length that arrived.
  *  - `repairToolInput` — an **issue-guided** repair: only a path where the
  *    schema wanted an `object` or `array` and found a string is even considered,
  *    so a tool that legitimately declares a `z.string()` field is never touched.
@@ -55,9 +57,12 @@ const TRAILING_CALL_TAGS = /<\/parameter>\s*(?:<\/invoke>\s*)?$/;
  * said. `input` is the raw value that failed validation — the same value handed
  * to `safeParse` — because the issue alone does not carry the offending value.
  *
- * Fires only for an `invalid_type` issue wanting an `object` or an `array` whose
- * path resolves to a string, and only when that string demonstrably *is* the
- * expected value:
+ * Fires for a `too_big` issue on a string, which yields the length that arrived
+ * and the count to remove.
+ *
+ * Fires otherwise only for an `invalid_type` issue wanting an `object` or an
+ * `array` whose path resolves to a string, and only when that string
+ * demonstrably *is* the expected value:
  *
  *  1. it parses in full as JSON of the expected type → double encoding, and
  *  2. it parses only once a wrapper artifact is stripped → the value is intact
@@ -70,6 +75,9 @@ const TRAILING_CALL_TAGS = /<\/parameter>\s*(?:<\/invoke>\s*)?$/;
  * `undefined` rather than throwing.
  */
 export function hintForZodIssue(issue, input) {
+    const overLength = hintForOverLongString(issue, input);
+    if (overLength !== undefined)
+        return overLength;
     const expected = repairableExpectation(issue);
     if (expected === undefined)
         return undefined;
@@ -123,6 +131,29 @@ export function repairToolInput(input, error) {
         return undefined;
     }
 }
+/**
+ * The measurement of a string that broke its maximum length, or `undefined` for
+ * any other issue.
+ *
+ * A Zod `too_big` message names the bound and stops there. A model reasons in
+ * tokens, thus it cannot count the characters that it sent, and it cuts by
+ * guess. Each guess costs one rejected call. The hint gives the two numbers
+ * that end the guess: the length that arrived, and the count to remove.
+ */
+function hintForOverLongString(issue, input) {
+    if (issue.code !== "too_big" || issue.origin !== "string")
+        return undefined;
+    const value = resolvePath(input, issue.path);
+    if (typeof value !== "string")
+        return undefined;
+    const maximum = Number(issue.maximum);
+    if (!Number.isFinite(maximum))
+        return undefined;
+    const excess = value.length - maximum;
+    if (excess <= 0)
+        return undefined;
+    return `This argument arrived with ${value.length} characters. Remove at least ${excess} characters, and send it again.`;
+}
 /** The `object`/`array` expectation of an `invalid_type` issue, if it has one. */
 function repairableExpectation(issue) {
     if (issue.code !== "invalid_type")

package/dist/runtime/assemble.d.ts

@@ -28,6 +28,8 @@ import { type SandboxStepDeps, type SandboxStepInput, type SandboxStepResult } f
 import { type ExecuteTargetAssessmentDeps, type ExecuteTargetAssessmentInput, type ExecuteTargetAssessmentResult } from "../workflows/execute-target-assessment.js";
 import { type DataProfileDeps, type DataProfileWorkflowInput } from "../tasks/data-profile.js";
 import { type ExtractValuesResult, type ExtractValuesWorkflowInput } from "../tasks/extract-values.js";
+import type { DeriveTableExecInput } from "../tools/report-session/derive-table.js";
+import type { ExecResult } from "../sandbox/types.js";
 import { type CitationResolverConfig } from "../citations/resolve.js";
 import type { CitationResolver } from "../citations/types.js";
 import type { AuthContext } from "../auth/types.js";
@@ -61,6 +63,7 @@ export interface RegisteredWorkflows {
     readonly executeTargetAssessment: (input: ExecuteTargetAssessmentInput) => Promise<ExecuteTargetAssessmentResult>;
     readonly dataProfile: (input: DataProfileWorkflowInput) => Promise<void>;
     readonly extractValues: (input: ExtractValuesWorkflowInput) => Promise<ExtractValuesResult>;
+    readonly deriveTableExec: (input: DeriveTableExecInput) => Promise<ExecResult>;
 }
 /**
  * Conversation-agent deps minus the workflow callable, the resource policy, the

package/dist/runtime/assemble.js

@@ -26,6 +26,7 @@ import { registerSandboxStep } from "../workflows/sandbox-step.js";
 import { registerExecuteTargetAssessment, } from "../workflows/execute-target-assessment.js";
 import { registerDataProfileWorkflow } from "../tasks/data-profile.js";
 import { bindExtractionTrigger, createExtractionArm, registerExtractValuesWorkflow, } from "../tasks/extract-values.js";
+import { registerDeriveTableExecWorkflow, triggerDeriveTableExec } from "../tasks/derive-table-exec.js";
 import { createCitationResolver } from "../citations/resolve.js";
 import { createThreadStore } from "../memory/thread-store.js";
 import { createArtifactReadStore, createProductionResolver } from "../report-model/production-resolver.js";
@@ -95,6 +96,12 @@ export function assembleCoreRuntime(deps) {
         runAuthorizer: wf.dataProfile.runAuthorizer,
         ...(wf.dataProfile.logger ? { logger: wf.dataProfile.logger } : {}),
     });
+    // A session derivation runs its container here and not in the turn. The await of an exec is a
+    // workflow-body call under the callback transport, thus the tool starts this workflow and awaits it.
+    const deriveTableExec = registerDeriveTableExecWorkflow({
+        sandboxClient: wf.dataProfile.sandboxClient,
+        ...(wf.dataProfile.logger ? { logger: wf.dataProfile.logger } : {}),
+    });
     // The session runtime binds the per-session state to the thread behind the
     // tool boundary, thus one instance serves every report thread. It comes before
     // the conversation agent, because `start_report_session` takes its anchor
@@ -159,7 +166,7 @@ export function assembleCoreRuntime(deps) {
         // and the same run authorizer. Thus a session derivation and an extraction run on
         // one substrate, and neither one mints a run of the analysis.
         derivations: reportSession.derivations,
-        sandboxClient: wf.dataProfile.sandboxClient,
+        runDerivation: (input) => triggerDeriveTableExec(deriveTableExec, input),
         runAuthorizer: conversation.runAuthorizer,
         makeResolver: makeReportResolver,
         ...(eyes ? { eyes } : {}),
@@ -188,6 +195,7 @@ export function assembleCoreRuntime(deps) {
             executeTargetAssessment,
             dataProfile,
             extractValues,
+            deriveTableExec,
         },
         citationResolver,
     };

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/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 };
     }

package/dist/tools/start-report-session.js

@@ -27,16 +27,20 @@ import { defineTool } from "./define-tool.js";
  * message row, thus the schema holds no unbounded string out of the store.
  *
  * The description caps the brief at approximately 2000 tokens, and a token is
- * about four characters. Thus the five bounds sum to 8000 characters, and the
+ * about four characters. Thus the five bounds sum to 8200 characters, and the
  * widest brief that the schema admits still meets the cap that the agent reads.
  *
  * The share of each field follows its role. `audience` names one reader, thus a
  * phrase is enough. `objective` and `angle` carry a sentence or two. Each
  * optional field carries a list of items, thus it takes the largest share.
+ *
+ * The bound of `audience` holds 400 characters, not the 200 that the phrase
+ * alone needs. A model counts tokens, not characters, thus a tight bound gives
+ * a rejected call and a retry.
  */
 const BRIEF_MAX = {
     objective: 1500,
-    audience: 200,
+    audience: 400,
     angle: 1500,
     exclusions: 2400,
     openQuestions: 2400,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.26.0",
+    "version": "0.26.1",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",