@inflexa-ai/harness 0.1.1

package/dist/workflows/sandbox-step.js

@@ -0,0 +1,573 @@
+/**
+ * `sandbox-step` — the per-step DBOS child workflow that drives one
+ * sandbox-agent execution and its post-step bookkeeping.
+ *
+ * Structure (each block runs as a `DBOS.runStep` so a crashed workflow
+ * 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.
+ *  3. `runAgent`            — the harness agent loop. Every LLM and tool
+ *                             call inside is its own durableStep.
+ *                             Catches `isBudgetExceeded` and self-cancels
+ *                             via `DBOS.cancelWorkflow(self)` to CANCELLED
+ *                             (resumable, not ERROR).
+ *  4. `generateFileMetadata`— post-step LLM call (chunked, slice-to-length).
+ *  5. `generateStepSummary` — post-step LLM call producing `output/summary.md`.
+ *  6. `reconcile + register`— write artifact manifest entries to cortex_artifacts.
+ *  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.
+ * 10. `mark-terminal`       — write the final status, emit `data-step-activity`
+ *                             onto the parent's DBOS stream.
+ *
+ * The parent owns sibling lifecycle: fail-fast and 402-cascade live on the
+ * parent (`executeAnalysis`). This child only owns its own teardown and
+ * its own self-cancel on 402.
+ */
+import { DBOS, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
+import { insertStepExecution, updateStepExecution } from "../state/index.js";
+import { unwrapOrThrow } from "../lib/result.js";
+import { isBudgetExceeded } from "../loop/budget-exceeded.js";
+import { runAgent } from "../loop/run-agent.js";
+import { durableStep } from "../loop/run-step.js";
+import { activityForTool, applyTreeDelta, isChatDataPart, sandboxTreeDelta } from "../sandbox/sandbox-step-translate.js";
+import { forSubAgent } from "../auth/types.js";
+import { walkStepArtifacts } from "../execution/post-step.js";
+import { collectStepOutputs, generateStepFileMetadata, generateStepSummaryAndWrite, reconcileAndRegisterStepArtifacts, vectorIndexStepOutputs, } from "../execution/post-step-pipeline.js";
+import { mintSandboxIdentity } from "../sandbox/identity.js";
+import { ProvenanceCollector } from "../provenance/collector.js";
+import { createBlockerHolder } from "../tools/sandbox/report-blocker.js";
+/**
+ * Fallback when the plan step omits `timeout`. Plans that need 3-hour runs
+ * declare it explicitly.
+ */
+export const DEFAULT_STEP_TIMEOUT_SECONDS = 3600;
+/**
+ * DBOS message topic the child uses to notify the parent that it is
+ * about to self-cancel because of a 402 budget-exceeded error. The
+ * notification fires BEFORE `DBOS.cancelWorkflow(self)` so the parent's
+ * concurrent recv accumulator records the child id before the child's
+ * terminal state lands. Without it the parent observes
+ * `DBOSWorkflowCancelledError` from `getResult` — a generic message that
+ * `isBudgetExceeded` does NOT match — and misclassifies the failure as
+ * fail-fast, skipping the 402 pause cascade.
+ */
+export const BUDGET_EXCEEDED_TOPIC = "child-budget-exceeded";
+// ── Helpers ───────────────────────────────────────────────────────────
+function nextFunctionIdFactory() {
+    let n = 0;
+    return () => `fn-${(n++).toString(36)}`;
+}
+/**
+ * Stable reconciliation id for a step's reconciling parts
+ * (`data-step-activity`, `data-step-file-tree`). One id per (runId, stepId)
+ * so the run-stream fold collapses every phase transition latest-wins onto
+ * a single frame. The client keys these by `stepId`, but the server fold
+ * keys by part `id`, so the id MUST be unique per step within the run.
+ */
+function stepPartId(kind, runId, stepId) {
+    return `${kind}-${runId}-${stepId}`;
+}
+/**
+ * Map an internal step failure to a user-safe string. Internal detail (file
+ * paths, content hashes, managed-root rejection reasons, stack traces) stays in the pod
+ * logs and in `lastErrorClass`; the surfaces a user sees — the live run panel
+ * (`data-step-activity`), `cortex_step_executions.error` (read by `inspectRun`
+ * and `routes/runs.ts`), and the parent's DAG snapshot / `cortex_runs.error` —
+ * carry only this generic phrase.
+ */
+function userFacingStepFailure(errorClass) {
+    return errorClass === "lineage_attestation" ? "Step results could not be finalized." : "Step failed during execution.";
+}
+// ── The child workflow body ───────────────────────────────────────────
+/**
+ * Register the sandbox-step child workflow with DBOS. Returns the
+ * registered callable so callers can dispatch via `DBOS.startWorkflow`.
+ *
+ * Workflow version stamping is handled globally via `DBOS.setConfig({
+ * applicationVersion })` in `launchDbos` — DBOS records the running
+ * version on every workflow row automatically, so blue/green drains read
+ * `dbos.application_versions` without per-workflow config.
+ */
+export function registerSandboxStep(deps) {
+    return DBOS.registerWorkflow(async (input) => {
+        return runSandboxStepBody(input, deps);
+    }, { name: "sandbox-step" });
+}
+/**
+ * Body extracted so tests can drive it without registering a workflow
+ * (the DBOS calls inside still rely on a workflow context being present).
+ */
+async function runSandboxStepBody(input, deps) {
+    const childWorkflowId = DBOS.workflowID ?? `${input.runId}-${input.stepId}`;
+    // Checkpointed so the value (and every `durationMs` derived from it) replays
+    // identically — a raw `Date.now()` in the workflow body drifts on recovery.
+    const startedAt = await DBOS.now();
+    // (1) mark-running — also persists the level (cortex_step_executions.wave)
+    // and child_workflow_id (cortex_step_executions.child_workflow_id).
+    await DBOS.runStep(async () => {
+        unwrapOrThrow(await insertStepExecution(deps.pool, {
+            runId: input.runId,
+            stepId: input.stepId,
+            analysisId: input.analysisId,
+            wave: input.level,
+            agentId: input.agentId,
+            childWorkflowId,
+        }));
+    }, { name: "mark-running" });
+    // Stamp the sandbox agent's id into provenance so loop events carry
+    // `source.agentId === input.agentId` (the parent's RunSession still reads
+    // "conversation-agent"). `run-agent.ts` builds source from
+    // `session.provenance.agentId`, and billing tags ride the same provenance.
+    const session = forSubAgent(input.runSession, input.agentId);
+    const writePrefix = deps.resolveWritePrefix(input);
+    // One lineage collector per step. The agent loop feeds each exec's
+    // provenance frame into it; post-step registration reads the resulting
+    // input/script edges. Reconstructed deterministically on replay — the
+    // frames it consumes are cached recv outputs and the command strings are
+    // cached LLM tool-use (see the harness-thread-store and harness-durable-runtime specs).
+    const lineageCollector = new ProvenanceCollector({
+        stepId: input.stepId,
+        runId: input.runId,
+    });
+    // (2a) sandbox.mint — checkpoint the machine's identity (name + HMAC secret)
+    // BEFORE it is spawned (see the harness-sandbox-exec spec). Durable-before-create is what makes (2b)
+    // idempotent: a crash between spawn and the spawn checkpoint re-runs (2b)
+    // with the same identity, which adopts the already-created machine instead
+    // of leaking a second one.
+    const identity = await DBOS.runStep(() => Promise.resolve(mintSandboxIdentity(input.runId)), { name: "sandbox.mint" });
+    // (2b) sandbox.create — spawn (or adopt) the machine under the minted
+    // identity. The handle (secret included) is cached so recovery picks the
+    // same machine back up without re-provisioning.
+    const sandboxMeta = {
+        runId: input.runId,
+        stepId: input.stepId,
+        analysisId: input.analysisId,
+        childWorkflowId,
+        image: input.image,
+        extraEnv: input.extraEnv,
+        resources: input.resources,
+    };
+    const sandbox = await DBOS.runStep(() => deps.sandboxClient.createSandbox(sandboxMeta, identity), { name: "sandbox.create" });
+    // 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) runAgent — the harness loop with durableStep.
+    // The step deadline is captured ONCE at step start from the checkpointed
+    // clock so it reproduces on replay — the `awaitExec` recv loop gates on this
+    // absolute deadline, so a raw `Date.now()` here would shift the recorded
+    // `DBOS.recv` sequence on recovery (see the harness-durable-runtime spec). `deadlineMs` is a getter so
+    // 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 blockerHolder = createBlockerHolder();
+    const agent = deps.buildAgent({
+        input,
+        session,
+        sandbox,
+        workflowId: childWorkflowId,
+        stepWritePrefix: writePrefix,
+        nextFunctionId: nextFunctionIdFactory(),
+        deadlineMs: () => stepDeadlineMs,
+        lineageCollector,
+        blockerHolder,
+    });
+    // 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`)
+    // pass through verbatim; orchestration events (`iteration`, `tool-started`,
+    // `tool-finished`) and model-output deltas are wrapped under the
+    // `data-loop-event` envelope so the SSE consumer can route them.
+    //
+    // Every emit is `await`ed in body order (the loop awaits its own emits, and
+    // `awaitExec` awaits its sandbox-event emits), so each body-path
+    // `DBOS.writeStream` lands at a deterministic function-ID on replay
+    // (see the harness-durable-runtime spec) — no fire-and-forget tail racing the next real op for the
+    // counter. `safeEmit` swallows a stream-write failure: a dropped UI frame
+    // is non-fatal and must not fail the step.
+    // Pattern A (fan-in at route): write to the CHILD's own `"events"` stream.
+    // `DBOS.writeStream` is body-only, so cross-workflow writes aren't supported;
+    // the SSE route reads the parent's stream plus every active child's, addressed
+    // by `cortex_step_executions.child_workflow_id`.
+    const emitToParentStream = (part) => DBOS.writeStream("events", part);
+    const safeEmit = async (part) => {
+        try {
+            await emitToParentStream(part);
+        }
+        catch (err) {
+            console.warn(`[sandbox-step] emitToParentStream failed (non-fatal):`, err instanceof Error ? err.message : err);
+        }
+    };
+    // Schema-conformant step-activity emitter — stable id per (runId, stepId)
+    // so the run-stream fold collapses every phase transition latest-wins.
+    const activityId = stepPartId("step-activity", input.runId, input.stepId);
+    const emitActivity = (phase, activity) => safeEmit({
+        type: "data-step-activity",
+        id: activityId,
+        runId: input.runId,
+        stepId: input.stepId,
+        phase,
+        activity,
+    });
+    // Single exit for the two terminal failure paths (agent loop, lineage
+    // attestation). Tears the sandbox down, logs the internal detail for
+    // operators, then persists + emits only a generic phrase and re-raises a
+    // scrubbed error — so the child DB row, the run panel, and the parent's
+    // re-thrown `settled.err.message` (DAG snapshot + `cortex_runs.error`) all
+    // stay free of internal paths/hashes/managed-root jargon. A DBOS cancellation is
+    // control-flow, not a failure — re-raise it verbatim.
+    const failStep = async (errorClass, err) => {
+        if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
+            throw err;
+        await tryTeardown(deps, sandbox);
+        const durationMs = (await DBOS.now()) - startedAt;
+        const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
+        console.error(`[sandbox-step] ${errorClass} failure for ${input.runId}/${input.stepId}: ${detail}`);
+        const safe = userFacingStepFailure(errorClass);
+        await DBOS.runStep(async () => {
+            unwrapOrThrow(await updateStepExecution(deps.pool, input.runId, input.stepId, {
+                status: "failed",
+                durationMs,
+                error: safe,
+                attempts: 1,
+                lastErrorClass: errorClass,
+            }));
+        }, {
+            name: errorClass === "lineage_attestation" ? "mark-failed-attestation" : "mark-failed",
+        });
+        await emitActivity("failed", safe);
+        throw new Error(safe);
+    };
+    // Live per-step file tree. The sandbox executor posts on-change deltas per
+    // exec; the body folds them into one cumulative path set (across every exec
+    // of the step) and emits the FULL tree under a stable per-step reconciling
+    // id — the terminal `walkArtifacts` tree reconciles onto the same id at step
+    // end. Full-tree + reconciling means an observer reconnecting from offset 0
+    // still converges (raw deltas alone would not). REPLAY: the fold is a 1:1
+    // pure function of the checkpointed `awaitExec` recv sequence — do NOT add a
+    // timer/debounce here, that would re-break the harness-durable-runtime spec.
+    const treeFileId = stepPartId("step-file-tree", input.runId, input.stepId);
+    const treeFiles = new Set();
+    const emitFileTree = () => safeEmit({
+        type: "data-step-file-tree",
+        id: treeFileId,
+        runId: input.runId,
+        stepId: input.stepId,
+        files: [...treeFiles].sort().map((path) => ({ path, type: "file" })),
+    });
+    // One translator from sandbox/loop events to the typed per-step parts
+    // consumers render. Add a new sandbox event kind as one case here. `data-step-activity`
+    // / `data-step-file-tree` are what the run side panel reads — raw loop events
+    // and per-exec deltas are not, so the fold is what makes the live activity and
+    // file tree visible during a step.
+    const emit = async (event) => {
+        if (isChatDataPart(event)) {
+            const delta = sandboxTreeDelta(event);
+            if (delta) {
+                applyTreeDelta(treeFiles, delta);
+                await emitFileTree();
+                return;
+            }
+            await safeEmit(event);
+            return;
+        }
+        // Forward the raw orchestration / model-delta event under the loop-event
+        // envelope, and surface each tool call as live step activity.
+        await safeEmit({ type: "data-loop-event", data: { stepId: input.stepId, event } });
+        if (event.type === "tool-started") {
+            await emitActivity("executing", activityForTool(event.name, event.input));
+        }
+    };
+    const initial = [{ role: "user", content: input.prompt }];
+    await emitActivity("executing", `Running ${input.agentId}`);
+    // DBOS exposes no JS AbortSignal that fires on `cancelWorkflow` — cancellation
+    // is enforced at DBOS checkpoint (step) boundaries, not cooperatively in-loop.
+    const neverAbort = new AbortController().signal;
+    let transcript;
+    let finishReason;
+    let hitMaxSteps;
+    try {
+        const agentResult = await runAgent(agent, initial, session, {
+            provider: deps.provider,
+            signal: neverAbort,
+            emit,
+            runStep: durableStep,
+            formatStepName: {
+                llm: (iteration) => `llm:${iteration}`,
+                tool: (toolName, toolUseId) => `tool:${toolName}:${toolUseId}`,
+            },
+            isFatalLoopError: (err) => err instanceof DBOSErrors.DBOSWorkflowCancelledError,
+        });
+        transcript = agentResult.messages;
+        finishReason = agentResult.finish.reason;
+        hitMaxSteps = agentResult.finish.cappedOut;
+    }
+    catch (err) {
+        if (isBudgetExceeded(err)) {
+            // Notify the parent BEFORE self-cancel — DBOSWorkflowCancelledError
+            // surfaced by `getResult` carries a generic message that
+            // `isBudgetExceeded` cannot match, so without this side-channel the
+            // parent classifier falls through to fail-fast and the 402 pause
+            // cascade never fires. Wrapped in `DBOS.runStep` for replay
+            // idempotency (DBOS persists the send under (workflowID, function_id),
+            // a recovered child does not re-send). Failure to send is logged but
+            // swallowed: the worst case is the parent misclassifies the cancel
+            // as fail-fast, which is the pre-fix behaviour and still safe.
+            const errMsg = err instanceof Error ? err.message : String(err);
+            const notification = {
+                childWorkflowId,
+                stepId: input.stepId,
+                error: errMsg,
+            };
+            try {
+                await DBOS.runStep(() => DBOS.send(input.parentWorkflowId, notification, BUDGET_EXCEEDED_TOPIC), { name: "notify-parent-budget-exceeded" });
+            }
+            catch (sendErr) {
+                console.warn(`[sandbox-step] notify-parent-budget-exceeded failed (non-fatal): ${sendErr instanceof Error ? sendErr.message : sendErr}`);
+            }
+            // Self-cancel to CANCELLED so the parent's `getResult` observes the
+            // cancellation and triggers the 402 pause cascade. ERROR is NOT
+            // resumable (NOTES #3); CANCELLED is what `resumeWorkflow` reads.
+            // The subsequent runStep flips the cortex_step_executions row to
+            // canceled and raises `DBOSWorkflowCancelledError` — nothing past
+            // that line executes. The parent's classifier reads the budget
+            // notification from the side-channel set populated above and
+            // observes the cancel terminal state via `getResult`.
+            await DBOS.cancelWorkflow(childWorkflowId);
+            const durationMs = (await DBOS.now()) - startedAt;
+            await DBOS.runStep(async () => {
+                unwrapOrThrow(await updateStepExecution(deps.pool, input.runId, input.stepId, {
+                    status: "canceled",
+                    durationMs,
+                    error: "budget_exceeded",
+                    attempts: 1,
+                    lastErrorClass: "budget_exceeded",
+                }));
+            }, { name: "mark-canceled" });
+            // Unreachable — the runStep above raises DBOSWorkflowCancelledError.
+            throw new Error("unreachable: mark-canceled did not raise", { cause: err });
+        }
+        // Non-resumable failure — tear down, mark failed (scrubbed), re-raise so
+        // the parent's `getResult` sees ERROR and the fail-fast cascade fires.
+        // `failStep` always throws; the outer `throw` is for control-flow analysis.
+        throw await failStep("agent_loop", err);
+    }
+    // Blocker (see the harness-sandbox-agents spec): the agent declared it cannot fulfil the step. A
+    // blocked step has no deliverables — skip the artifact post-step pipeline,
+    // mark `blocked` (carrying the reason), emit the blocked part, and return a
+    // terminal-failure status so the parent's fail-fast cascade fires.
+    const blockerOutcome = blockerHolder.outcome;
+    if (blockerOutcome) {
+        await tryTeardown(deps, sandbox);
+        const durationMs = (await DBOS.now()) - startedAt;
+        await DBOS.runStep(async () => {
+            unwrapOrThrow(await updateStepExecution(deps.pool, input.runId, input.stepId, {
+                status: "blocked",
+                durationMs,
+                error: blockerOutcome.reason,
+                blockedReason: blockerOutcome.reason,
+                attempts: 1,
+                lastErrorClass: "blocked",
+                finishReason,
+                hitMaxSteps,
+            }));
+        }, { name: "mark-blocked" });
+        await safeEmit({
+            type: "data-step-blocked",
+            id: stepPartId("step-blocked", input.runId, input.stepId),
+            runId: input.runId,
+            stepId: input.stepId,
+            agentId: input.agentId,
+            reason: blockerOutcome.reason,
+        });
+        await emitActivity("failed", "Step blocked");
+        return {
+            status: "blocked",
+            durationMs,
+            finishReason,
+            error: blockerOutcome.reason,
+        };
+    }
+    // (4-8) post-step — the body is the explicit composition: walk the artifact
+    // tree once, then thread each stage's typed output into the next. Helpers
+    // run inline (not `DBOS.runStep`-wrapped), so a replay re-executes this
+    // section. Each helper is best-effort (`safeRun*` logs + degrades) so a
+    // single failure never fails the step.
+    const postCtx = {
+        input,
+        session,
+        transcript,
+        writePrefix,
+        sandboxId: sandbox.sandboxId,
+        lineageCollector,
+    };
+    await emitActivity("generating-metadata", "Describing output files");
+    const manifest = await safeRunValue(() => walkStepArtifacts({
+        writePrefix,
+        stepId: input.stepId,
+        runId: input.runId,
+    }), "post-step.walk", []);
+    // The two post-step LLM producers are wrapped in `DBOS.runStep` so their
+    // outputs are checkpointed (see the harness-durable-runtime spec): the conditional terminal emits they
+    // gate (`data-step-summary`, file-tree) stay replay-stable and the billed
+    // LLM calls are not re-issued on recovery. The remaining stages (walk /
+    // reconcile / sync / index) stay inline — a separate follow-up.
+    const metadataEntries = await safeRunValue(() => DBOS.runStep(() => generateStepFileMetadata(deps, postCtx, manifest), {
+        name: "post-step.generate-file-metadata",
+    }), "post-step.metadata", []);
+    await emitActivity("generating-summary", "Summarizing step results");
+    const summary = await safeRunValue(() => DBOS.runStep(() => generateStepSummaryAndWrite(deps, postCtx, manifest), {
+        name: "post-step.generate-step-summary",
+    }), "post-step.summary", undefined);
+    // Lineage attestation (registration + sync) is fail-fast (see the artifact-manifest spec): unlike
+    // the best-effort enrichment stages, a failure here orphans the step's real
+    // outputs, so it fails the step loudly instead of finishing green. Transient
+    // managed-root errors are already retried in the client, so anything thrown here is
+    // persistent — tear down, mark failed, and re-raise so the parent's fail-fast
+    // cascade fires (mirrors the agent-loop failure path).
+    await emitActivity("persisting", "Registering artifacts");
+    let reconciledManifest;
+    try {
+        reconciledManifest = await reconcileAndRegisterStepArtifacts(deps, postCtx, manifest);
+        await deps.artifactRegistry.sync({
+            resourceId: input.analysisId,
+            runId: input.runId,
+            stepId: input.stepId,
+        }, session);
+    }
+    catch (err) {
+        throw await failStep("lineage_attestation", err);
+    }
+    const postArtifacts = {
+        metadataEntries,
+        summary,
+        reconciledManifest,
+    };
+    let stepOutputs;
+    try {
+        stepOutputs = collectStepOutputs(postCtx, postArtifacts);
+    }
+    catch (err) {
+        console.warn(`[sandbox-step] post-step.collect failed (non-fatal):`, err instanceof Error ? err.message : err);
+    }
+    await emitActivity("indexing", "Indexing outputs for search");
+    await safeRun(() => 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" });
+    // (10) mark-terminal + emit.
+    const durationMs = (await DBOS.now()) - startedAt;
+    await DBOS.runStep(async () => {
+        unwrapOrThrow(await updateStepExecution(deps.pool, input.runId, input.stepId, {
+            status: "completed",
+            durationMs,
+            attempts: 1,
+            lastErrorClass: null,
+            finishReason,
+            hitMaxSteps,
+        }));
+    }, { name: "mark-complete" });
+    // Terminal step-detail parts. file-tree + summary + output each get a
+    // stable id per step so the run-stream fold + client both treat them as
+    // one-per-step (file-tree reconciles; summary/output are emitted once).
+    if (stepOutputs) {
+        if (stepOutputs.files.length > 0) {
+            await safeEmit({
+                type: "data-step-file-tree",
+                id: stepPartId("step-file-tree", input.runId, input.stepId),
+                runId: input.runId,
+                stepId: input.stepId,
+                files: stepOutputs.files.map((f) => ({
+                    path: f.path,
+                    size: f.size,
+                    type: "file",
+                })),
+            });
+        }
+        if (stepOutputs.summaryMarkdown.trim().length > 0) {
+            await safeEmit({
+                type: "data-step-summary",
+                id: stepPartId("step-summary", input.runId, input.stepId),
+                runId: input.runId,
+                stepId: input.stepId,
+                agentId: input.agentId,
+                markdown: stepOutputs.summaryMarkdown,
+            });
+        }
+        if (stepOutputs.files.length > 0) {
+            await safeEmit({
+                type: "data-step-output",
+                id: stepPartId("step-output", input.runId, input.stepId),
+                runId: input.runId,
+                stepId: input.stepId,
+                agentId: input.agentId,
+                files: stepOutputs.files.map((f) => ({
+                    path: f.path,
+                    size: f.size,
+                    fileType: f.fileType,
+                    description: f.description,
+                })),
+                artifactCount: stepOutputs.files.length,
+                durationMs,
+                finishReason,
+                hitMaxSteps,
+            });
+        }
+    }
+    await emitActivity("complete", "Step complete");
+    return {
+        status: "complete",
+        durationMs,
+        finishReason,
+        error: null,
+    };
+}
+/**
+ * Best-effort wrapper for non-load-bearing post-step calls. Logs and
+ * swallows non-fatal failures — these are reflected in the step summary
+ * but do not fail the step itself (synthesis/sync/index can be retried).
+ */
+async function safeRun(fn, label) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
+            throw err;
+        console.warn(`[sandbox-step] ${label} failed (non-fatal):`, err instanceof Error ? err.message : err);
+    }
+}
+/**
+ * `safeRun` for a value-returning post-step stage: on a non-fatal failure it
+ * logs and yields `fallback` so the body can thread a safe default downstream
+ * instead of aborting the post-step pipeline.
+ */
+async function safeRunValue(fn, label, fallback) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
+            throw err;
+        console.warn(`[sandbox-step] ${label} failed (non-fatal):`, err instanceof Error ? err.message : err);
+        return fallback;
+    }
+}
+async function tryTeardown(deps, sandbox) {
+    try {
+        await DBOS.runStep(() => deps.sandboxClient.teardown(sandbox), { name: "sandbox.teardown" });
+    }
+    catch (err) {
+        console.warn(`[sandbox-step] teardown failed (non-fatal):`, err instanceof Error ? err.message : err);
+    }
+}

package/dist/workflows/target-assessment/assemblers/index.d.ts

@@ -0,0 +1,5 @@
+export { assembleEntity, assembleTractability, enrichTractabilityModalitiesWithApprovals, type DrugForTractability, reconcileFaersCoverage, assembleDossier, } from "./orchestrator.js";
+export type { TrialOutcomeFilter } from "./trials.js";
+export { assembleLiabilitySummary, isSafetyRelevant, meetsTpmFloor, SAFETY_RELEVANT_ORGANS, REPRODUCTIVE_TOX_TISSUES, REPRODUCTIVE_TOX_TPM_FLOOR, DEFAULT_TPM_FLOOR, aggregateFaersAcrossModulators, aggregateTrialAes, aggregateOffTargetPanel, aggregateClassPrecedent, buildOrganRollup, } from "./safety.js";
+export { deterministicTranslationalCommentary, isClinicalMeasurement, isSelfReference } from "./literature.js";
+export { aggregateTrialOutcomes } from "./trials.js";

package/dist/workflows/target-assessment/assemblers/index.js

@@ -0,0 +1,4 @@
+export { assembleEntity, assembleTractability, enrichTractabilityModalitiesWithApprovals, reconcileFaersCoverage, assembleDossier, } from "./orchestrator.js";
+export { assembleLiabilitySummary, isSafetyRelevant, meetsTpmFloor, SAFETY_RELEVANT_ORGANS, REPRODUCTIVE_TOX_TISSUES, REPRODUCTIVE_TOX_TPM_FLOOR, DEFAULT_TPM_FLOOR, aggregateFaersAcrossModulators, aggregateTrialAes, aggregateOffTargetPanel, aggregateClassPrecedent, buildOrganRollup, } from "./safety.js";
+export { deterministicTranslationalCommentary, isClinicalMeasurement, isSelfReference } from "./literature.js";
+export { aggregateTrialOutcomes } from "./trials.js";