@inflexa-ai/harness 0.43.1 → 0.45.0

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

@@ -50,8 +50,9 @@
  *       the run before any step starts
  *     - a `suspend` error of a synthesis model request suspends the run in
  *       place of the synthesis failure
- *     - the analysis flips to `suspended_insufficient_funds` in
- *       `collectAndComplete`. The paused parent lands in `CANCELLED`, a
+ *     - the run row and the analysis flip to `suspended_insufficient_funds` in
+ *       `collectAndComplete`. The run status is terminal and does not block a
+ *       new run of the plan. The paused parent lands in `CANCELLED`, a
  *       durably reschedulable state; re-driving it is a future enhancement,
  *       not yet wired here. The reason of the host rides to the run row, the
  *       charge close, the metric, and the terminal part, unread.
@@ -160,7 +161,7 @@ export interface ExecuteAnalysisInput {
  * path returns — the caller joined an in-flight run, no new workflow was
  * started. Every other variant is a terminal status the parent reached.
  */
-export type ExecuteAnalysisFinalStatus = "running" | "completed" | "partial" | "failed" | "canceled";
+export type ExecuteAnalysisFinalStatus = "running" | "completed" | "partial" | "failed" | "canceled" | "suspended_insufficient_funds";
 export interface ExecuteAnalysisResult {
     readonly runId: string;
     readonly workflowId: string;

package/dist/workflows/execute-analysis.js

@@ -50,8 +50,9 @@
  *       the run before any step starts
  *     - a `suspend` error of a synthesis model request suspends the run in
  *       place of the synthesis failure
- *     - the analysis flips to `suspended_insufficient_funds` in
- *       `collectAndComplete`. The paused parent lands in `CANCELLED`, a
+ *     - the run row and the analysis flip to `suspended_insufficient_funds` in
+ *       `collectAndComplete`. The run status is terminal and does not block a
+ *       new run of the plan. The paused parent lands in `CANCELLED`, a
  *       durably reschedulable state; re-driving it is a future enhancement,
  *       not yet wired here. The reason of the host rides to the run row, the
  *       charge close, the metric, and the terminal part, unread.
@@ -79,12 +80,13 @@ import { ATTR_INFLEXA_STEP_ID, stableSpan } from "../lib/otel-spans.js";
 import { recordRunCompleted, recordStepCompleted, stepOutcomeOf } from "../lib/metrics.js";
 import { describeDbError } from "../lib/db-result.js";
 import { unwrapOrThrow } from "../lib/result.js";
-import { countArtifactsForRun, insertStepExecution, loadDataProfileStatus, queryActiveRun, queryStepArtifactPaths, queryStepsByRun, seedStepExecutions, setRunSynthesisOutcome, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, updateStepExecution, } from "../state/index.js";
+import { countArtifactsByRuns, insertStepExecution, loadDataProfileStatus, queryActiveRun, queryStepArtifactPaths, queryStepsByRun, seedStepExecutions, setRunSynthesisOutcome, suspendAnalysis as suspendAnalysisQuery, sweepPendingStepExecutions, updateRunStatus, updateStepExecution, } from "../state/index.js";
 import { addChatUsage, hasReportedUsage } from "../loop/metrics.js";
+import { flattenDataPart } from "../contracts/chat-frame.js";
 import { SYNTHESIS_AGENT_ID, loadStepSummariesFromDisk } from "../execution/run-synthesis.js";
 import { MAX_UPSTREAM_ARTIFACTS, composeStepBriefing, emptyStepMemory } from "../prompts/briefing.js";
 import { SYNTHESIS_STEP_ID, runDir, runStepDir, stepSubdir, stepWritePrefix, toSandboxPath } from "../workspace/paths.js";
-import { isChatDataPart } from "../sandbox/sandbox-step-translate.js";
+import { isChatDataPart, synthesisEmission } from "../sandbox/sandbox-step-translate.js";
 import { synthesizeRun } from "../app/synthesize-run.js";
 import { computeTopologicalLevels, scheduleReady, validatePlanDag } from "./execute-analysis-scheduler.js";
 import { recordCancelledChild } from "./metrics.js";
@@ -250,7 +252,7 @@ export async function gatherStepPackage(args) {
         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);
+    const workspaceRoot = await 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
@@ -359,9 +361,20 @@ export function synthesisRowUpdate(outcome, durationMs) {
  */
 export function synthesizeFindings(args) {
     const { analysisId, runId, completedSteps, session, deps } = args;
+    const logger = (deps.logger ?? createNoopLogger()).named("executeAnalysis.synthesis");
+    // Observation is a diagnostic channel: a failed progress write is logged and never fails the synthesis.
+    let progressSeq = 0;
+    const writeProgressAlone = async (part, phase) => {
+        try {
+            await DBOS.writeStream("events", part);
+        }
+        catch (err) {
+            logger.warn("synthesis progress write failed (non-fatal)", { phase, ...logger.errorFields(err) });
+        }
+    };
     const emit = (event) => {
         const part = isChatDataPart(event)
-            ? event
+            ? flattenDataPart(event)
             : {
                 type: "data-loop-event",
                 data: { stepId: "synthesis", event },
@@ -395,14 +408,15 @@ export function synthesizeFindings(args) {
         // call path.
         session: forStep(session, SYNTHESIS_STEP_ID),
         emit,
-        onProgress: (phase, activity, extra = {}) => DBOS.writeStream("events", {
-            type: "data-synthesis-progress",
-            id: `synthesis-progress-${runId}`,
-            runId,
-            phase,
-            activity,
-            ...extra,
-        }),
+        onProgress: async (phase, activity, extra = {}) => {
+            // Synthesis runs inside one `DBOS.runStep`, thus `DBOS.now()` reads the wall clock here, and a rerun of
+            // the step after a crash writes its entries again under the same ids. A reader dedups an entry by id.
+            const seq = progressSeq++;
+            const at = new Date(await DBOS.now()).toISOString();
+            const parts = synthesisEmission(runId, SYNTHESIS_STEP_ID, seq, phase, activity, at, extra);
+            await writeProgressAlone(parts.progress, phase);
+            await writeProgressAlone(parts.entry, phase);
+        },
     });
 }
 // ── Workflow registration ────────────────────────────────────────────
@@ -661,10 +675,10 @@ async function validateAndInit(input, runId, deps) {
         return { kind: "joined-existing", runId: existing.runId };
     }
     await DBOS.runStep(async () => {
-        // A resolver throw here (unknown analysis, unresolvable root) fails the
+        // A resolver rejection here (unknown analysis, unresolvable root) fails the
         // step durably — exactly the contract the workspace-root-resolution spec
         // requires of failures inside DBOS bodies.
-        await mkdir(join(deps.resolveWorkspaceRoot(input.analysisId), runDir(runId)), {
+        await mkdir(join(await deps.resolveWorkspaceRoot(input.analysisId), runDir(runId)), {
             recursive: true,
         });
     }, { name: "init-run-filesystem" });
@@ -1086,7 +1100,7 @@ async function collectAndComplete(args) {
         durationMs: terminalAtMs - startedAtMs,
     }, input.runSession);
     await ledgerStep(logger.with({ status }), "persist-final-status", async () => {
-        const written = await updateRunStatus(deps.pool, runId, status, failureReason ?? (status === "canceled" && suspended === null ? "external_cancel" : null));
+        const written = await updateRunStatus(deps.pool, runId, status, failureReason ?? (status === "canceled" ? "external_cancel" : null));
         if (written.isErr())
             return written;
         // The outcome metrics ride inside the step that persists the terminal status: DBOS
@@ -1119,10 +1133,9 @@ async function collectAndComplete(args) {
         await ledgerStep(logger.with({ synthesisStatus: outcome.status }), "persist-synthesis-outcome", () => setRunSynthesisOutcome(deps.pool, runId, outcome.status, outcome.reason));
     }
     // Sweep never-started steps to `skipped` — but ONLY on genuinely-terminal
-    // paths. The gate is the BRANCH, not the written run status: the resumable
-    // suspension below also writes "canceled", yet its pending rows must survive
-    // for the resumed workflow to execute. Log-don't-rollback, like every other
-    // finalisation step here.
+    // paths. The gate is the BRANCH, not the written run status: the pending rows
+    // of a suspended run must survive for a later resume. Log-don't-rollback, like
+    // every other finalisation step here.
     if (suspended === null) {
         await ledgerStep(logger, "sweep-pending-steps", () => sweepPendingStepExecutions(deps.pool, runId));
     }
@@ -1149,9 +1162,9 @@ async function collectAndComplete(args) {
     // beat the CLI's poll-and-shutdown). These branches only fan out the UI stream part, whose
     // completed/failed shapes genuinely differ — the provenance record does not.
     if (status === "completed" || status === "partial") {
-        const artifactCount = await DBOS.runStep(async () => await countArtifactsForRun(deps.pool, input.analysisId, runId).unwrapOr(0), {
-            name: "count-run-artifacts",
-        });
+        const artifactCount = await DBOS.runStep(async () => await countArtifactsByRuns(deps.pool, input.analysisId, [runId])
+            .map((counts) => counts[0]?.count ?? 0)
+            .unwrapOr(0), { name: "count-run-artifacts" });
         await emitStreamPart({
             type: "data-run-completed",
             runId,
@@ -1197,7 +1210,7 @@ async function collectAndComplete(args) {
 function deriveFinalStatus(args) {
     const { totalSteps, completed, failed, canceled, suspended } = args;
     if (suspended)
-        return "canceled";
+        return "suspended_insufficient_funds";
     if (failed.size > 0) {
         return completed.size > 0 ? "partial" : "failed";
     }

package/dist/workflows/plan/graph.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The graph of a stored plan: each step with its agent, its dependencies, and its
+ * level. The levels and the agent fallback are those of `data-dag-state`, so a
+ * host draws the same graph before, during, and after a run.
+ */
+import type { PlanGraphStep } from "../../contracts/chat-parts.js";
+/**
+ * Give the graph of a stored plan document, in the order of the plan. An empty
+ * step list gives an empty graph. A document that fails the stored plan schema, or
+ * whose steps have a duplicate id, a missing dependency, or a cycle, gives `null`
+ * (a plan that no run can execute has no levels).
+ *
+ * The throw of `validatePlanDag` is caught here, at the boundary: the function is a
+ * read for a caller that has no use for the typed error.
+ */
+export declare function planGraphOf(plan: unknown): PlanGraphStep[] | null;

package/dist/workflows/plan/graph.js

@@ -0,0 +1,36 @@
+/**
+ * The graph of a stored plan: each step with its agent, its dependencies, and its
+ * level. The levels and the agent fallback are those of `data-dag-state`, so a
+ * host draws the same graph before, during, and after a run.
+ */
+import { AnalysisPlanSchema } from "../../schemas/workflow-state.js";
+import { computeTopologicalLevels, validatePlanDag } from "../execute-analysis-scheduler.js";
+/**
+ * Give the graph of a stored plan document, in the order of the plan. An empty
+ * step list gives an empty graph. A document that fails the stored plan schema, or
+ * whose steps have a duplicate id, a missing dependency, or a cycle, gives `null`
+ * (a plan that no run can execute has no levels).
+ *
+ * The throw of `validatePlanDag` is caught here, at the boundary: the function is a
+ * read for a caller that has no use for the typed error.
+ */
+export function planGraphOf(plan) {
+    const parsed = AnalysisPlanSchema.safeParse(plan);
+    if (!parsed.success)
+        return null;
+    const steps = parsed.data.steps;
+    try {
+        validatePlanDag(steps);
+    }
+    catch {
+        return null;
+    }
+    const levels = computeTopologicalLevels(steps);
+    return steps.map((step) => ({
+        id: step.id,
+        name: step.name,
+        agent: step.agent ?? "unknown",
+        dependsOn: [...step.depends_on],
+        level: levels.get(step.id) ?? 0,
+    }));
+}

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

@@ -263,12 +263,12 @@ export interface SandboxStepDeps {
      * agent from the catalog, wires its workspace tools, and returns the
      * configured `AgentDefinition` runAgent will drive.
      */
-    buildAgent(ctx: SandboxAgentBuildContext): AgentDefinition;
+    buildAgent(ctx: SandboxAgentBuildContext): Promise<AgentDefinition>;
     /**
      * Resolve the absolute writable artifact prefix for this step. The
      * workspace mutate tools enforce write confinement against this path.
      */
-    resolveWritePrefix(input: SandboxStepInput): string;
+    resolveWritePrefix(input: SandboxStepInput): Promise<string>;
 }
 /**
  * Per-step context passed to every post-step dep. Carries the durable input

package/dist/workflows/sandbox-step.js

@@ -38,7 +38,7 @@ import { durableStep } from "../loop/run-step.js";
 import { maskExcept } from "../loop/tool-mask.js";
 import { READ_TOOL_OUTPUT_TOOL_ID } from "../loop/tool-output.js";
 import { lastExecOutcome } from "../sandbox/exec-outcome.js";
-import { activityForTool, applyTreeDelta, isChatDataPart, sandboxTreeDelta, stepPartId } from "../sandbox/sandbox-step-translate.js";
+import { activityEmission, activityForTool, applyTreeDelta, isChatDataPart, sandboxTreeDelta, stepPartId } from "../sandbox/sandbox-step-translate.js";
 import { createDetailResolver } from "../tools/detail-resolver.js";
 import { forSubAgent } from "../auth/types.js";
 import { walkStepArtifacts } from "../execution/post-step.js";
@@ -176,7 +176,7 @@ export async function runSandboxStepBody(input, deps) {
     // "conversation-agent"). `run-agent.ts` builds source from
     // `session.provenance.agentId`, and billing tags ride the same provenance.
     const session = forSubAgent(input.runSession, input.agentId);
-    const writePrefix = deps.resolveWritePrefix(input);
+    const writePrefix = await deps.resolveWritePrefix(input);
     const lineageCollector = createLineageCollector(input);
     // (2a) sandbox.mint — checkpoint the machine's identity (its name)
     // BEFORE it is spawned (see the harness-sandbox-exec spec). Durable-before-create is what makes (2b)
@@ -220,7 +220,7 @@ export async function runSandboxStepBody(input, deps) {
     const stepDeadlineMs = (await DBOS.now()) + (input.timeoutSeconds ?? DEFAULT_STEP_TIMEOUT_SECONDS) * 1000;
     const blockerHolder = createBlockerHolder();
     const fileMetadata = createFileMetadataCell();
-    const agent = deps.buildAgent({
+    const agent = await deps.buildAgent({
         input,
         session,
         sandbox,
@@ -266,17 +266,19 @@ export async function runSandboxStepBody(input, deps) {
             logger.warn("emitToParentStream failed (non-fatal)", logger.errorFields(err));
         }
     };
-    // Schema-conformant step-activity emitter — stable id per (runId, stepId)
-    // so the run-stream fold collapses every phase transition latest-wins.
-    const activityId = stepPartId("step-activity", input.runId, input.stepId);
-    const emitActivity = (phase, activity) => safeEmit({
-        type: "data-step-activity",
-        id: activityId,
-        runId: input.runId,
-        stepId: input.stepId,
-        phase,
-        activity,
-    });
+    // Schema-conformant step-activity emitter. `data-step-activity` has a stable id per (runId, stepId),
+    // so the run-stream fold collapses every phase transition latest-wins. Each emission also leaves one
+    // `data-activity-entry` that the fold keeps, thus a late subscriber gets each line with its time. The
+    // two parts share one checkpointed clock read. `activitySeq` advances before the clock read and the
+    // writes, and each write fails alone through `safeEmit`.
+    let activitySeq = 0;
+    const emitActivity = async (phase, activity) => {
+        const seq = activitySeq++;
+        const at = new Date(await DBOS.now()).toISOString();
+        const parts = activityEmission(input, seq, phase, activity, at);
+        await safeEmit(parts.activity);
+        await safeEmit(parts.entry);
+    };
     // Single exit for the two terminal failure paths (agent loop, lineage
     // attestation). Tears the sandbox down, logs the internal detail for
     // operators, then persists + emits only a generic phrase and re-raises a

package/dist/workspace/filesystem.js

@@ -32,7 +32,7 @@ import { lstat as fsLstat, open as fsOpen, readdir as fsReaddir, stat as fsStat
 import { constants as fsConstants } from "node:fs";
 import { createInterface } from "node:readline";
 import { join } from "node:path";
-import { ResultAsync, err, errAsync, ok } from "neverthrow";
+import { ResultAsync, ok } from "neverthrow";
 import { scopeResource } from "../auth/types.js";
 import { tryFetch, tryFs } from "../lib/fs-result.js";
 import { classifyWithinRoot } from "../lib/fs-helpers.js";
@@ -41,7 +41,7 @@ import { resolveWorkspacePath } from "./paths.js";
 export function createWorkspaceFilesystem(deps) {
     const { resolveWorkspaceRoot, presignedFallback } = deps;
     /**
-     * `ResolveWorkspaceRoot` signals an unresolvable resource by throwing — the contract that
+     * `ResolveWorkspaceRoot` signals an unresolvable resource by a rejection — the contract that
      * makes a resolution failure inside a DBOS body a durably-failed step. This seam is not a
      * DBOS body: it promises `Result`, and the read tools it backs are reachable from a live
      * chat turn whose analysis folder may have been moved or deleted since the turn began.
@@ -50,14 +50,12 @@ export function createWorkspaceFilesystem(deps) {
      */
     function resolveFor(session, path, workingDir) {
         const { resourceId: analysisId } = scopeResource(session.scope);
-        let workspaceRoot;
-        try {
-            workspaceRoot = resolveWorkspaceRoot(analysisId);
-        }
-        catch (cause) {
-            return err({ type: "read_failed", op: "workspace.resolveWorkspaceRoot", path: analysisId, cause });
-        }
-        return ok({ resolved: resolveWorkspacePath({ workspaceRoot, analysisId, path, workingDir }), workspaceRoot });
+        return ResultAsync.fromThrowable(resolveWorkspaceRoot, (cause) => ({
+            type: "read_failed",
+            op: "workspace.resolveWorkspaceRoot",
+            path: analysisId,
+            cause,
+        }))(analysisId).map((workspaceRoot) => ({ resolved: resolveWorkspacePath({ workspaceRoot, analysisId, path, workingDir }), workspaceRoot }));
     }
     /**
      * Lexical resolution PLUS a symlink-following confinement check — the single
@@ -70,18 +68,16 @@ export function createWorkspaceFilesystem(deps) {
      * presigned-fallback handling still runs (a non-existent path leaks nothing).
      */
     function confinedResolve(session, path, workingDir) {
-        const base = resolveFor(session, path, workingDir);
-        if (base.isErr())
-            return errAsync(base.error);
-        const { resolved, workspaceRoot } = base.value;
-        if (resolved.kind === "out_of_scope")
-            return okAsync(resolved);
-        return ResultAsync.fromPromise(classifyWithinRoot(workspaceRoot, resolved.absolute), (cause) => ({
-            type: "read_failed",
-            op: "workspace.confineRealpath",
-            path: resolved.absolute,
-            cause,
-        })).map((verdict) => (verdict === "escaped" ? { kind: "out_of_scope" } : resolved));
+        return resolveFor(session, path, workingDir).andThen(({ resolved, workspaceRoot }) => {
+            if (resolved.kind === "out_of_scope")
+                return okAsync(resolved);
+            return ResultAsync.fromPromise(classifyWithinRoot(workspaceRoot, resolved.absolute), (cause) => ({
+                type: "read_failed",
+                op: "workspace.confineRealpath",
+                path: resolved.absolute,
+                cause,
+            })).map((verdict) => (verdict === "escaped" ? { kind: "out_of_scope" } : resolved));
+        });
     }
     return {
         readFile({ session, path, maxBytes, headLines, tailLines, workingDir }) {

package/dist/workspace/paths.d.ts

@@ -43,11 +43,14 @@
  *   - **Stable while the resource has an active run** — derived paths are
  *     recorded in durable step outputs; preventing mid-run moves is the
  *     embedder's job.
- *   - **Throws on unknown resources** — inside DBOS bodies the failure must
- *     cross the step boundary as a throw so the step is durably recorded as
- *     failed (see `lib/result.ts` house rules).
+ *   - **Rejects on unknown resources** — inside DBOS bodies the awaited
+ *     rejection must cross the step boundary as a throw so the step is durably
+ *     recorded as failed (see `lib/result.ts` house rules).
+ *
+ * Async so that a realization can read host state (a marker file on a network
+ * mount) without a block of the event loop.
  */
-export type ResolveWorkspaceRoot = (resourceId: string) => string;
+export type ResolveWorkspaceRoot = (resourceId: string) => Promise<string>;
 /** Result of resolving a workspace path against the canonical layout. */
 export type ResolvedPath = {
     readonly kind: "ok";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.43.1",
+    "version": "0.45.0",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -33,7 +33,7 @@
         "directory": "harness"
     },
     "scripts": {
-        "build": "tsc -p tsconfig.json && node scripts/copy-assets.mjs",
+        "build": "tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
         "design:fixture": "bun scripts/render-fixture.ts",
         "design:gallery": "bun scripts/render-gallery.ts",
         "format": "prettier --write src/",
@@ -41,12 +41,12 @@
         "gallery:data": "bash scripts/gallery-data.sh",
         "lint": "eslint .",
         "lint:python": "ruff check src/input-scan/decoder && ruff format --check src/input-scan/decoder",
-        "prepare": "tsc -p tsconfig.json && node scripts/copy-assets.mjs",
+        "prepare": "tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
         "prepublishOnly": "bun run build && bun run smoke",
         "smoke": "node scripts/smoke.mjs",
         "test:full": "bash scripts/test-full.sh",
         "test:python": "python3 -m pytest src/input-scan/decoder -q",
-        "typecheck": "tsc --noEmit"
+        "typecheck": "tsc -p tsconfig.json --noEmit"
     },
     "dependencies": {
         "@ai-sdk/anthropic": "^4.0.62",