@inflexa-ai/harness 0.4.2 → 0.4.4

package/dist/state/init.js

@@ -61,6 +61,10 @@ CREATE TABLE IF NOT EXISTS cortex_runs (
   started_at          TEXT NOT NULL,
   completed_at        TEXT,
   error               TEXT,
+  -- Run-level synthesis outcome. NULL means "unknown": a legacy row written
+  -- before these columns existed, or a run whose synthesis never recorded a result.
+  synthesis_status    TEXT,
+  synthesis_reason    TEXT,
   parts               JSONB,
   mandate_jti         TEXT, -- oss-core-managed-ok run-mandate ledger, nullable, OSS leaves null
   mandate_expires_at  TEXT -- oss-core-managed-ok run-mandate ledger, nullable, OSS leaves null
@@ -318,6 +322,8 @@ export async function initCortexState(pool, injected) {
                 "ALTER TABLE cortex_runs ADD COLUMN IF NOT EXISTS parts JSONB",
                 "ALTER TABLE cortex_runs ADD COLUMN IF NOT EXISTS mandate_jti TEXT", // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
                 "ALTER TABLE cortex_runs ADD COLUMN IF NOT EXISTS mandate_expires_at TEXT", // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+                "ALTER TABLE cortex_runs ADD COLUMN IF NOT EXISTS synthesis_status TEXT",
+                "ALTER TABLE cortex_runs ADD COLUMN IF NOT EXISTS synthesis_reason TEXT",
                 "ALTER TABLE cortex_analysis_state ADD COLUMN IF NOT EXISTS data_profile_result JSONB",
                 "ALTER TABLE cortex_analysis_state ADD COLUMN IF NOT EXISTS billing_context JSONB",
                 // Sandbox reliability telemetry (from sandbox-reliability change on main).

package/dist/state/runs.d.ts

@@ -12,7 +12,7 @@
 import type { ResultAsync } from "neverthrow";
 import type { DbError } from "../lib/db-result.js";
 import type { Querier } from "./db.js";
-import type { CortexRunRow } from "./schema.js";
+import type { CortexRunRow, SynthesisStatus } from "./schema.js";
 export interface InsertRunInput {
     runId: string;
     analysisId: string;
@@ -67,3 +67,9 @@ export declare function queryRunsByThread(pool: Querier, analysisId: string, thr
  * The JWT itself is NOT persisted — it rides in DBOS workflow input.
  */
 export declare function setRunMandate(pool: Querier, runId: string, jti: string, expiresAt: string): ResultAsync<void, DbError>;
+/**
+ * Record the run-level synthesis outcome on the run ledger. `synthesisReason`
+ * carries operator-facing detail for a skipped/failed outcome; it stays null
+ * for the "produced" case.
+ */
+export declare function setRunSynthesisOutcome(pool: Querier, runId: string, synthesisStatus: SynthesisStatus, synthesisReason?: string | null): ResultAsync<void, DbError>;

package/dist/state/runs.js

@@ -80,7 +80,7 @@ export function queryActiveRun(pool, analysisId, planId) {
     return tryQuery("runs.queryActiveRun", async () => {
         const result = await pool.query({
             text: `SELECT run_id, analysis_id, thread_id, workflow_name,
-                   status, started_at, completed_at, error, parts,
+                   status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
                    mandate_jti, mandate_expires_at, plan_id -- oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
             FROM cortex_runs
             WHERE analysis_id = $1
@@ -118,7 +118,7 @@ export function queryRun(pool, runId) {
     return tryQuery("runs.queryRun", async () => {
         const result = await pool.query({
             text: `SELECT run_id, analysis_id, thread_id, workflow_name,
-                   status, started_at, completed_at, error, parts,
+                   status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
                    mandate_jti, mandate_expires_at, plan_id -- oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
             FROM cortex_runs
             WHERE run_id = $1`,
@@ -132,7 +132,7 @@ export function queryRunsByAnalysis(pool, analysisId, { limit = 50, offset = 0 }
     return tryQuery("runs.queryRunsByAnalysis", async () => {
         const result = await pool.query({
             text: `SELECT run_id, analysis_id, thread_id, workflow_name,
-                   status, started_at, completed_at, error, parts,
+                   status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
                    mandate_jti, mandate_expires_at, plan_id -- oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
             FROM cortex_runs
             WHERE analysis_id = $1
@@ -146,7 +146,7 @@ export function queryRunsByThread(pool, analysisId, threadId, { limit = 50, offs
     return tryQuery("runs.queryRunsByThread", async () => {
         const result = await pool.query({
             text: `SELECT run_id, analysis_id, thread_id, workflow_name,
-                   status, started_at, completed_at, error, parts,
+                   status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
                    mandate_jti, mandate_expires_at, plan_id -- oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
             FROM cortex_runs
             WHERE analysis_id = $1 AND thread_id = $2
@@ -174,6 +174,21 @@ export function setRunMandate(pool, runId, jti, expiresAt) {
         });
     });
 }
+/**
+ * Record the run-level synthesis outcome on the run ledger. `synthesisReason`
+ * carries operator-facing detail for a skipped/failed outcome; it stays null
+ * for the "produced" case.
+ */
+export function setRunSynthesisOutcome(pool, runId, synthesisStatus, synthesisReason) {
+    return tryMutation("runs.setRunSynthesisOutcome", async () => {
+        await pool.query({
+            text: `UPDATE cortex_runs
+            SET synthesis_status = $1, synthesis_reason = $2
+            WHERE run_id = $3`,
+            values: [synthesisStatus, synthesisReason ?? null, runId],
+        });
+    });
+}
 function mapRunRow(row) {
     // JSONB is parsed by `pg` into native arrays/objects. Treat legacy TEXT
     // rows (if anything slipped through) as strings and parse them.
@@ -198,6 +213,8 @@ function mapRunRow(row) {
         startedAt: row.started_at,
         completedAt: row.completed_at ?? null,
         error: row.error ?? null,
+        synthesisStatus: row.synthesis_status ?? null,
+        synthesisReason: row.synthesis_reason ?? null,
         parts,
         mandateJti: row.mandate_jti ?? null, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
         mandateExpiresAt: row.mandate_expires_at ?? null, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)

package/dist/state/schema.d.ts

@@ -64,6 +64,13 @@ export declare const StepExecutionStatus: z.ZodEnum<{
     blocked: "blocked";
 }>;
 export type StepExecutionStatus = z.infer<typeof StepExecutionStatus>;
+export declare const SynthesisStatus: z.ZodEnum<{
+    failed: "failed";
+    produced: "produced";
+    skipped_no_summaries: "skipped_no_summaries";
+    skipped_blocker: "skipped_blocker";
+}>;
+export type SynthesisStatus = z.infer<typeof SynthesisStatus>;
 export declare const CortexRunRowSchema: z.ZodObject<{
     runId: z.ZodString;
     analysisId: z.ZodString;
@@ -80,6 +87,13 @@ export declare const CortexRunRowSchema: z.ZodObject<{
     startedAt: z.ZodString;
     completedAt: z.ZodNullable<z.ZodString>;
     error: z.ZodNullable<z.ZodString>;
+    synthesisStatus: z.ZodNullable<z.ZodEnum<{
+        failed: "failed";
+        produced: "produced";
+        skipped_no_summaries: "skipped_no_summaries";
+        skipped_blocker: "skipped_blocker";
+    }>>;
+    synthesisReason: z.ZodNullable<z.ZodString>;
     parts: z.ZodNullable<z.ZodArray<z.ZodAny>>;
     mandateJti: z.ZodNullable<z.ZodString>;
     mandateExpiresAt: z.ZodNullable<z.ZodString>;

package/dist/state/schema.js

@@ -35,6 +35,11 @@ export const ArtifactRowSchema = z.object({
 // ── Run & Step Execution Schemas ─────────────────────────────────────
 export const RunStatus = z.enum(["running", "completed", "partial", "failed", "canceled", "suspended_insufficient_funds"]);
 export const StepExecutionStatus = z.enum(["pending", "running", "completed", "failed", "skipped", "canceled", "blocked"]);
+// Run-level synthesis outcome, distinct from RunStatus: a run can reach
+// status="completed" while synthesis produced nothing. "produced" is the only
+// outcome that wrote a synthesis result; the two "skipped_*" variants and
+// "failed" record why none exists.
+export const SynthesisStatus = z.enum(["produced", "skipped_no_summaries", "skipped_blocker", "failed"]);
 export const CortexRunRowSchema = z.object({
     runId: z.string(),
     analysisId: z.string(),
@@ -44,6 +49,10 @@ export const CortexRunRowSchema = z.object({
     startedAt: z.string(),
     completedAt: z.string().nullable(),
     error: z.string().nullable(),
+    // NULL synthesisStatus means "unknown" — a legacy row, or a run whose
+    // synthesis never recorded an outcome.
+    synthesisStatus: SynthesisStatus.nullable(),
+    synthesisReason: z.string().nullable(),
     parts: z.array(z.any()).nullable(),
     mandateJti: z.string().nullable(), // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
     mandateExpiresAt: z.string().nullable(), // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)

package/dist/tools/iterate-report.js

@@ -50,6 +50,7 @@ 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";
+import { hintForZodIssue } from "../lib/zod-issues.js";
 const REPORT_TOOL_ACCESS_TTL_SECONDS = 3600;
 const PREVIEW_META_FILE = "preview-meta.json";
 async function readPreviewMeta(metaPath) {
@@ -435,6 +436,7 @@ export function createReportSubmitTool(deps) {
                         issues: parsed.error.issues.map((i) => ({
                             path: i.path.join(".") || "(root)",
                             message: i.message,
+                            hint: hintForZodIssue(i, input.report),
                         })),
                         hint: "The `report` brief did not match the schema. Call `plan_report` for the full schema, fix the fields named in `issues`, and resubmit.",
                     });

package/dist/tools/research/generate-plan.js

@@ -41,6 +41,7 @@ import { hydratePlanSteps, PlannerPlanSchema } from "../../schemas/plan-schemas.
 import { validatePlan } from "../../schemas/validate-plan.js";
 import { AnalysisPlanSchema } from "../../schemas/workflow-state.js";
 import { unwrapOrThrow } from "../../lib/result.js";
+import { hintForZodIssue } from "../../lib/zod-issues.js";
 import { insertPlan, loadDataProfileStatus, loadPlan } from "../../state/index.js";
 // ── Tool-level config ──────────────────────────────────────────────
 /** Sub-agent identity for the planner — provenance only. */
@@ -201,11 +202,12 @@ async function persistPlan(plan, ctx, pool) {
     }
 }
 // ── Validation ──────────────────────────────────────────────────────
-function zodIssuesToValidationIssues(error, rootPath = "plan") {
+function zodIssuesToValidationIssues(error, input, rootPath = "plan") {
     return error.issues.map((i) => ({
         path: [rootPath, ...i.path.map((p) => String(p))].join("."),
         code: "schema",
         message: i.message,
+        hint: hintForZodIssue(i, input),
     }));
 }
 /**
@@ -215,7 +217,7 @@ function zodIssuesToValidationIssues(error, rootPath = "plan") {
 function fullyValidate(candidate, resourcePolicy) {
     const parsed = PlannerPlanSchema.safeParse(candidate);
     if (!parsed.success) {
-        return { valid: false, issues: zodIssuesToValidationIssues(parsed.error) };
+        return { valid: false, issues: zodIssuesToValidationIssues(parsed.error, candidate) };
     }
     // Semantic checks operate on the AnalysisPlan shape — PlannerPlan omits
     // maxSteps, so inject the execution-time default to satisfy the validator.

package/dist/tools/research/inspect-run.d.ts

@@ -9,8 +9,8 @@
  * conversation thread on completion. The retired `run-result-writer` push
  * payload (run status, step summaries, run synthesis, artifact paths) is
  * surfaced here on demand: the run row + step `summaryPath` references +
- * the `synthesisPath` for completed runs let the conversation agent
- * `read_file` the artefacts it needs.
+ * the `synthesisPath` for runs whose synthesis was produced let the
+ * conversation agent `read_file` the artefacts it needs.
  */
 import type { Pool } from "pg";
 import type { CortexRunRow } from "../../state/schema.js";
@@ -39,6 +39,7 @@ type InspectRunOutput = {
 };
 declare function formatRun(r: CortexRunRow, verbose: boolean): {
     error?: string | null | undefined;
+    synthesisReason?: string | undefined;
     runId: string;
     workflowName: string;
     status: "running" | "completed" | "failed" | "partial" | "canceled" | "suspended_insufficient_funds";
@@ -46,6 +47,7 @@ declare function formatRun(r: CortexRunRow, verbose: boolean): {
     completedAt: string | null;
     planId: string | null;
     synthesisPath: string | null;
+    synthesisStatus: "failed" | "produced" | "skipped_no_summaries" | "skipped_blocker" | null;
 };
 export declare function createInspectRunTool(pool: Pool): import("../define-tool.js").Tool<{
     runId?: string | undefined;

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

@@ -9,8 +9,8 @@
  * conversation thread on completion. The retired `run-result-writer` push
  * payload (run status, step summaries, run synthesis, artifact paths) is
  * surfaced here on demand: the run row + step `summaryPath` references +
- * the `synthesisPath` for completed runs let the conversation agent
- * `read_file` the artefacts it needs.
+ * the `synthesisPath` for runs whose synthesis was produced let the
+ * conversation agent `read_file` the artefacts it needs.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
@@ -26,7 +26,15 @@ function formatRun(r, verbose) {
         startedAt: r.startedAt,
         completedAt: r.completedAt,
         planId: r.planId,
-        synthesisPath: r.status === "completed" ? `runs/${r.runId}/synthesis.json` : null,
+        // synthesis.json is written only when synthesis actually produced a
+        // result; a skipped/failed synthesis leaves no file, so pointing at a
+        // path would send the agent to a stale or absent artifact. The recorded
+        // outcome — surfaced as synthesisStatus (and synthesisReason when set) —
+        // lets a consumer tell "produced" from "skipped/failed/unknown" without
+        // reading a file.
+        synthesisPath: r.synthesisStatus === "produced" ? `runs/${r.runId}/synthesis.json` : null,
+        synthesisStatus: r.synthesisStatus,
+        ...(r.synthesisReason !== null ? { synthesisReason: r.synthesisReason } : {}),
         ...(verbose ? { error: r.error } : {}),
     };
 }
@@ -35,7 +43,7 @@ export function createInspectRunTool(pool) {
         id: "inspect_run",
         description: "Inspect workflow runs for this analysis. " +
             "Without a runId: lists all runs. " +
-            "With a runId: returns step-level details with paths to summary.md (and synthesis.json on completed runs). " +
+            "With a runId: returns step-level details with paths to summary.md, plus each run's synthesisStatus and a synthesisPath to synthesis.json only when synthesis was produced. " +
             "Default response is lightweight — pass includeDiagnostics:true to add error/duration/retry telemetry. " +
             "Read summary.md or synthesis.json for findings, or use workspace search with type:summary or type:synthesis.",
         inputSchema: z.object({

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

@@ -58,6 +58,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 { AnalysisStep } from "../schemas/workflow-state.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
@@ -297,6 +298,8 @@ export declare function synthesizeFindings(args: {
     deps: ExecuteAnalysisDeps;
 }): Promise<{
     findings: readonly RunFinding[];
+    synthesisStatus: Exclude<SynthesisStatus, "failed">;
+    synthesisReason: string | null;
 }>;
 /**
  * Register the executeAnalysis parent workflow with DBOS. Caller is

package/dist/workflows/execute-analysis.js

@@ -59,7 +59,7 @@ 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 { RunDedupCollisionError, countArtifactsForRun, loadDataProfileStatus, queryActiveRun, queryStepArtifactPaths, seedStepExecutions, setRunSynthesisOutcome, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, } from "../state/index.js";
 import { isBudgetExceeded } from "../loop/budget-exceeded.js";
 import { loadStepSummariesFromDisk } from "../execution/run-synthesis.js";
 import { MAX_UPSTREAM_ARTIFACTS, composeStepBriefing } from "../prompts/briefing.js";
@@ -224,6 +224,7 @@ export function synthesizeFindings(args) {
         return DBOS.writeStream("events", part);
     };
     return synthesizeRun({
+        logger: deps.logger,
         pool: deps.pool,
         provider: deps.provider,
         embedding: deps.embedding,
@@ -333,6 +334,9 @@ export async function runExecuteAnalysisBody(input, deps) {
     // after so the workflow record goes to ERROR.
     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.
+    let synthesisOutcome = null;
     const synthesisEnabled = deps.synthesisEnabled ?? true;
     if (synthesisEnabled && final.completed.size > 0) {
         try {
@@ -344,9 +348,11 @@ export async function runExecuteAnalysisBody(input, deps) {
                 deps,
             }), { name: "synthesize-findings" });
             synthesisFindings = synthOut.findings;
+            synthesisOutcome = { status: synthOut.synthesisStatus, reason: synthOut.synthesisReason };
         }
         catch (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) });
         }
     }
@@ -369,6 +375,7 @@ export async function runExecuteAnalysisBody(input, deps) {
             : final.failureReason,
         forceFailed: synthesisError !== null,
         findings: synthesisFindings,
+        synthesisOutcome,
         deps,
     });
     // Synthesis failure takes priority over the budget-exceeded cascade: a run
@@ -741,6 +748,22 @@ async function collectAndComplete(args) {
     catch (err) {
         logger.error("persist-final-status failed", { status, ...logger.errorFields(err) });
     }
+    // Record the run's synthesis outcome AFTER the status write — a reader that
+    // sees a terminal status then also sees whether (and why) synthesis ran. A
+    // null outcome means synthesis never ran; leave the columns NULL ("unknown").
+    // Log-don't-rollback, like the sibling terminal steps: a failed ledger note
+    // must not undo an otherwise-complete run.
+    const outcome = args.synthesisOutcome;
+    if (outcome !== null) {
+        try {
+            await DBOS.runStep(async () => {
+                unwrapOrThrow(await setRunSynthesisOutcome(deps.pool, runId, outcome.status, outcome.reason));
+            }, { name: "persist-synthesis-outcome" });
+        }
+        catch (err) {
+            logger.error("persist-synthesis-outcome failed", { synthesisStatus: outcome.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
     // 402 pause below also writes "canceled", yet its pending rows must survive

package/package.json

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