@inflexa-ai/harness 0.9.0 → 0.10.0

package/dist/agents/conversation-agent.js

@@ -32,7 +32,7 @@ import { createWorkingMemory } from "../memory/working-memory.js";
 import { conversationPrompt } from "../prompts/conversation.js";
 import { composeSystemPrompt } from "./system-prompt.js";
 // Bio-lookup leaf tools (pure — no dependencies).
-import { searchGeneTool, searchPathwayTool, lookupGoTermTool, searchInteractionsTool, chemblTool, pubchemTool, openTargetsTool, searchPharmgkbTool, searchFaersTool, searchClinicalTrialsTool, searchGeoDatasetsTool, createSearchDgidbTool, searchBgeeExpressionTool, getImpcKoProfileTool, checkSafetyPanelTool, } from "../tools/bio/index.js";
+import { searchGeneTool, searchPathwayTool, lookupGoTermTool, searchInteractionsTool, chemblTool, pubchemTool, openTargetsTool, searchGwasCatalogTool, searchPharmgkbTool, searchFaersTool, searchClinicalTrialsTool, searchGeoDatasetsTool, createSearchDgidbTool, searchBgeeExpressionTool, getImpcKoProfileTool, checkSafetyPanelTool, } from "../tools/bio/index.js";
 import { createNcbiTools, createChemDbTools } from "../tools/bio/keys.js";
 // Dependency-bearing tool factories.
 import { createGeneratePlanTool, createLiteratureReviewerTool, createInspectRunTool, createInspectDataProfileTool, createGenerateAnalogyReportTool, } from "../tools/research/index.js";
@@ -68,6 +68,8 @@ export function createConversationAgent(deps) {
         pubchemTool,
         // Translational medicine.
         openTargetsTool,
+        // Genetic evidence — SNP-trait associations for target validation / MR support.
+        searchGwasCatalogTool,
         searchPharmgkbTool,
         searchFaersTool,
         searchClinicalTrialsTool,

package/dist/execution/run-synthesis.d.ts

@@ -30,6 +30,13 @@ import type { ChatProvider } from "../providers/types.js";
 import type { RunSession } from "../auth/types.js";
 import { type Tool } from "../tools/define-tool.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
+/**
+ * The synthesizer's agent identity — the `source.agentId` on its loop events
+ * and the `agent_id` of the run-phase `synthesis` row `executeAnalysis` writes
+ * to `cortex_step_executions`. One definition so the ledger row and the stream
+ * events can never disagree about who did the work.
+ */
+export declare const SYNTHESIS_AGENT_ID = "run-synthesizer";
 type SynthesizerOutcome = {
     kind: "submitted";
     synthesis: RunSynthesis;

package/dist/execution/run-synthesis.js

@@ -39,7 +39,13 @@ import { defineTool } from "../tools/define-tool.js";
 import { createReportBlockerToolFor } from "../tools/sandbox/report-blocker.js";
 import { createLiteratureReviewerTool } from "../tools/research/literature-reviewer.js";
 // ── Agent identity / budgets ────────────────────────────────────────
-const AGENT_ID = "run-synthesizer";
+/**
+ * The synthesizer's agent identity — the `source.agentId` on its loop events
+ * and the `agent_id` of the run-phase `synthesis` row `executeAnalysis` writes
+ * to `cortex_step_executions`. One definition so the ledger row and the stream
+ * events can never disagree about who did the work.
+ */
+export const SYNTHESIS_AGENT_ID = "run-synthesizer";
 /**
  * Budget for the synthesizer loop: read summaries + 1–3 reviewer delegations
  * + draft + 1–2 submit/fix cycles + headroom.
@@ -349,7 +355,7 @@ export async function generateRunSynthesis(input) {
     const blockerTool = buildBlockerTool(holder);
     const tools = [validateTool, submitTool, blockerTool, reviewer];
     const agent = {
-        id: AGENT_ID,
+        id: SYNTHESIS_AGENT_ID,
         systemPrompt: composeSystemPrompt(synthesisAgentPrompt),
         model: input.model,
         tools,

package/dist/schemas/validate-plan.js

@@ -13,14 +13,17 @@
  */
 import { KNOWN_AGENT_IDS } from "../agents/sandbox-catalog.js";
 import { CycleError, DependencyError, topoSortIntoWaves } from "../execution/topo-sort.js";
-import { isSafeId, STEP_SUBDIRS } from "../workspace/paths.js";
+import { isSafeId, STEP_SUBDIRS, SYNTHESIS_STEP_ID } from "../workspace/paths.js";
 const KNOWN_AGENTS = new Set(KNOWN_AGENT_IDS);
 /**
  * Reserved step-id names. A step id equal to an artifact subdirectory name
  * would make its directory (`runs/{runId}/{stepId}`) collide with the
- * subdirectory convention agents expect inside a step (see the harness-workspace-tools spec).
+ * subdirectory convention agents expect inside a step, and
+ * {@link SYNTHESIS_STEP_ID} is the run-phase ledger row `executeAnalysis`
+ * writes for run-level synthesis — a plan step with that id would collide with
+ * the row's `(run_id, step_id)` primary key (see the harness-workspace-tools spec).
  */
-const RESERVED_STEP_IDS = new Set(STEP_SUBDIRS);
+const RESERVED_STEP_IDS = new Set([...STEP_SUBDIRS, SYNTHESIS_STEP_ID]);
 /** Derive a filesystem-safe output prefix from a step ID. */
 export function deriveOutputPrefix(stepId) {
     return stepId
@@ -97,11 +100,13 @@ export function validatePlan(plan, options) {
                 `${ceiling.maxMemoryGb} per step — reduce memoryGb or restructure the step`);
         }
     }
-    // 5. Reserved step-id names (collide with artifact subdirectories)
+    // 5. Reserved step-id names (collide with artifact subdirectories or the
+    //    run-phase synthesis ledger row)
     for (const step of plan.steps) {
         if (RESERVED_STEP_IDS.has(step.id.toLowerCase())) {
             errors.push(`Step "${step.id}" uses a reserved name — step ids must not be one of: ` +
-                `${STEP_SUBDIRS.join(", ")} (they collide with the artifact subdirectory convention)`);
+                `${[...RESERVED_STEP_IDS].join(", ")} (the artifact subdirectory names collide with the ` +
+                `step-directory convention; "${SYNTHESIS_STEP_ID}" is the run-level synthesis phase)`);
         }
     }
     // 6. Step-id path safety. The id becomes the `runs/{runId}/{stepId}` directory

package/dist/tools/research/inspect-run.js

@@ -16,6 +16,7 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { queryRun, queryRunsByAnalysis, queryStepsByRun } from "../../state/index.js";
 import { scopeResource } from "../../auth/types.js";
+import { SYNTHESIS_STEP_ID } from "../../workspace/paths.js";
 import { unwrapOrThrow } from "../../lib/result.js";
 import { defineTool } from "../define-tool.js";
 function formatRun(r, verbose) {
@@ -73,9 +74,15 @@ export function createInspectRunTool(pool) {
                 agentId: s.agentId,
                 wave: s.wave,
                 status: s.status,
-                // Seeded rows exist before a step ever runs; a summary path for one
-                // would point the agent at a file that cannot exist yet (or ever).
-                ...(s.status === "pending" || s.status === "skipped" ? {} : { summaryPath: `runs/${input.runId}/${s.stepId}/output/summary.md` }),
+                // No per-step `summaryPath` when the file cannot exist: a seeded row
+                // (`pending`/`skipped`) never produced output, and the reserved
+                // `synthesis` phase is not a sandbox step — it writes the run-level
+                // `synthesis.json`, surfaced as the run's `synthesisPath`, not a
+                // `{stepId}/output/summary.md`. Emitting the per-step path for it would
+                // point the agent at a file that never exists.
+                ...(s.status === "pending" || s.status === "skipped" || s.stepId === SYNTHESIS_STEP_ID
+                    ? {}
+                    : { summaryPath: `runs/${input.runId}/${s.stepId}/output/summary.md` }),
                 ...(verbose
                     ? {
                         durationMs: s.durationMs,

package/dist/tools/workspace/read-file.d.ts

@@ -30,6 +30,11 @@ type ReadFileOutput = {
 } | {
     status: "out_of_scope";
     path: string;
+} | {
+    status: "binary";
+    path: string;
+    mode: "head" | "tail" | "full";
+    totalSize?: number;
 };
 export declare function createReadFileTool(fs: WorkspaceFilesystem, workingDir?: string): import("../define-tool.js").Tool<{
     path: string;

package/dist/tools/workspace/read-file.js

@@ -13,6 +13,18 @@ import { defineTool } from "../define-tool.js";
 import { unwrapOrThrow } from "../../lib/result.js";
 /** Default cap — large enough for typical CSV/MD/JSON, small enough to keep tool results out of context-blowing territory. */
 const DEFAULT_MAX_BYTES = 256 * 1024;
+/**
+ * Treat returned content as binary when it contains a NUL byte — `grep`'s
+ * `looksBinary` heuristic, applied here to the whole returned window rather than
+ * a 1 KiB probe. These exact bytes are what would be UTF-8-decoded into the
+ * transcript, and a NUL both renders that decode as lossy garbage (useless to
+ * the model) and cannot be persisted into the JSONB message store — Postgres
+ * rejects U+0000 with 22P05, failing the whole turn's append. Reporting the
+ * read as `binary` keeps a NUL out of both.
+ */
+function looksBinary(content) {
+    return content.includes(0);
+}
 const ReadFileInputSchema = z.object({
     path: z
         .string()
@@ -45,8 +57,10 @@ export function createReadFileTool(fs, workingDir) {
             "as UTF-8 text. Output is capped at " +
             `${DEFAULT_MAX_BYTES} bytes; pass headLines or tailLines to read a ` +
             "specific window of a large file (typical for bio CSV/TSV/log files). " +
-            "Oversize reads come back truncated with a marker. Missing paths and " +
-            "paths outside the analysis tree return a data variant — not an error.",
+            "Oversize reads come back truncated with a marker. This tool is for " +
+            "text; a binary file (one holding NUL bytes, e.g. a .gz or image) comes " +
+            "back as a `binary` data variant rather than decoded garbage. Missing " +
+            "paths and paths outside the analysis tree return a data variant — not an error.",
         inputSchema: ReadFileInputSchema,
         execute: async ({ path, headLines, tailLines }, ctx) => {
             if (headLines !== undefined && tailLines !== undefined) {
@@ -67,6 +81,8 @@ export function createReadFileTool(fs, workingDir) {
             const mode = headLines !== undefined ? "head" : tailLines !== undefined ? "tail" : "full";
             switch (result.kind) {
                 case "ok":
+                    if (looksBinary(result.content))
+                        return ok({ status: "binary", path, mode });
                     return ok({
                         status: "ok",
                         path,
@@ -74,6 +90,8 @@ export function createReadFileTool(fs, workingDir) {
                         content: result.content.toString("utf8"),
                     });
                 case "truncated":
+                    if (looksBinary(result.content))
+                        return ok({ status: "binary", path, mode, totalSize: result.totalSize });
                     return ok({
                         status: "truncated",
                         path,

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

@@ -63,7 +63,7 @@ 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 { SynthesisStatus } from "../state/index.js";
+import type { SynthesisStatus, UpdateStepExecutionInput } from "../state/index.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";
@@ -288,6 +288,19 @@ export declare function composeStepSeed(args: {
     runId: string;
     deps: ExecuteAnalysisDeps;
 }): Promise<string>;
+/**
+ * Project a classified synthesis outcome onto the run-phase `synthesis` ledger
+ * row's terminal update (see the run-synthesis-outcome spec). The blocker keeps
+ * its reason in `blockedReason` — an honest agent-declared blocker, not an
+ * error — and a failure carries the same reason string
+ * `persist-synthesis-outcome` writes to `cortex_runs.synthesis_reason`, so the
+ * two ledgers cannot disagree about why synthesis died. Exported for the
+ * projection tests (the `buildChildInput` pattern).
+ */
+export declare function synthesisRowUpdate(outcome: {
+    status: SynthesisStatus;
+    reason: string | null;
+}, durationMs: number): UpdateStepExecutionInput;
 /**
  * Run-level literature-grounded synthesis (no sandbox). Returns the
  * quick-display findings for the run-completed card; empty when synthesis is

package/dist/workflows/execute-analysis.js

@@ -58,17 +58,17 @@
  *     - WRITES NOTHING to the conversation thread (results are pull-only
  *       via `inspectRun`)
  */
-import { DBOS } from "@dbos-inc/dbos-sdk";
+import { DBOS, Error as DBOSErrors } 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, setRunSynthesisOutcome, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, } from "../state/index.js";
+import { RunDedupCollisionError, countArtifactsForRun, insertStepExecution, loadDataProfileStatus, queryActiveRun, queryStepArtifactPaths, seedStepExecutions, setRunSynthesisOutcome, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, updateStepExecution, } from "../state/index.js";
 import { isBudgetExceeded } from "../loop/budget-exceeded.js";
-import { loadStepSummariesFromDisk } from "../execution/run-synthesis.js";
+import { SYNTHESIS_AGENT_ID, 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 { SYNTHESIS_STEP_ID, 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";
@@ -222,6 +222,31 @@ async function collectUpstreamHandoffs(args) {
     }
     return handoffs;
 }
+/**
+ * Project a classified synthesis outcome onto the run-phase `synthesis` ledger
+ * row's terminal update (see the run-synthesis-outcome spec). The blocker keeps
+ * its reason in `blockedReason` — an honest agent-declared blocker, not an
+ * error — and a failure carries the same reason string
+ * `persist-synthesis-outcome` writes to `cortex_runs.synthesis_reason`, so the
+ * two ledgers cannot disagree about why synthesis died. Exported for the
+ * projection tests (the `buildChildInput` pattern).
+ */
+export function synthesisRowUpdate(outcome, durationMs) {
+    switch (outcome.status) {
+        case "produced":
+            return { status: "completed", durationMs };
+        case "skipped_no_summaries":
+            return { status: "skipped", durationMs };
+        case "skipped_blocker":
+            return { status: "blocked", durationMs, blockedReason: outcome.reason };
+        case "failed":
+            return { status: "failed", durationMs, error: outcome.reason };
+        default: {
+            const _exhaustive = outcome.status;
+            throw new Error(`unhandled synthesis status: ${String(_exhaustive)}`);
+        }
+    }
+}
 /**
  * Run-level literature-grounded synthesis (no sandbox). Returns the
  * quick-display findings for the run-completed card; empty when synthesis is
@@ -309,14 +334,32 @@ export async function runExecuteAnalysisBody(input, deps) {
     // The seed's DO NOTHING conflict action makes this replay-safe; the agent
     // fallback mirrors `buildChildInput` so seed and mark-running agree on the
     // row a step's child later upserts.
+    //
+    // The run-phase `synthesis` row is seeded alongside the DAG — gated on
+    // enablement ONLY, because the other half of the run gate for actually
+    // executing synthesis (`final.completed.size > 0`) is unknowable until the
+    // scheduler returns. A seeded row whose gate later fails simply stays
+    // `pending` and the terminal sweep finalizes it to `skipped` — honest
+    // ("never ran, never will"), like any never-dispatched DAG step. Its wave
+    // sits after every DAG level so ledger-ordered readers render it last.
+    const synthesisEnabled = deps.synthesisEnabled ?? true;
+    const synthesisWave = Math.max(-1, ...levels.values()) + 1;
     await DBOS.runStep(async () => {
-        unwrapOrThrow(await seedStepExecutions(deps.pool, input.steps.map((step) => ({
+        const dagRows = input.steps.map((step) => ({
             runId,
             stepId: step.id,
             analysisId: input.analysisId,
             wave: levels.get(step.id) ?? 0,
             agentId: input.agentByStepId[step.id] ?? "scientific-executor",
-        }))));
+        }));
+        const synthesisRow = {
+            runId,
+            stepId: SYNTHESIS_STEP_ID,
+            analysisId: input.analysisId,
+            wave: synthesisWave,
+            agentId: SYNTHESIS_AGENT_ID,
+        };
+        unwrapOrThrow(await seedStepExecutions(deps.pool, synthesisEnabled ? [...dagRows, synthesisRow] : dagRows));
     }, { name: "seed-step-executions" });
     // One checkpointed clock read stamps the run's start; the terminal read in
     // `collectAndComplete` subtracts it for the true run span. Checkpointed →
@@ -352,10 +395,37 @@ export async function runExecuteAnalysisBody(input, deps) {
     let synthesisError = null;
     let synthesisFindings = [];
     // Null when synthesis never ran (disabled or no completed steps): the ledger
-    // columns stay NULL — "unknown", not a recorded skip.
+    // columns stay NULL — "unknown", not a recorded skip — and the seeded
+    // `synthesis` row (if any) stays `pending` for the terminal sweep.
     let synthesisOutcome = null;
-    const synthesisEnabled = deps.synthesisEnabled ?? true;
     if (synthesisEnabled && final.completed.size > 0) {
+        // Bracketing clock reads for the row's duration_ms — checkpointed, so a
+        // recovered replay reuses the original instants (same rule as `startedAtMs`).
+        const synthStartedAtMs = await DBOS.now();
+        // Mark the seeded `synthesis` row running. The same upsert the DAG children
+        // use: it stamps started_at, and it CREATES the row outright when the seed
+        // never carried it (synthesisEnabled flipped true across a recovery
+        // redeploy) — the mark self-heals rather than trusting the seed's snapshot
+        // of the config. Log-don't-fail: a progress row must never fail an
+        // otherwise-healthy run. Cancellation still re-propagates — it is not a
+        // write failure, and swallowing it here would only defer it one operation.
+        try {
+            await DBOS.runStep(async () => {
+                unwrapOrThrow(await insertStepExecution(deps.pool, {
+                    runId,
+                    stepId: SYNTHESIS_STEP_ID,
+                    analysisId: input.analysisId,
+                    wave: synthesisWave,
+                    agentId: SYNTHESIS_AGENT_ID,
+                    childWorkflowId: null,
+                }));
+            }, { name: "mark-synthesis-running" });
+        }
+        catch (err) {
+            if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
+                throw err;
+            logger.error("mark-synthesis-running failed", { runId, ...logger.errorFields(err) });
+        }
         try {
             const synthOut = await DBOS.runStep(() => synthesizeFindings({
                 analysisId: input.analysisId,
@@ -368,10 +438,37 @@ export async function runExecuteAnalysisBody(input, deps) {
             synthesisOutcome = { status: synthOut.synthesisStatus, reason: synthOut.synthesisReason };
         }
         catch (err) {
+            // Cancellation is not a synthesis outcome: re-propagate unchanged (the
+            // sandbox-step rule), so a cancelled workflow is never recorded as a
+            // synthesis failure — neither on the row nor in cortex_runs. The row is
+            // deliberately left `running`: `collectAndComplete` never executes on
+            // this path either, so the run row is equally non-terminal and the pair
+            // stays consistent — the pre-existing cancelled-mid-flight wedge shape
+            // `inflexa run` already detects via its DBOS-status cross-check.
+            if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
+                throw err;
             synthesisError = err;
             synthesisOutcome = { status: "failed", reason: err instanceof Error ? err.message : String(err) };
             logger.error("synthesizeFindings failed — failing the run", { runId, ...logger.errorFields(err) });
         }
+        // Terminal stamp for the `synthesis` row — deliberately BEFORE
+        // `collectAndComplete` writes the run row's terminal status, so no reader
+        // can observe a terminal run beside a still-`running` synthesis row. Both
+        // branches above set `synthesisOutcome` (or threw), so it is non-null here
+        // and the compiler narrows it — no guard needed. Log-don't-fail, like the
+        // sibling finalisation writes.
+        const rowOutcome = synthesisOutcome;
+        try {
+            const synthEndedAtMs = await DBOS.now();
+            await DBOS.runStep(async () => {
+                unwrapOrThrow(await updateStepExecution(deps.pool, runId, SYNTHESIS_STEP_ID, synthesisRowUpdate(rowOutcome, synthEndedAtMs - synthStartedAtMs)));
+            }, { name: "persist-synthesis-step" });
+        }
+        catch (err) {
+            if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
+                throw err;
+            logger.error("persist-synthesis-step failed", { runId, ...logger.errorFields(err) });
+        }
     }
     // (6) collectAndComplete — terminal block. Runs on EVERY path. When synthesis
     // failed, force a failed terminal status so the charge/run-authorization close correctly

package/dist/workspace/paths.d.ts

@@ -181,5 +181,15 @@ export declare function stepSubdir(stepBase: string, type: StepSubdirType): stri
 export declare function reportDir(reportId: string): string;
 /** All standard subdirectory types for a step. */
 export declare const STEP_SUBDIRS: readonly StepSubdirType[];
+/**
+ * Reserved id of the run-phase synthesis row in `cortex_step_executions` — the
+ * ledger row `executeAnalysis` writes for run-level synthesis so progress
+ * readers see the phase. Reserved here beside {@link STEP_SUBDIRS} because the
+ * reservation is a layout fact as much as a ledger one: a plan step with this
+ * id would collide with the row's primary key AND put its step directory
+ * `runs/{runId}/synthesis/` beside the run-level `runs/{runId}/synthesis.json`.
+ * Plan validation rejects it (see validate-plan).
+ */
+export declare const SYNTHESIS_STEP_ID = "synthesis";
 /** Get all subdirectory paths for a step. */
 export declare function allStepSubdirs(stepBase: string): string[];

package/dist/workspace/paths.js

@@ -213,6 +213,16 @@ export function reportDir(reportId) {
 }
 /** All standard subdirectory types for a step. */
 export const STEP_SUBDIRS = ["scripts", "output", "figures", "logs", "notebooks"];
+/**
+ * Reserved id of the run-phase synthesis row in `cortex_step_executions` — the
+ * ledger row `executeAnalysis` writes for run-level synthesis so progress
+ * readers see the phase. Reserved here beside {@link STEP_SUBDIRS} because the
+ * reservation is a layout fact as much as a ledger one: a plan step with this
+ * id would collide with the row's primary key AND put its step directory
+ * `runs/{runId}/synthesis/` beside the run-level `runs/{runId}/synthesis.json`.
+ * Plan validation rejects it (see validate-plan).
+ */
+export const SYNTHESIS_STEP_ID = "synthesis";
 /** Get all subdirectory paths for a step. */
 export function allStepSubdirs(stepBase) {
     return STEP_SUBDIRS.map((type) => stepSubdir(stepBase, type));

package/package.json

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