@inflexa-ai/harness 0.2.0 → 0.3.0

package/dist/tools/bio/search-dgidb.js

@@ -11,6 +11,7 @@
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
 import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
 const DGIDB_GRAPHQL_URL = "https://dgidb.org/api/graphql";
 const GENE_INTERACTIONS_QUERY = `query($genes: [String!]!) {
@@ -115,85 +116,98 @@ function applyFilters(interactions, filters) {
     }
     return out;
 }
-export const searchDgidbTool = defineTool({
-    id: "search_dgidb",
-    description: "Query the Drug-Gene Interaction Database (DGIdb) for drug-gene interactions. " +
-        "DGIdb aggregates 30+ sources (ChEMBL, DrugBank, TTD, PharmGKB, GuideToPharmacology, CIViC, etc.) " +
-        "and returns source counts as a confidence signal. " +
-        "searchType='gene' returns drugs interacting with input HUGO gene symbols (most common: 'what drugs hit my gene set?'). " +
-        "searchType='drug' returns the genes each input drug is known to act on. " +
-        "Free, no API key required. Sorted by source count desc.",
-    inputSchema: z.object({
-        query: z
-            .union([z.string(), z.array(z.string()).max(50)])
-            .describe("Single identifier or list of up to 50. For searchType='gene': HUGO symbols. For searchType='drug': drug names or DGIdb concept IDs."),
-        searchType: z.enum(["gene", "drug"]).default("gene"),
-        interactionTypes: z.array(z.string()).optional().describe("Case-insensitive substring filter on interaction type. e.g. ['inhibitor', 'antagonist']"),
-        sources: z.array(z.string()).optional().describe("Restrict to interactions from these source DBs (case-insensitive substring)."),
-        minSources: z.number().int().min(1).default(1).describe("Drop interactions supported by fewer than this many sources."),
-        limit: z.number().int().min(1).max(200).default(50).describe("Max interactions per input gene/drug after filtering."),
-    }),
-    execute: async ({ query, searchType = "gene", interactionTypes, sources, minSources = 1, limit = 50 }) => {
-        const inputs = typeof query === "string" ? [query] : query;
-        if (inputs.length === 0 || inputs.every((s) => !s.trim())) {
-            throw new Error("query must contain at least one identifier");
-        }
-        const isGene = searchType === "gene";
-        const variableName = isGene ? "genes" : "drugs";
-        const queryString = isGene ? GENE_INTERACTIONS_QUERY : DRUG_INTERACTIONS_QUERY;
-        const res = await apiFetchValidated(DGIDB_GRAPHQL_URL, DgidbResponseSchema, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-                query: queryString,
-                variables: { [variableName]: inputs },
-            }),
-        });
-        if (res.isErr())
-            throw new Error(describeApiError(res.error));
-        const body = res.value;
-        if (!body || !body.data)
-            throw new Error("DGIdb returned no data");
-        if (body.errors?.length) {
-            console.warn("dgidb.partial_errors", { errors: body.errors.slice(0, 3) });
-        }
-        const nodes = (isGene ? body.data.genes?.nodes : body.data.drugs?.nodes) ?? [];
-        const nodeMap = new Map();
-        for (const node of nodes) {
-            nodeMap.set(node.name.toLowerCase(), node);
-            if (!isGene && node.conceptId) {
-                nodeMap.set(node.conceptId.toLowerCase(), node);
-            }
-        }
-        const results = inputs.map((input) => {
-            const node = nodeMap.get(input.toLowerCase());
-            if (!node) {
-                return { input, found: false, interactions: [] };
+/**
+ * A factory rather than a bare const (unlike its bio-leaf siblings) because it
+ * logs: DGIdb answers GraphQL partial errors alongside usable data, and an
+ * operator debugging odd interaction results needs to see them. `ToolContext`
+ * carries no deps by design, so a tool that logs is dep-bearing — the same
+ * reason `createSearchClinvarTool` takes its key that way.
+ */
+export function createSearchDgidbTool(deps = {}) {
+    const logger = (deps.logger ?? createNoopLogger()).named("search_dgidb");
+    return defineTool({
+        id: "search_dgidb",
+        description: "Query the Drug-Gene Interaction Database (DGIdb) for drug-gene interactions. " +
+            "DGIdb aggregates 30+ sources (ChEMBL, DrugBank, TTD, PharmGKB, GuideToPharmacology, CIViC, etc.) " +
+            "and returns source counts as a confidence signal. " +
+            "searchType='gene' returns drugs interacting with input HUGO gene symbols (most common: 'what drugs hit my gene set?'). " +
+            "searchType='drug' returns the genes each input drug is known to act on. " +
+            "Free, no API key required. Sorted by source count desc.",
+        inputSchema: z.object({
+            query: z
+                .union([z.string(), z.array(z.string()).max(50)])
+                .describe("Single identifier or list of up to 50. For searchType='gene': HUGO symbols. For searchType='drug': drug names or DGIdb concept IDs."),
+            searchType: z.enum(["gene", "drug"]).default("gene"),
+            interactionTypes: z
+                .array(z.string())
+                .optional()
+                .describe("Case-insensitive substring filter on interaction type. e.g. ['inhibitor', 'antagonist']"),
+            sources: z.array(z.string()).optional().describe("Restrict to interactions from these source DBs (case-insensitive substring)."),
+            minSources: z.number().int().min(1).default(1).describe("Drop interactions supported by fewer than this many sources."),
+            limit: z.number().int().min(1).max(200).default(50).describe("Max interactions per input gene/drug after filtering."),
+        }),
+        execute: async ({ query, searchType = "gene", interactionTypes, sources, minSources = 1, limit = 50 }) => {
+            const inputs = typeof query === "string" ? [query] : query;
+            if (inputs.length === 0 || inputs.every((s) => !s.trim())) {
+                throw new Error("query must contain at least one identifier");
             }
-            const inputSide = isGene
-                ? { geneName: node.name }
-                : {
-                    drugName: node.name,
-                    drugConceptId: node.conceptId ?? undefined,
-                };
-            const mapped = (node.interactions ?? []).map((raw) => mapInteraction(raw, searchType, inputSide));
-            const filtered = applyFilters(mapped, {
-                interactionTypes,
-                sources,
-                minSources,
+            const isGene = searchType === "gene";
+            const variableName = isGene ? "genes" : "drugs";
+            const queryString = isGene ? GENE_INTERACTIONS_QUERY : DRUG_INTERACTIONS_QUERY;
+            const res = await apiFetchValidated(DGIDB_GRAPHQL_URL, DgidbResponseSchema, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    query: queryString,
+                    variables: { [variableName]: inputs },
+                }),
             });
-            const sorted = filtered.sort((a, b) => {
-                if (b.sourceCount !== a.sourceCount) {
-                    return b.sourceCount - a.sourceCount;
+            if (res.isErr())
+                throw new Error(describeApiError(res.error));
+            const body = res.value;
+            if (!body || !body.data)
+                throw new Error("DGIdb returned no data");
+            if (body.errors?.length) {
+                logger.warn("dgidb partial errors alongside data", { errors: body.errors.slice(0, 3) });
+            }
+            const nodes = (isGene ? body.data.genes?.nodes : body.data.drugs?.nodes) ?? [];
+            const nodeMap = new Map();
+            for (const node of nodes) {
+                nodeMap.set(node.name.toLowerCase(), node);
+                if (!isGene && node.conceptId) {
+                    nodeMap.set(node.conceptId.toLowerCase(), node);
                 }
-                return (b.interactionScore ?? 0) - (a.interactionScore ?? 0);
+            }
+            const results = inputs.map((input) => {
+                const node = nodeMap.get(input.toLowerCase());
+                if (!node) {
+                    return { input, found: false, interactions: [] };
+                }
+                const inputSide = isGene
+                    ? { geneName: node.name }
+                    : {
+                        drugName: node.name,
+                        drugConceptId: node.conceptId ?? undefined,
+                    };
+                const mapped = (node.interactions ?? []).map((raw) => mapInteraction(raw, searchType, inputSide));
+                const filtered = applyFilters(mapped, {
+                    interactionTypes,
+                    sources,
+                    minSources,
+                });
+                const sorted = filtered.sort((a, b) => {
+                    if (b.sourceCount !== a.sourceCount) {
+                        return b.sourceCount - a.sourceCount;
+                    }
+                    return (b.interactionScore ?? 0) - (a.interactionScore ?? 0);
+                });
+                return {
+                    input,
+                    found: true,
+                    interactions: sorted.slice(0, limit),
+                };
             });
-            return {
-                input,
-                found: true,
-                interactions: sorted.slice(0, limit),
-            };
-        });
-        return ok({ results });
-    },
-});
+            return ok({ results });
+        },
+    });
+}

package/dist/tools/iterate-report.d.ts

@@ -47,6 +47,7 @@ import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { type StagedAsset } from "./lib/report-preflight.js";
 import type { PreviewPublisher } from "./report/preview-publisher.js";
 import type { ChromeConfig } from "../lib/chrome.js";
+import type { Logger } from "../lib/logger.js";
 /**
  * The report brief the conversation agent composes: title/audience + sources +
  * the section union. This is the ~12k-char schema that `plan_report` hands back
@@ -183,6 +184,8 @@ export declare const submitReportInputSchema: z.ZodObject<{
  */
 export declare const planReportTool: Tool;
 export interface SubmitReportDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly provider: ChatProvider;
     readonly pool: Pool;
     /** Embedder-supplied workspace-root resolution seam (see workspace/paths.ts). */

package/dist/tools/iterate-report.js

@@ -49,6 +49,7 @@ import { defineTool } from "./define-tool.js";
 import { previewDir } from "../workspace/paths.js";
 import { runReportIteration } from "../execution/report-runner.js";
 import { formatBytes, stageReportAssets } from "./lib/report-preflight.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 const REPORT_TOOL_ACCESS_TTL_SECONDS = 3600;
 const PREVIEW_META_FILE = "preview-meta.json";
 async function readPreviewMeta(metaPath) {
@@ -577,7 +578,8 @@ export function createReportSubmitTool(deps) {
                     });
                 }
                 catch (err) {
-                    console.warn(`[submit-report] failed to persist preview meta: ${err instanceof Error ? err.message : err}`);
+                    const logger = (deps.logger ?? createNoopLogger()).named("submit-report");
+                    logger.warn("failed to persist preview meta", logger.errorFields(err));
                 }
             }
             const previewTitle = brief?.title ?? existingMeta?.title ?? "Report";

package/dist/tools/research/literature-reviewer.d.ts

@@ -17,7 +17,10 @@
 import { type ChatProvider } from "../../providers/types.js";
 import { type Tool } from "../define-tool.js";
 import { type BioToolKeys } from "../bio/keys.js";
+import type { Logger } from "../../lib/logger.js";
 export interface LiteratureReviewerDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     /** The LLM seam the child loop runs on. */
     readonly provider: ChatProvider;
     /** Model id — provenance / metric label; the provider owns the wire model. */

package/dist/tools/research/literature-reviewer.js

@@ -26,7 +26,7 @@ import { createNcbiTools } from "../bio/keys.js";
 import { getImpcKoProfileTool } from "../bio/get-impc-ko-profile.js";
 import { lookupGoTermTool } from "../bio/lookup-go-term.js";
 import { searchBgeeExpressionTool } from "../bio/search-bgee-expression.js";
-import { searchDgidbTool } from "../bio/search-dgidb.js";
+import { createSearchDgidbTool } from "../bio/search-dgidb.js";
 import { searchGeneTool } from "../bio/search-gene.js";
 import { searchInteractionsTool } from "../bio/search-interactions.js";
 import { searchPathwayTool } from "../bio/search-pathway.js";
@@ -43,7 +43,7 @@ export function createLiteratureReviewerTool(deps) {
         lookupGoTermTool,
         searchInteractionsTool,
         ncbi.pubmed,
-        searchDgidbTool,
+        createSearchDgidbTool({ ...(deps.logger ? { logger: deps.logger } : {}) }),
         searchBgeeExpressionTool,
         getImpcKoProfileTool,
     ];

package/dist/tools/workspace/execute-command.d.ts

@@ -22,7 +22,10 @@
 import type { SandboxClient } from "../../sandbox/client.js";
 import type { SandboxRef } from "../../sandbox/types.js";
 import type { ProvenanceCollector } from "../../provenance/collector.js";
+import type { Logger } from "../../lib/logger.js";
 export interface ExecuteCommandDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly sandboxClient: SandboxClient;
     /** Live sandbox handle for the step. Created once per step at composition root. */
     readonly sandbox: SandboxRef;

package/dist/tools/workspace/execute-command.js

@@ -26,6 +26,7 @@ import { defineTool } from "../define-tool.js";
 import { feedExecFrame } from "../../provenance/exec-frame.js";
 import { boundExecResult } from "./result-bounds.js";
 import { runSandboxExec } from "./run-exec.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
 const ExecuteCommandInputSchema = z.object({
     command: z
         .array(z.string().min(1))
@@ -86,7 +87,8 @@ export function createExecuteCommandTool(deps) {
                     });
                 }
                 catch (err) {
-                    console.warn(`[execute_command] provenance frame handling failed (non-fatal) for ${execId}: ${err instanceof Error ? err.message : err}`);
+                    const logger = (deps.logger ?? createNoopLogger()).named("execute_command");
+                    logger.warn("provenance frame handling failed (non-fatal)", { execId, ...logger.errorFields(err) });
                 }
             }
             return ok({ status: "ok", ...boundExecResult(result) });

package/dist/workflows/execute-analysis.d.ts

@@ -57,6 +57,7 @@ import type { Pool } from "pg";
 import type { MachineBudget, ResourceSpec } from "../config/resource-limits.js";
 import type { RunSession } from "../auth/types.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
+import type { Logger } from "../lib/logger.js";
 import type { AnalysisStep } from "../schemas/workflow-state.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
@@ -206,6 +207,8 @@ export type RunProvenanceEvent = {
  * embedder, model, keys, roots) the in-body synthesis needs.
  */
 export interface ExecuteAnalysisDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly pool: Pool;
     /** Chat provider for the in-body literature-grounded synthesis. */
     readonly provider: ChatProvider;

package/dist/workflows/execute-analysis.js

@@ -57,6 +57,7 @@ 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, loadDataProfileStatus, queryActiveRun, queryStepArtifactPaths, seedStepExecutions, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, } from "../state/index.js";
 import { isBudgetExceeded } from "../loop/budget-exceeded.js";
@@ -81,13 +82,14 @@ 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) });
     }
 }
 /**
@@ -261,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);
@@ -344,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
@@ -693,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({
@@ -735,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
@@ -749,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
@@ -761,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 {
@@ -773,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
@@ -786,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. */