@inflexa-ai/harness 0.1.1 → 0.3.0

package/dist/workflows/execute-analysis.js

@@ -20,6 +20,10 @@
  *     - dispatch every `scheduleReady(plan, completedSet, startedSet)` via
  *       `DBOS.startWorkflow` with deterministic child id
  *       `"${parent.workflowID}-${N}"` (N is the step's stable index)
+ *     - compose each child's seed prompt HERE, at dispatch (`composeStepSeed`,
+ *       inside a durable step): the moment a step is dispatched is the first
+ *       moment its dependencies' results exist, so this is the only place the
+ *       seed can name them
  *     - each child input is `forStep(input.runSession, stepId)` for the
  *       session field
  *     - emit `data-dag-state` (reconciling by id) on every dispatch +
@@ -53,10 +57,13 @@ import { DBOS } from "@dbos-inc/dbos-sdk";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { forStep } from "../auth/types.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 import { unwrapOrThrow } from "../lib/result.js";
-import { RunDedupCollisionError, countArtifactsForRun, queryActiveRun, seedStepExecutions, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, } from "../state/index.js";
+import { RunDedupCollisionError, countArtifactsForRun, loadDataProfileStatus, queryActiveRun, queryStepArtifactPaths, seedStepExecutions, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, } from "../state/index.js";
 import { isBudgetExceeded } from "../loop/budget-exceeded.js";
-import { runDir } from "../workspace/paths.js";
+import { loadStepSummariesFromDisk } from "../execution/run-synthesis.js";
+import { MAX_UPSTREAM_ARTIFACTS, composeStepBriefing } from "../prompts/briefing.js";
+import { runDir, runStepDir, stepSubdir, stepWritePrefix, toSandboxPath } from "../workspace/paths.js";
 import { isChatDataPart } from "../sandbox/sandbox-step-translate.js";
 import { synthesizeRun } from "../app/synthesize-run.js";
 import { computeTopologicalLevels, scheduleReady, validatePlanDag } from "./execute-analysis-scheduler.js";
@@ -75,23 +82,25 @@ function emitStreamPart(part) {
  * host's own ledger, not here.
  */
 function emitProvenanceGuarded(deps, event) {
+    const logger = (deps.logger ?? createNoopLogger()).named("executeAnalysis");
     if (!deps.emitProvenance)
         return;
     try {
         deps.emitProvenance(event);
     }
     catch (err) {
-        console.error(`[executeAnalysis] emitProvenance threw for run ${event.runId} (event=${event.type}):`, err);
+        logger.error("emitProvenance threw", { runId: event.runId, event: event.type, ...logger.errorFields(err) });
     }
 }
 /**
  * Project the sandbox-step input handed to each child. The parent owns the
- * level computation; the rest comes from `ExecuteAnalysisInput`. The body
- * fills in `runSession` via `forStep` after this returns. Exported for the
+ * level computation and the seed (`prompt`, composed by `composeStepSeed` at
+ * dispatch); the rest comes from `ExecuteAnalysisInput`. The body fills in
+ * `runSession` via `forStep` after this returns. Exported for the
  * projection/timeout-propagation tests.
  */
 export function buildChildInput(args) {
-    const { input, stepId, level, runId, workflowId } = args;
+    const { input, stepId, level, runId, workflowId, prompt } = args;
     const resources = input.resourcesByStepId[stepId];
     if (!resources) {
         throw new Error(`executeAnalysis: step "${stepId}" missing from resourcesByStepId — every step must declare resources`);
@@ -102,12 +111,100 @@ export function buildChildInput(args) {
         stepId,
         agentId: input.agentByStepId[stepId] ?? "scientific-executor",
         level,
-        prompt: input.promptByStepId[stepId] ?? "",
+        prompt,
         parentWorkflowId: workflowId,
         resources,
         timeoutSeconds: input.timeoutByStepId?.[stepId],
     };
 }
+// ── Seed composition (at dispatch, not at plan submission) ────────────
+/**
+ * Compose one step's seed — the user-content message its agent opens on.
+ *
+ * The composition point is the design: the scheduler calls this at the instant
+ * it dispatches a step, which is the first instant at which every one of that
+ * step's dependencies has *finished* and written its results down. A seed
+ * rendered any earlier (at plan submission, say) cannot mention them, and the
+ * agent is left to rediscover its own upstream.
+ *
+ * Everything read here is durable state written by an already-settled child
+ * (`output/summary.md`, `cortex_artifacts`) or by the profiler
+ * (`cortex_analysis_state`) — never live in-flight state, which would not
+ * reproduce.
+ *
+ * REPLAY: the caller wraps this in a `DBOS.runStep`, so the composed string is
+ * checkpointed and a replay returns it verbatim — the DB and disk are not read
+ * again and cannot drift the seed under a recovered run. Never call it
+ * unwrapped from the workflow body.
+ */
+export async function composeStepSeed(args) {
+    const { input, stepId, runId, deps } = args;
+    const step = input.planStepById[stepId];
+    if (!step) {
+        throw new Error(`executeAnalysis: step "${stepId}" missing from planStepById — every step must carry its plan data`);
+    }
+    const analysisId = input.analysisId;
+    const workspaceRoot = deps.resolveWorkspaceRoot(analysisId);
+    // The paths the agent actually sees: the tree is bind-mounted at
+    // `/{analysisId}`, and the step's writable directory is its cwd. Derived
+    // through the same helpers the sandbox mount and the mutate tools use, so
+    // the seed cannot disagree with the container about where anything is.
+    const workspace = {
+        analysisRoot: `/${analysisId}`,
+        workingDir: toSandboxPath(workspaceRoot, analysisId, stepWritePrefix({ workspaceRoot, runId, stepId })),
+    };
+    // A DB failure here throws (house rules): a swallowed error would be frozen
+    // into the checkpointed seed and served to every replay of this step.
+    const profile = unwrapOrThrow(await loadDataProfileStatus(deps.pool, analysisId));
+    const upstream = await collectUpstreamHandoffs({
+        analysisId,
+        runId,
+        workspaceRoot,
+        dependsOn: step.depends_on,
+        agentByStepId: input.agentByStepId,
+        pool: deps.pool,
+    });
+    return composeStepBriefing({
+        step,
+        workspace,
+        profile: profile?.result ?? null,
+        upstream,
+    });
+}
+/**
+ * Gather what each completed dependency produced. Dependency order is the
+ * plan's declared `depends_on` order — deterministic, so the seed is stable.
+ *
+ * A dependency that wrote no summary is omitted rather than blocking the
+ * dispatch (`loadStepSummariesFromDisk` skips a missing file): a step that
+ * completed without a summary has nothing to hand off, and waiting for one that
+ * will never arrive would deadlock the run.
+ */
+async function collectUpstreamHandoffs(args) {
+    const { analysisId, runId, workspaceRoot, dependsOn, agentByStepId, pool } = args;
+    if (dependsOn.length === 0)
+        return [];
+    const summaries = await loadStepSummariesFromDisk({
+        workspaceRoot,
+        runId,
+        completedSteps: dependsOn,
+        agentByStepId,
+    });
+    const handoffs = [];
+    for (const summary of summaries) {
+        const outputDir = stepSubdir(runStepDir(runId, summary.stepId), "output");
+        const artifacts = await queryStepArtifactPaths(pool, analysisId, runId, summary.stepId, MAX_UPSTREAM_ARTIFACTS);
+        handoffs.push({
+            stepId: summary.stepId,
+            agentId: summary.agentId,
+            summaryMarkdown: summary.markdown,
+            summaryPath: `/${analysisId}/${outputDir}/summary.md`,
+            outputDir: `/${analysisId}/${outputDir}`,
+            artifacts: artifacts.map((a) => `/${analysisId}/${a.path}`),
+        });
+    }
+    return handoffs;
+}
 /**
  * Run-level literature-grounded synthesis (no sandbox). Returns the
  * quick-display findings for the run-completed card; empty when synthesis is
@@ -166,6 +263,7 @@ export function registerExecuteAnalysis(deps) {
  * (the DBOS calls inside still rely on a workflow context being present).
  */
 export async function runExecuteAnalysisBody(input, deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("executeAnalysis").with({ analysisId: input.analysisId });
     // (0) Validate up-front — no side effects yet, so a malformed plan does
     // NOT leak a runId, run authorization, or running charge.
     validatePlanDag(input.steps);
@@ -249,7 +347,7 @@ export async function runExecuteAnalysisBody(input, deps) {
         }
         catch (err) {
             synthesisError = err;
-            console.error(`[executeAnalysis] synthesizeFindings failed for run ${runId} — failing the run:`, err instanceof Error ? err.message : err);
+            logger.error("synthesizeFindings failed — failing the run", { runId, ...logger.errorFields(err) });
         }
     }
     // (6) collectAndComplete — terminal block. Runs on EVERY path. When synthesis
@@ -416,12 +514,18 @@ async function runSchedulerLoop(args) {
         for (const stepId of admit) {
             const idx = stepIndexById.get(stepId);
             const childWorkflowId = `${workflowId}-${idx}`;
+            // Compose the seed HERE — the dependencies of `stepId` are all in
+            // `completed`, so this is the first (and only) moment their results
+            // can be named. Checkpointed so a replay re-dispatches the child
+            // with a byte-identical prompt instead of re-reading the DB/disk.
+            const prompt = await DBOS.runStep(() => composeStepSeed({ input, stepId, runId, deps }), { name: `compose-step-seed:${stepId}` });
             const baseChildInput = buildChildInput({
                 input,
                 stepId,
                 level: levels.get(stepId) ?? 0,
                 runId,
                 workflowId,
+                prompt,
             });
             const childInput = {
                 ...baseChildInput,
@@ -592,6 +696,7 @@ async function cancelInFlight(inFlight, cause, canceledByParent) {
 }
 async function collectAndComplete(args) {
     const { input, runId, workflowId, startedAtMs, completed, failed, canceled, budgetExceeded, failureReason, forceFailed, deps } = args;
+    const logger = (deps.logger ?? createNoopLogger()).named("executeAnalysis").with({ runId, analysisId: input.analysisId });
     const status = forceFailed
         ? "failed"
         : deriveFinalStatus({
@@ -634,7 +739,7 @@ async function collectAndComplete(args) {
         }, { name: "persist-final-status" });
     }
     catch (err) {
-        console.error(`[executeAnalysis] persist-final-status failed for run ${runId} (status=${status}):`, err);
+        logger.error("persist-final-status failed", { status, ...logger.errorFields(err) });
     }
     // Sweep never-started steps to `skipped` — but ONLY on genuinely-terminal
     // paths. The gate is the BRANCH, not the written run status: the resumable
@@ -648,7 +753,7 @@ async function collectAndComplete(args) {
             }, { name: "sweep-pending-steps" });
         }
         catch (err) {
-            console.error(`[executeAnalysis] sweep-pending-steps failed for run ${runId}:`, err);
+            logger.error("sweep-pending-steps failed", logger.errorFields(err));
         }
     }
     // A forced failure (synthesis threw) is terminal, not a resumable budget
@@ -660,7 +765,7 @@ async function collectAndComplete(args) {
             }, { name: "suspend-analysis" });
         }
         catch (err) {
-            console.error(`[executeAnalysis] suspend-analysis failed for run ${runId}:`, err);
+            logger.error("suspend-analysis failed", logger.errorFields(err));
         }
     }
     try {
@@ -672,7 +777,7 @@ async function collectAndComplete(args) {
         }), { name: "close-running-charge" });
     }
     catch (err) {
-        console.error(`[executeAnalysis] closeRunningCharge failed for run ${runId} (reason=${chargeReason}):`, err);
+        logger.error("closeRunningCharge failed", { chargeReason, ...logger.errorFields(err) });
     }
     // Revoke the run authorization for the terminal run state. Ownership
     // defaults to true for inputs persisted before the field existed (a
@@ -685,7 +790,7 @@ async function collectAndComplete(args) {
         await DBOS.runStep(() => deps.runAuthorizer.revoke(authorization, revokeReason), { name: "revoke-run-auth" });
     }
     catch (err) {
-        console.error(`[executeAnalysis] revokeRunAuthorization failed for run ${runId} (reason=${revokeReason}):`, err);
+        logger.error("revokeRunAuthorization failed", { revokeReason, ...logger.errorFields(err) });
     }
     // The `run_completed` provenance was already emitted above (before the status write, to
     // beat the CLI's poll-and-shutdown). These branches only fan out the UI stream part, whose

package/dist/workflows/execute-target-assessment.d.ts

@@ -34,6 +34,7 @@ import type { Pool } from "pg";
 import { z } from "zod";
 import type { RunSession } from "../auth/types.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
+import type { Logger } from "../lib/logger.js";
 import type { AgentChat } from "../providers/types.js";
 import { TargetAssessmentInputSchema } from "./target-assessment/schemas.js";
 import { type ProgressPhase } from "./target-assessment/progress.js";
@@ -69,6 +70,8 @@ export interface ExecuteTargetAssessmentResult {
     readonly bytes: number;
 }
 export interface ExecuteTargetAssessmentDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly pool: Pool;
     /** Run-authorization seam — the terminal path revokes through `revoke`. */
     readonly runAuthorizer: RunAuthorizer;

package/dist/workflows/execute-target-assessment.js

@@ -33,6 +33,7 @@
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { z } from "zod";
 import { forSubAgent } from "../auth/types.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { resolveTarget } from "../tools/lib/identifier-resolver.js";
 import { TargetAssessmentInputSchema } from "./target-assessment/schemas.js";
@@ -111,6 +112,7 @@ export function registerExecuteTargetAssessment(deps) {
  * (the DBOS calls inside still rely on a workflow context being present).
  */
 export async function runExecuteTargetAssessmentBody(input, deps) {
+    const logger = (deps.logger ?? createNoopLogger()).with({ assessmentId: input.assessmentId });
     // (§6.1) Outermost try/finally — every termination path dispatches the
     // matching terminal handler. Phase 0 throws are caught here; every
     // other phase wraps its body in coverage envelopes and does not throw.
@@ -137,7 +139,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
         // (§5.3, §6.3) Phase 0 — target resolution. The only legitimate throw
         // site. On throw, the catch below records `phase0Error` and the
         // terminal block dispatches `markFailed({kind: "target-unresolved"})`.
-        await emitProgress(deps.pool, input.assessmentId, "resolving");
+        await emitProgress(deps.pool, logger, input.assessmentId, "resolving");
         const resolved = await DBOS.runStep(async () => {
             const r = await resolveTarget(input.target);
             return {
@@ -154,7 +156,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
         // returns the cached envelope. The per-collector run functions emit
         // different bundle shapes; the union is widened to `unknown` here
         // and `Phase1Bundle` is reconstructed by manifest key below.
-        await emitProgress(deps.pool, input.assessmentId, "collecting");
+        await emitProgress(deps.pool, logger, input.assessmentId, "collecting");
         const manifest = COLLECTOR_MANIFEST;
         const collectorCtx = { ncbiApiKey: deps.ncbiApiKey };
         const collectorPairs = await Promise.all(manifest.map((entry) => DBOS.runStep(() => entry.run(resolved, collectorCtx), {
@@ -185,7 +187,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
         // (§5.5, §5.11) Phase 2 — decisions. Lazy billing resolution happens
         // inside the chat provider's closure (TA-aware provider in §12). The
         // session carries the `billingContextId` the provider reads from.
-        await emitProgress(deps.pool, input.assessmentId, "deciding");
+        await emitProgress(deps.pool, logger, input.assessmentId, "deciding");
         const decisionSession = buildSession(input, "ta-decisions");
         const [modulatorRes, drugsRes] = await Promise.all([
             modulatorTriage(phase1, {
@@ -226,7 +228,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
         // (§5.6) Phase 3 — fan-out blocks. Each block iterates items via
         // Promise.all over DBOS.runStep; `withHost` semaphores inside each
         // item function cap concurrency to 4 per host.
-        await emitProgress(deps.pool, input.assessmentId, "fanning_out");
+        await emitProgress(deps.pool, logger, input.assessmentId, "fanning_out");
         const triage = phase2.decisions.modulatorTriage;
         const triageShortlist = triage.coverage === "available"
             ? triage.data.shortlist.map((m) => ({
@@ -287,7 +289,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
             },
         };
         // (§5.7) Phase 4 — deterministic assembly. Single DBOS step.
-        await emitProgress(deps.pool, input.assessmentId, "assembling");
+        await emitProgress(deps.pool, logger, input.assessmentId, "assembling");
         const phase4 = await DBOS.runStep(() => phase4Assemble(deps.pool, phase3), { name: "ta-phase4-assemble" });
         // (§5.8-pre) Approval-precedent grounding — one deterministic openFDA
         // lookup, rendered to markdown and injected into every synthesis prompt.
@@ -301,14 +303,14 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
                     result = await fetchApprovalPrecedents({ indication });
                 }
                 catch (err) {
-                    console.warn(`[ta-approval-precedents] openFDA lookup failed for "${indication}": ${err instanceof Error ? err.message : err}`);
+                    logger.named("ta-approval-precedents").warn("openFDA lookup failed", { indication, ...logger.errorFields(err) });
                     result = null;
                 }
             }
             return renderApprovalPrecedents(indication, result);
         }, { name: "ta-approval-precedents" });
         // (§5.8) Phase 5 — three per-section syntheses in parallel.
-        await emitProgress(deps.pool, input.assessmentId, "synthesizing");
+        await emitProgress(deps.pool, logger, input.assessmentId, "synthesizing");
         const synthesisDeps = (agentId) => ({
             chatProvider: deps.chatProvider,
             session: { ...buildSession(input, agentId) },
@@ -343,6 +345,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
         // and returns the persisted-shape bundle. Schema/derived violations
         // throw and the terminal handler dispatches to `markFailed`.
         const persisted = await DBOS.runStep(() => phase5Persist({
+            logger,
             assessmentId: input.assessmentId,
             phase4Dossier: phase4.dossier,
             phase2,
@@ -390,10 +393,10 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
             await DBOS.runStep(async () => unwrapOrThrow(await setDossier(deps.pool, input.assessmentId, dossierForPersist)), {
                 name: "ta-terminal-completed",
             });
-            await emitProgress(deps.pool, input.assessmentId, "completed");
+            await emitProgress(deps.pool, logger, input.assessmentId, "completed");
         }
         catch (err) {
-            console.error(`[ta-terminal] setDossier failed for ${input.assessmentId}: ${err instanceof Error ? err.message : err}`);
+            logger.named("ta-terminal").error("setDossier failed", logger.errorFields(err));
         }
         await revokeRunAuthorizationSafe(deps, authorization, "target-assessment-completed");
         recordTerminalReason("completed");
@@ -409,7 +412,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
             kind: "target-unresolved",
             message: phase0Error instanceof Error ? phase0Error.message : String(phase0Error),
         })), { name: "ta-terminal-failed-resolve" });
-        await emitProgress(deps.pool, input.assessmentId, "failed");
+        await emitProgress(deps.pool, logger, input.assessmentId, "failed");
         await revokeRunAuthorizationSafe(deps, authorization, "target-assessment-failed");
         recordTerminalReason("target-unresolved");
         return {
@@ -425,7 +428,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
             message: schemaViolation.message,
             details: schemaViolation.issues,
         })), { name: "ta-terminal-failed-schema" });
-        await emitProgress(deps.pool, input.assessmentId, "failed");
+        await emitProgress(deps.pool, logger, input.assessmentId, "failed");
         await revokeRunAuthorizationSafe(deps, authorization, "target-assessment-failed");
         recordTerminalReason("schema-violation");
         return {
@@ -440,7 +443,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
             kind: "derived-invariant-violation",
             message: derivedViolation.message,
         })), { name: "ta-terminal-failed-derived" });
-        await emitProgress(deps.pool, input.assessmentId, "failed");
+        await emitProgress(deps.pool, logger, input.assessmentId, "failed");
         await revokeRunAuthorizationSafe(deps, authorization, "target-assessment-failed");
         recordTerminalReason("derived-invariant-violation");
         return {
@@ -459,7 +462,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
             name: "ta-terminal-drain-marker",
         }).catch(() => null);
         await DBOS.runStep(async () => unwrapOrThrow(await markAssessmentSuspended(deps.pool, input.assessmentId)), { name: "ta-terminal-suspended" });
-        await emitProgress(deps.pool, input.assessmentId, "suspended");
+        await emitProgress(deps.pool, logger, input.assessmentId, "suspended");
         await revokeRunAuthorizationSafe(deps, authorization, "target-assessment-canceled");
         const workflowId = DBOS.workflowID;
         if (workflowId) {
@@ -485,7 +488,7 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
             kind: "unexpected-throw",
             message: unexpectedError instanceof Error ? unexpectedError.message : String(unexpectedError),
         })), { name: "ta-terminal-failed-unexpected" });
-        await emitProgress(deps.pool, input.assessmentId, "failed");
+        await emitProgress(deps.pool, logger, input.assessmentId, "failed");
         await revokeRunAuthorizationSafe(deps, authorization, "target-assessment-failed");
         recordTerminalReason("unexpected-throw");
         return {
@@ -514,13 +517,14 @@ export async function runExecuteTargetAssessmentBody(input, deps) {
  * aborted by a transient revoke failure.
  */
 async function revokeRunAuthorizationSafe(deps, authorization, reason) {
+    const logger = (deps.logger ?? createNoopLogger()).named("execute-target-assessment");
     try {
         await DBOS.runStep(() => deps.runAuthorizer.revoke(authorization, reason), {
             name: `ta-revoke-run-auth:${reason}`,
         });
     }
     catch (err) {
-        console.warn(`[execute-target-assessment] revokeRunAuthorization (${reason}) failed:`, err instanceof Error ? err.message : err);
+        logger.warn("revokeRunAuthorization failed", { reason, ...logger.errorFields(err) });
     }
 }
 // Re-export the canonical TA input schema (consumers and the managed root

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

@@ -27,6 +27,7 @@
  * its own self-cancel on 402.
  */
 import type { Pool } from "pg";
+import type { Logger } from "../lib/logger.js";
 import type { AgentDefinition, LoopMessage } from "../loop/types.js";
 import type { AgentChat, EmbeddingProvider } from "../providers/types.js";
 import { type RunSession } from "../auth/types.js";
@@ -183,6 +184,14 @@ export interface SandboxAgentBuildContext {
  */
 export interface SandboxStepDeps {
     readonly pool: Pool;
+    /**
+     * Operational logging seam. Omit it and the body falls back to a no-op —
+     * but a failed step's cause is written here and NOWHERE else (`failStep`
+     * scrubs the error before it reaches the DB row, the run panel, or the
+     * parent's re-raise), so an embedder that wires nothing gives up its only
+     * account of why a step died.
+     */
+    readonly logger?: Logger;
     /** Non-streaming chat — drives the agent loop + the post-step sub-agents. */
     readonly provider: AgentChat;
     /** Write-side embedder for the post-step vector index. */

package/dist/workflows/sandbox-step.js

@@ -28,6 +28,7 @@
  */
 import { DBOS, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
 import { insertStepExecution, updateStepExecution } from "../state/index.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { isBudgetExceeded } from "../loop/budget-exceeded.js";
 import { runAgent } from "../loop/run-agent.js";
@@ -101,6 +102,14 @@ export function registerSandboxStep(deps) {
  * (the DBOS calls inside still rely on a workflow context being present).
  */
 async function runSandboxStepBody(input, deps) {
+    // Step coordinates bind once — every record below carries them without each
+    // call site restating them. REPLAY: a recovered workflow re-executes this body
+    // and re-emits its records, so a reader dedups by (runId, stepId), not by count.
+    const logger = (deps.logger ?? createNoopLogger()).named("sandbox-step").with({
+        runId: input.runId,
+        stepId: input.stepId,
+        agentId: input.agentId,
+    });
     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.
@@ -206,7 +215,7 @@ async function runSandboxStepBody(input, deps) {
             await emitToParentStream(part);
         }
         catch (err) {
-            console.warn(`[sandbox-step] emitToParentStream failed (non-fatal):`, err instanceof Error ? err.message : err);
+            logger.warn("emitToParentStream failed (non-fatal)", logger.errorFields(err));
         }
     };
     // Schema-conformant step-activity emitter — stable id per (runId, stepId)
@@ -230,10 +239,15 @@ async function runSandboxStepBody(input, deps) {
     const failStep = async (errorClass, err) => {
         if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
             throw err;
-        await tryTeardown(deps, sandbox);
+        await tryTeardown(logger, 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}`);
+        // The scrub below is deliberate and load-bearing, which makes this record
+        // the ONLY account of why the step died — the thrown error carries just the
+        // generic phrase, so nothing downstream can reconstruct the cause.
+        logger.error("step failure", {
+            errorClass,
+            ...logger.errorFields(err),
+        });
         const safe = userFacingStepFailure(errorClass);
         await DBOS.runStep(async () => {
             unwrapOrThrow(await updateStepExecution(deps.pool, input.runId, input.stepId, {
@@ -334,7 +348,9 @@ async function runSandboxStepBody(input, deps) {
                 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}`);
+                logger.warn("notify-parent-budget-exceeded failed (non-fatal)", {
+                    ...logger.errorFields(sendErr),
+                });
             }
             // Self-cancel to CANCELLED so the parent's `getResult` observes the
             // cancellation and triggers the 402 pause cascade. ERROR is NOT
@@ -369,7 +385,7 @@ async function runSandboxStepBody(input, deps) {
     // terminal-failure status so the parent's fail-fast cascade fires.
     const blockerOutcome = blockerHolder.outcome;
     if (blockerOutcome) {
-        await tryTeardown(deps, sandbox);
+        await tryTeardown(logger, deps, sandbox);
         const durationMs = (await DBOS.now()) - startedAt;
         await DBOS.runStep(async () => {
             unwrapOrThrow(await updateStepExecution(deps.pool, input.runId, input.stepId, {
@@ -413,7 +429,7 @@ async function runSandboxStepBody(input, deps) {
         lineageCollector,
     };
     await emitActivity("generating-metadata", "Describing output files");
-    const manifest = await safeRunValue(() => walkStepArtifacts({
+    const manifest = await safeRunValue(logger, () => walkStepArtifacts({
         writePrefix,
         stepId: input.stepId,
         runId: input.runId,
@@ -423,11 +439,11 @@ async function runSandboxStepBody(input, deps) {
     // 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), {
+    const metadataEntries = await safeRunValue(logger, () => 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), {
+    const summary = await safeRunValue(logger, () => 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
@@ -459,10 +475,10 @@ async function runSandboxStepBody(input, deps) {
         stepOutputs = collectStepOutputs(postCtx, postArtifacts);
     }
     catch (err) {
-        console.warn(`[sandbox-step] post-step.collect failed (non-fatal):`, err instanceof Error ? err.message : err);
+        logger.warn("post-step.collect failed (non-fatal)", logger.errorFields(err));
     }
     await emitActivity("indexing", "Indexing outputs for search");
-    await safeRun(() => vectorIndexStepOutputs(deps, postCtx, postArtifacts), "post-step.vector-index");
+    await safeRun(logger, () => vectorIndexStepOutputs(deps, postCtx, postArtifacts), "post-step.vector-index");
     // (9) teardown — destroy sandbox + clear sandbox_ref.
     await DBOS.runStep(() => deps.sandboxClient.teardown(sandbox), { name: "sandbox.teardown" });
     // (10) mark-terminal + emit.
@@ -537,14 +553,17 @@ async function runSandboxStepBody(input, deps) {
  * 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) {
+async function safeRun(logger, 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);
+        // The stage rides as a namespace, not interpolated prose: `label` is what
+        // says WHICH post-step stage degraded, and a reader must be able to filter
+        // on it without parsing the message.
+        logger.named(label).warn("failed (non-fatal)", logger.errorFields(err));
     }
 }
 /**
@@ -552,22 +571,25 @@ async function safeRun(fn, label) {
  * 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) {
+async function safeRunValue(logger, 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);
+        // The stage rides as a namespace, not interpolated prose: `label` is what
+        // says WHICH post-step stage degraded, and a reader must be able to filter
+        // on it without parsing the message.
+        logger.named(label).warn("failed (non-fatal)", logger.errorFields(err));
         return fallback;
     }
 }
-async function tryTeardown(deps, sandbox) {
+async function tryTeardown(logger, 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);
+        logger.warn("teardown failed (non-fatal)", logger.errorFields(err));
     }
 }

package/dist/workflows/target-assessment/lib/citation-validator.js

@@ -5,11 +5,11 @@
 // was always 0. These patterns match the format the agent actually writes.
 // The block content may include array index notation like `[0]`, so we
 // use a pattern that allows `[digits]` inside the outer brackets.
-const DOSSIER_CITE_BLOCK_RE = /\[dossier:\s*((?:[^[\]]*(?:\[\d+\])?)*)\]/gi;
+const DOSSIER_CITE_BLOCK_RE = /\[dossier:\s*((?:[^[\]]|\[\d+\])*)\]/gi;
 // External citation IDs are plain strings — no array-index notation like `[n]` — so the simple [^\]]+ class suffices here instead of the array-index-aware pattern used by DOSSIER_CITE_BLOCK_RE.
 const EXTERNAL_CITE_BLOCK_RE = /\[external citation:\s*([^\]]+)\]/gi;
 // Assumes at most one `external citation:` segment per dossier block (the recommendation prompt produces at most one); a hypothetical second segment in the same block would be parsed imperfectly.
-const EXTERNAL_SEGMENT_RE = /external citation:\s*((?:[^[\]]*(?:\[\d+\])?)*)/i;
+const EXTERNAL_SEGMENT_RE = /external citation:\s*((?:[^[\]]|\[\d+\])*)/i;
 const NCT_RE = /\bNCT\d{8}\b/g;
 const PMID_RE = /\bPMID[:\s]?(\d{6,9})\b/g;
 // Legacy inline format: `dossier.path.foo` written directly in prose, no

package/dist/workflows/target-assessment/lib/clinical-consequence-annotator.js

@@ -19,6 +19,7 @@ import { z } from "zod";
 import { withHost } from "../../../lib/host-concurrency.js";
 import { tryQuery, tryMutation } from "../../../lib/db-result.js";
 import { offTargetAnnotatorPrompt } from "../../../prompts/target-assessment/off-target-annotator.js";
+import { composeSystemPrompt } from "../../../agents/system-prompt.js";
 import { forSubAgent } from "../../../auth/types.js";
 import { finalText, runAgent } from "../../../loop/run-agent.js";
 import { passthroughStep } from "../../../loop/run-step.js";
@@ -93,7 +94,7 @@ const ANNOTATOR_AGENT_ID = "off-target-annotator";
 function buildAnnotatorAgent(model) {
     return {
         id: ANNOTATOR_AGENT_ID,
-        systemPrompt: offTargetAnnotatorPrompt,
+        systemPrompt: composeSystemPrompt(offTargetAnnotatorPrompt),
         model,
         tools: [],
         maxIterations: 2,

package/dist/workflows/target-assessment/lib/llm-step.d.ts

@@ -23,6 +23,7 @@
  * the caller bumps the attempt counter so the resumed call lands a fresh
  * DBOS cache slot rather than replaying the cancelled prior attempt.
  */
+import type { Logger } from "../../../lib/logger.js";
 import type { AgentChat, ChatRequest, ChatResponse } from "../../../providers/types.js";
 import type { AgentSession } from "../../../auth/types.js";
 /**
@@ -38,6 +39,8 @@ export interface BudgetExceededMarker {
     readonly error: string;
 }
 export interface RunLlmStepOptions {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     /** Durable-step name — already attempt-numbered by the caller. */
     readonly stepName: string;
     /** Agent id stamped in the marker for telemetry. */