@inflexa-ai/harness 0.14.2 → 0.15.1

package/dist/workflows/execute-analysis.js

@@ -66,6 +66,7 @@ import { createNoopLogger } from "../lib/console-logger.js";
 import { unwrapOrThrow } from "../lib/result.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 { addChatUsage, hasReportedUsage } from "../loop/metrics.js";
 import { SYNTHESIS_AGENT_ID, loadStepSummariesFromDisk } from "../execution/run-synthesis.js";
 import { MAX_UPSTREAM_ARTIFACTS, composeStepBriefing } from "../prompts/briefing.js";
 import { SYNTHESIS_STEP_ID, runDir, runStepDir, stepSubdir, stepWritePrefix, toSandboxPath } from "../workspace/paths.js";
@@ -319,11 +320,22 @@ export function synthesizeFindings(args) {
         resolveWorkspaceRoot: deps.resolveWorkspaceRoot,
         synthesisModel: deps.synthesisModel,
         bioKeys: deps.bioKeys,
+        usageRecorder: deps.usageRecorder,
     }, {
         analysisId,
         runId,
         completedSteps,
-        session,
+        // Stepped, exactly as a sandbox step's child input is. Synthesis owns a real row in the
+        // step-execution ledger (seeded and updated under `SYNTHESIS_STEP_ID` in the body below),
+        // so it lists as a step everywhere a run's steps are shown. Handing it the bare run session
+        // left every call it makes — the synthesizer loop and each sub-agent it dispatches —
+        // recorded against the run carrying no `stepId`, which made the one step in the list unable
+        // to report a figure the one that had just spent the most.
+        //
+        // It also puts the step id into the replay-stable `recordKey`, which is what it is for:
+        // synthesis and a plan step of the same run can no longer mint the same key from the same
+        // call path.
+        session: forStep(session, SYNTHESIS_STEP_ID),
         emit,
         onProgress: (phase, activity, extra = {}) => DBOS.writeStream("events", {
             type: "data-synthesis-progress",
@@ -530,6 +542,7 @@ export async function runExecuteAnalysisBody(input, deps) {
         failed: final.failed,
         canceled: final.canceled,
         budgetExceeded: final.budgetExceeded,
+        ...(final.usage ? { usage: final.usage } : {}),
         failureReason: synthesisError
             ? synthesisError instanceof Error
                 ? `synthesis-failed: ${synthesisError.message}`
@@ -601,6 +614,12 @@ async function runSchedulerLoop(args) {
     const canceled = new Set();
     const inFlight = new Map();
     const budgetExceededChildIds = new Set();
+    // Run-level usage aggregate, folded from the children's own durable results.
+    // `getResult` IS the replay-safe source: a recovered parent reads back the
+    // identical value from each child's workflow record, so the sum reproduces
+    // exactly without a second channel. A child that settled by throwing carries
+    // no result and therefore contributes nothing — same rule as its duration.
+    const runUsage = {};
     // Child workflow ids the parent itself cancelled (budget / neverFits halt cascade). Their `getResult`
     // rejects with a DBOS cancellation error and lands in the settlement error branch — but the step was
     // CANCELED by us, not failed on its own merits. Keyed here (deterministic: `cancelInFlight` runs the
@@ -798,6 +817,7 @@ async function runSchedulerLoop(args) {
         let stepDurationMs;
         if (settled.kind === "result") {
             const r = settled.result;
+            addChatUsage(runUsage, r.usage);
             if (r.status === "complete") {
                 completed.add(settled.stepId);
                 stepRuntime.set(settled.stepId, {
@@ -912,7 +932,15 @@ async function runSchedulerLoop(args) {
         });
     }
     await drainBudgetExceededNotifications(budgetExceededChildIds);
-    return { completed, failed, canceled, budgetExceeded, failureReason, stepStates: stepRuntime };
+    return {
+        completed,
+        failed,
+        canceled,
+        budgetExceeded,
+        failureReason,
+        stepStates: stepRuntime,
+        ...(hasReportedUsage(runUsage) ? { usage: { ...runUsage } } : {}),
+    };
 }
 async function drainBudgetExceededNotifications(childIds) {
     while (true) {
@@ -1068,6 +1096,7 @@ async function collectAndComplete(args) {
                     note: `${completed.size} of ${input.steps.length} steps completed; results are partial.`,
                 }
                 : {}),
+            ...(args.usage ? { usage: args.usage } : {}),
         });
     }
     else {

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

@@ -35,6 +35,7 @@ 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 { UsageRecorder } from "../billing/usage-recorder.js";
 import type { AgentChat } from "../providers/types.js";
 import { TargetAssessmentInputSchema } from "./target-assessment/schemas.js";
 import { type ProgressPhase } from "./target-assessment/progress.js";
@@ -88,6 +89,8 @@ export interface ExecuteTargetAssessmentDeps {
     readonly decisionModel: string;
     /** Billing-gateway model for synthesis agents — typically `env.TARGET_ASSESSMENT_SYNTHESIS_MODEL`. */
     readonly synthesisModel: string;
+    /** LLM usage-accounting seam for the assessment's agent loops; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
 }
 /**
  * Register the executeTargetAssessment workflow with DBOS. Caller is

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

@@ -26,8 +26,10 @@
  * parent (`executeAnalysis`). This child only owns its own teardown and
  * its own self-cancel on 402.
  */
+import type { TokenUsageRollup } from "@inflexa-ai/harness/contracts/usage.js";
 import type { Pool } from "pg";
 import type { Logger } from "../lib/logger.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { AgentDefinition, LoopMessage } from "../loop/types.js";
 import type { AgentChat, EmbeddingProvider } from "../providers/types.js";
 import { type RunSession } from "../auth/types.js";
@@ -125,6 +127,17 @@ export interface SandboxStepResult {
     readonly durationMs: number;
     readonly finishReason: string | null;
     readonly error: string | null;
+    /**
+     * What this step's agent loop reported spending. Absent when it reported
+     * nothing — never an all-zero figure.
+     *
+     * Durable by virtue of being the child's workflow result: the parent folds
+     * the run's aggregate from these, and a recovered parent reads back the same
+     * values, so the aggregate needs no side channel to survive replay. Optional
+     * because this is a durable shape — a child that settled under an older
+     * result shape recovers without it.
+     */
+    readonly usage?: TokenUsageRollup;
 }
 /** One file in the step's terminal file tree / output listing. */
 export interface StepFileEntry {
@@ -204,6 +217,11 @@ export interface SandboxStepDeps {
      * account of why a step died.
      */
     readonly logger?: Logger;
+    /**
+     * LLM usage-accounting seam. Covers this step's agent loop and the
+     * post-step sub-agent loops alike; omitted falls back to the no-op recorder.
+     */
+    readonly usageRecorder?: UsageRecorder;
     /** Non-streaming chat — drives the agent loop + the post-step sub-agents. */
     readonly provider: AgentChat;
     /** Write-side embedder for the post-step vector index. */
@@ -275,3 +293,8 @@ export declare function createLineageCollector(input: Pick<SandboxStepInput, "st
  * `dbos.application_versions` without per-workflow config.
  */
 export declare function registerSandboxStep(deps: SandboxStepDeps): (input: SandboxStepInput) => Promise<SandboxStepResult>;
+/**
+ * Body extracted so tests can drive it without registering a workflow
+ * (the DBOS calls inside still rely on a workflow context being present).
+ */
+export declare function runSandboxStepBody(input: SandboxStepInput, deps: SandboxStepDeps): Promise<SandboxStepResult>;

package/dist/workflows/sandbox-step.js

@@ -34,6 +34,7 @@ import { isBudgetExceeded } from "../loop/budget-exceeded.js";
 import { runAgent } from "../loop/run-agent.js";
 import { durableStep } from "../loop/run-step.js";
 import { 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";
 import { collectStepOutputs, generateStepFileMetadata, generateStepSummaryAndWrite, reconcileAndRegisterStepArtifacts, vectorIndexStepOutputs, } from "../execution/post-step-pipeline.js";
@@ -110,7 +111,7 @@ export function registerSandboxStep(deps) {
  * Body extracted so tests can drive it without registering a workflow
  * (the DBOS calls inside still rely on a workflow context being present).
  */
-async function runSandboxStepBody(input, deps) {
+export async function runSandboxStepBody(input, deps) {
     // Step coordinates bind once — every record below carries them without each
     // call site restating them. REPLAY: a recovered workflow re-executes this body
     // and re-emits its records, so a reader dedups by (runId, stepId), not by count.
@@ -193,6 +194,9 @@ async function runSandboxStepBody(input, deps) {
         lineageCollector,
         blockerHolder,
     });
+    // Built over THIS agent's tools, not a shared table: a sandbox agent's roster
+    // differs per agent type, and each tool describes its own calls.
+    const resolveDetail = createDetailResolver(agent.tools, logger);
     // Forward every loop event onto the child's own DBOS `"events"` stream
     // (the route fans-in parent + every active child stream — Pattern A).
     // Pre-shaped chat data parts (e.g. `data-sandbox-event` from `run-exec.ts`)
@@ -301,7 +305,7 @@ async function runSandboxStepBody(input, deps) {
         // envelope, and surface each tool call as live step activity.
         await safeEmit({ type: "data-loop-event", data: { stepId: input.stepId, event } });
         if (event.type === "tool-started") {
-            await emitActivity("executing", activityForTool(event.name, event.input));
+            await emitActivity("executing", activityForTool(event.name, event.input, resolveDetail));
         }
     };
     const initial = [{ role: "user", content: input.prompt }];
@@ -312,12 +316,14 @@ async function runSandboxStepBody(input, deps) {
     let transcript;
     let finishReason;
     let hitMaxSteps;
+    let stepUsage;
     try {
         const agentResult = await runAgent(agent, initial, session, {
             provider: deps.provider,
             signal: neverAbort,
             emit,
             runStep: durableStep,
+            usageRecorder: deps.usageRecorder,
             formatStepName: {
                 llm: (iteration) => `llm:${iteration}`,
                 tool: (toolName, toolUseId) => `tool:${toolName}:${toolUseId}`,
@@ -327,6 +333,7 @@ async function runSandboxStepBody(input, deps) {
         transcript = agentResult.messages;
         finishReason = agentResult.finish.reason;
         hitMaxSteps = agentResult.finish.cappedOut;
+        stepUsage = agentResult.finish.usage;
     }
     catch (err) {
         if (isBudgetExceeded(err)) {
@@ -380,6 +387,28 @@ async function runSandboxStepBody(input, deps) {
         // `failStep` always throws; the outer `throw` is for control-flow analysis.
         throw await failStep("agent_loop", err);
     }
+    // What the step's loop spent, emitted the moment the loop is done and before
+    // any branch that can end the step — so a step that later blocks or fails its
+    // post-step pipeline has still reported what it cost.
+    //
+    // No rollup means NO PART: the part's contract is to carry a step's rollup,
+    // and a loop that reported nothing has none to carry. A part naming the step
+    // with an absent usage field would be a claim about a figure nobody made.
+    //
+    // Stable id per (runId, stepId), like every other step part here, so a
+    // DBOS-replayed body's re-emission folds latest-wins onto the one part
+    // instead of appearing twice on the run's stream.
+    if (stepUsage) {
+        await safeEmit({
+            type: "data-step-usage",
+            id: stepPartId("step-usage", input.runId, input.stepId),
+            runId: input.runId,
+            stepId: input.stepId,
+            agentId: input.agentId,
+            modelId: agent.model,
+            usage: stepUsage,
+        });
+    }
     // Blocker (see the harness-sandbox-agents spec): the agent declared it cannot fulfil the step. A
     // blocked step has no deliverables — skip the artifact post-step pipeline,
     // mark `blocked` (carrying the reason), emit the blocked part, and return a
@@ -414,6 +443,7 @@ async function runSandboxStepBody(input, deps) {
             durationMs,
             finishReason,
             error: blockerOutcome.reason,
+            ...(stepUsage ? { usage: stepUsage } : {}),
         };
     }
     // (4-8) post-step — the body is the explicit composition: walk the artifact
@@ -547,6 +577,7 @@ async function runSandboxStepBody(input, deps) {
         durationMs,
         finishReason,
         error: null,
+        ...(stepUsage ? { usage: stepUsage } : {}),
     };
 }
 /**

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

@@ -19,6 +19,7 @@ import { z } from "zod";
 import type { Pool } from "pg";
 import type { AgentSession } from "../../../auth/types.js";
 import type { ChatProvider } from "../../../providers/types.js";
+import type { UsageRecorder } from "../../../billing/usage-recorder.js";
 export declare const OffTargetAnnotationSchema: z.ZodObject<{
     clinical_consequence: z.ZodString;
     provenance: z.ZodString;
@@ -28,6 +29,8 @@ export interface ClinicalConsequenceAnnotatorDeps {
     readonly provider: ChatProvider;
     readonly session: AgentSession;
     readonly model: string;
+    /** LLM usage-accounting seam for the annotator loop; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
 }
 export interface AnnotationInput {
     primaryTargetGene: string;

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

@@ -126,6 +126,7 @@ export async function annotateClinicalConsequence(pool, input, deps) {
             signal: controller.signal,
             emit: () => { },
             runStep: passthroughStep,
+            usageRecorder: deps.usageRecorder,
         });
         const raw = extractJsonObject(finalText(messages));
         if (raw === null)

package/package.json

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