@inflexa-ai/harness 0.14.1 → 0.15.0

package/dist/tools/detail-resolver.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The name-plus-input detail resolver.
+ *
+ * The live loop holds the resolved `Tool` at dispatch and needs nothing. Every
+ * other surface — the reload converter, a workflow's live-activity line — has a
+ * tool NAME and a persisted input, so it needs a way back to the tool. This is
+ * that way, and it is deliberately built over a tool list the CALLER supplies:
+ *
+ * - A name map internal to the harness could never see an embedder's tools. A
+ *   host contributes tools through the host-tools seam, and those calls are as
+ *   ambiguous in a transcript as any other.
+ * - Two harness tools legitimately share one id (`write_file` exists in both the
+ *   workspace surface and the report version store). A resolver built from one
+ *   agent's list cannot hold both, because a tool list rejects a duplicate id at
+ *   registry construction.
+ *
+ * It resolves through the same `computeDetail` the loop uses, so a reloaded
+ * thread cannot show a different detail from the one the live turn showed.
+ * Nothing is persisted: storage stays the pure model transcript.
+ */
+import { type ToolCallDetail } from "../loop/tool-detail.js";
+import type { Logger } from "../lib/logger.js";
+import type { Tool } from "./define-tool.js";
+/**
+ * Maps a tool name plus a call's input to that call's detail. Yields
+ * `undefined` for an unknown tool, a tool with no hook, and an input the tool's
+ * schema rejects.
+ */
+export type ToolDetailResolver = (toolName: string, input: unknown) => ToolCallDetail | undefined;
+/**
+ * Build a resolver over `tools`. A duplicate id resolves to the first tool
+ * declaring it; callers pass one agent's composed list, which a registry has
+ * already rejected duplicates from.
+ */
+export declare function createDetailResolver(tools: readonly Tool[], logger?: Logger): ToolDetailResolver;

package/dist/tools/detail-resolver.js

@@ -0,0 +1,39 @@
+/**
+ * The name-plus-input detail resolver.
+ *
+ * The live loop holds the resolved `Tool` at dispatch and needs nothing. Every
+ * other surface — the reload converter, a workflow's live-activity line — has a
+ * tool NAME and a persisted input, so it needs a way back to the tool. This is
+ * that way, and it is deliberately built over a tool list the CALLER supplies:
+ *
+ * - A name map internal to the harness could never see an embedder's tools. A
+ *   host contributes tools through the host-tools seam, and those calls are as
+ *   ambiguous in a transcript as any other.
+ * - Two harness tools legitimately share one id (`write_file` exists in both the
+ *   workspace surface and the report version store). A resolver built from one
+ *   agent's list cannot hold both, because a tool list rejects a duplicate id at
+ *   registry construction.
+ *
+ * It resolves through the same `computeDetail` the loop uses, so a reloaded
+ * thread cannot show a different detail from the one the live turn showed.
+ * Nothing is persisted: storage stays the pure model transcript.
+ */
+import { computeDetail } from "../loop/tool-detail.js";
+import { createNoopLogger } from "../lib/console-logger.js";
+/**
+ * Build a resolver over `tools`. A duplicate id resolves to the first tool
+ * declaring it; callers pass one agent's composed list, which a registry has
+ * already rejected duplicates from.
+ */
+export function createDetailResolver(tools, logger) {
+    const log = (logger ?? createNoopLogger()).named("tool-detail");
+    const byId = new Map();
+    for (const tool of tools) {
+        if (!byId.has(tool.id))
+            byId.set(tool.id, tool);
+    }
+    return (toolName, input) => {
+        const tool = byId.get(toolName);
+        return tool === undefined ? undefined : computeDetail(tool, input, log);
+    };
+}

package/dist/tools/execute-analysis.js

@@ -152,6 +152,9 @@ export function createExecuteAnalysisTool(deps) {
             "that explicit request is consent and needs no synthetic-plan approval. If computation is merely your suggestion, ask first. " +
             "You never choose the sandbox specialist: ad hoc routing does that automatically. Returns runId with status=in_progress; inspect results on a later turn.",
         inputSchema,
+        // The mode is what a user most needs to see here — an approved plan
+        // running is a different event from an ad hoc request being routed.
+        describeCall: (input) => (input.mode === "plan" ? `plan ${input.planId ?? ""}` : `ad hoc: ${input.request ?? ""}`),
         execute: async (input, ctx) => {
             if (ctx.session.scope.kind !== "analysis")
                 throw new Error("execute_analysis requires an analysis-scoped session");

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

@@ -48,6 +48,7 @@ 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";
+import type { UsageRecorder } from "../billing/usage-recorder.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
@@ -209,6 +210,8 @@ export interface SubmitReportDeps {
         previewId: string;
         ttlSeconds: number;
     }) => Promise<PreviewPublisher>;
+    /** LLM usage-accounting seam for the report-builder loop; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
 }
 /**
  * `submit_report` — takes the composed brief and drives the report iteration.

package/dist/tools/iterate-report.js

@@ -654,6 +654,7 @@ export function createReportSubmitTool(deps) {
                 templatesDir: deps.templatesDir,
                 skillsDir: deps.skillsDir,
                 chrome: deps.chrome,
+                usageRecorder: deps.usageRecorder,
             }, {
                 resourceId,
                 workspaceRoot: analysisRoot,
@@ -665,6 +666,8 @@ export function createReportSubmitTool(deps) {
                 session: ctx.session,
                 signal: ctx.signal,
                 emit: ctx.emit,
+                turnUsage: ctx.turnUsage,
+                invocationId: ctx.invocationId,
             });
             if (!result.ok) {
                 await ctx.emit({

package/dist/tools/memory/update-working-memory.js

@@ -149,6 +149,14 @@ export function createUpdateWorkingMemoryTool(workingMemory, pool) {
             "user's last message, run contents (tables, gene lists, file paths), or anything you can retrieve " +
             "again with inspect_run, read_file, or search.",
         inputSchema,
+        // Four writes in one turn are four identical chips without this. The
+        // entry id rides along on revise/retire because it is the only thing
+        // separating two retirements from the same section.
+        describeCall: (input) => {
+            const operation = input.section === "goal" ? "set" : (input.operation ?? "add");
+            const target = input.id === undefined ? "" : ` ${input.id}`;
+            return `${operation} ${input.section}${target}`;
+        },
         execute: async (input, ctx) => {
             const analysisId = scopeResource(ctx.session.scope).resourceId;
             switch (input.section) {

package/dist/tools/research/generate-analogy-report.d.ts

@@ -15,6 +15,7 @@
 import { z } from "zod";
 import { type AnalogicalReasonerOutput } from "@inflexa-ai/harness/contracts/analogy-report.js";
 import type { ChatProvider } from "../../providers/types.js";
+import type { UsageRecorder } from "../../billing/usage-recorder.js";
 import { type Tool } from "../define-tool.js";
 import { type BioToolKeys } from "../bio/keys.js";
 export declare const generateAnalogyReportInputSchema: z.ZodObject<{
@@ -39,6 +40,8 @@ export interface GenerateAnalogyReportDeps {
     readonly model: string;
     /** API keys for the bio/chem + GitHub data sources the reasoner searches. */
     readonly bioKeys: BioToolKeys;
+    /** LLM usage-accounting seam for the child loop; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
 }
 /** Build the `generate_analogy_report` delegation tool bound to its provider. */
 export declare function createGenerateAnalogyReportTool(deps: GenerateAnalogyReportDeps): Tool;

package/dist/tools/research/generate-analogy-report.js

@@ -203,6 +203,12 @@ export function createGenerateAnalogyReportTool(deps) {
                     signal: ctx.signal,
                     emit: ctx.emit,
                     runStep: passthroughStep,
+                    usageRecorder: deps.usageRecorder,
+                    // Fold the child's calls into the turn total the root loop reports.
+                    turnUsage: ctx.turnUsage,
+                    // Keeps the usage record keys of two parallel dispatches disjoint —
+                    // same frame, same call path, same loop-local step names.
+                    invocationId: ctx.invocationId,
                 });
                 rawText = finalText(transcript);
             }

package/dist/tools/research/generate-plan.d.ts

@@ -25,6 +25,7 @@
  */
 import type { Pool } from "pg";
 import { type ChatProvider } from "../../providers/types.js";
+import type { UsageRecorder } from "../../billing/usage-recorder.js";
 import { type Tool } from "../define-tool.js";
 import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
 import { type ResourcePolicy } from "../../config/resource-limits.js";
@@ -49,6 +50,8 @@ export interface GeneratePlanDeps extends EnvironmentStorePaths {
     readonly resourcePolicy?: ResourcePolicy;
     /** Diagnostic sink. Absent, the tool runs silently — see `RunAgentOptions.logger`. */
     readonly logger?: Logger;
+    /** LLM usage-accounting seam for the planner loop; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
 }
 /** Build the `generate_plan` tool bound to its provider and pool. */
 export declare function createGeneratePlanTool(deps: GeneratePlanDeps): Tool;

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

@@ -830,6 +830,12 @@ export function createGeneratePlanTool(deps) {
                     // as soon as one is recorded.
                     toolChoice: "required",
                     logger,
+                    usageRecorder: deps.usageRecorder,
+                    // Fold the planner's calls into the turn total the root loop reports.
+                    turnUsage: ctx.turnUsage,
+                    // Keeps the usage record keys of two parallel dispatches disjoint —
+                    // same frame, same call path, same loop-local step names.
+                    invocationId: ctx.invocationId,
                 }, {
                     tools: innerTools.terminal,
                     nudge: "You ended without a terminal outcome. Call submit_plan with " +

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

@@ -102,6 +102,10 @@ export function createInspectRunTool(pool, clock = systemClock) {
             "For a user-directed check, waitForTerminalSeconds can wait once for 1-30 seconds; if the cutoff returns in_progress, stop polling for that turn. " +
             "Default response is lightweight — pass includeDiagnostics:true to add error/duration/retry telemetry.",
         inputSchema,
+        // The two calls do different work: one inspects a named run, the other
+        // pages the list. Naming the run id is what separates repeated polls of
+        // the same run from polls of different ones.
+        describeCall: (input) => (input.runId === undefined ? `run list (page ${input.page ?? 1})` : input.runId),
         execute: async (input, ctx) => {
             const resourceId = scopeResource(ctx.session.scope).resourceId;
             const verbose = input.includeDiagnostics === true;

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

@@ -18,6 +18,7 @@ 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";
+import type { UsageRecorder } from "../../billing/usage-recorder.js";
 export interface LiteratureReviewerDeps {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
@@ -27,6 +28,8 @@ export interface LiteratureReviewerDeps {
     readonly model: string;
     /** API keys for the bio/chem data sources the reviewer searches. */
     readonly bioKeys: BioToolKeys;
+    /** LLM usage-accounting seam for the child loop; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
 }
 /** Build the `literature_reviewer` delegation tool bound to its provider. */
 export declare function createLiteratureReviewerTool(deps: LiteratureReviewerDeps): Tool;

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

@@ -72,6 +72,12 @@ export function createLiteratureReviewerTool(deps) {
                 signal: ctx.signal,
                 emit: ctx.emit,
                 runStep: passthroughStep,
+                usageRecorder: deps.usageRecorder,
+                // Fold the child's calls into the turn total the root loop reports.
+                turnUsage: ctx.turnUsage,
+                // Keeps the usage record keys of two parallel reviews disjoint —
+                // same frame, same call path, same loop-local step names.
+                invocationId: ctx.invocationId,
             });
             return ok({ report: finalText(transcript) });
         },

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

@@ -65,6 +65,8 @@ export function createEditFileTool(deps) {
             "/ `out_of_scope` / `file_not_found` / `not_found` / `not_unique` data " +
             "variants — never throws on expected outcomes.",
         inputSchema: EditFileInputSchema,
+        // The path only. The replaced text is file content, not a description.
+        describeCall: ({ path }) => path,
         execute: async ({ path, old_string, new_string, replace_all }, ctx) => {
             const read = unwrapOrThrow(await deps.workspaceFilesystem.readFile({
                 session: ctx.session,

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

@@ -42,6 +42,12 @@ const ExecuteCommandInputSchema = z.object({
     env: z.record(z.string(), z.string()).optional().describe("Extra environment variables for this command."),
     timeoutSeconds: z.number().int().positive().optional().describe("Per-command timeout in seconds; capped by the step deadline."),
 });
+/** Extensions that mark an argv token as the thing being run, not a flag or a data path. */
+const SCRIPT_EXTENSIONS = /\.(py|R|r|sh|js|ts|ipynb)$/;
+/** The first script-like token in an argv, or `undefined` when none looks like one. */
+function scriptToken(command) {
+    return command.find((arg) => SCRIPT_EXTENSIONS.test(arg));
+}
 export function createExecuteCommandTool(deps) {
     const { sandboxClient, sandbox, workflowId, stepId, nextFunctionId, deadlineMs, defaultCwd, markExecActive, lineageCollector, mountRoot } = deps;
     return defineTool({
@@ -58,6 +64,25 @@ export function createExecuteCommandTool(deps) {
             "analysis results via 'python -c' / inline one-liners and read them from " +
             "stdout; that work is lost. Write a script and persist its outputs to output/.",
         inputSchema: ExecuteCommandInputSchema,
+        // The script is what a reader recognises, and it survives a long
+        // invocation whose flags would otherwise push it past the length cap.
+        // When nothing in the argv looks like a script, the joined argv is the
+        // best account of the call there is.
+        //
+        // `env` never rides along. It is the channel this tool documents for
+        // secrets, so it is the one field guaranteed to hold them. An argv can
+        // hold one too (`--password …` is a real habit), and the emit-site
+        // redaction only matches the structured, prefixed formats — so the join
+        // is a deliberate trade, not a claim of safety.
+        //
+        // Know what the trade costs. This tool is sandbox-gated, so the only
+        // surface that reads its detail is a workflow's live-activity line — and
+        // that line goes to the run-event stream through `DBOS.writeStream`. The
+        // detail is therefore DURABLE, and every history read replays it. It
+        // stays inside the session's own analysis and never reaches the model,
+        // but display-only does not mean transient. A secret typed into an argv
+        // outlives the turn that ran it.
+        describeCall: ({ command }) => scriptToken(command) ?? command.join(" "),
         execute: async ({ command, cwd, env, timeoutSeconds }, ctx) => {
             const execId = `${workflowId}:${stepId}:${nextFunctionId()}`;
             const effectiveCwd = cwd === undefined ? defaultCwd : cwd.startsWith("/") ? cwd : posixPath.join(defaultCwd, cwd);

package/dist/tools/workspace/grep.js

@@ -38,6 +38,9 @@ export function createGrepTool(fs, workingDir) {
             "bytes per line — narrow your path or pattern if you hit the cap. " +
             "No matches and out-of-scope paths return data variants, not errors.",
         inputSchema: GrepInputSchema,
+        // Both fields, because either alone loses the call: the same pattern over
+        // two trees and two patterns over one tree are both ordinary sequences.
+        describeCall: ({ pattern, path }) => `${pattern} in ${path}`,
         execute: async ({ pattern, path, ignoreCase }, ctx) => {
             let regex;
             try {

package/dist/tools/workspace/list-files.js

@@ -24,6 +24,8 @@ export function createListFilesTool(fs, workingDir) {
             "else: it never reaches a directory outside the analysis, including the host process's current " +
             "working directory. Missing and out-of-scope paths return a data variant, not an error.",
         inputSchema: ListFilesInputSchema,
+        // The directory IS the call — two listings differ by nothing else.
+        describeCall: ({ path }) => path,
         execute: async ({ path }, ctx) => {
             const result = unwrapOrThrow(await fs.list({ session: ctx.session, path, workingDir }));
             switch (result.kind) {

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

@@ -62,6 +62,13 @@ export function createReadFileTool(fs, workingDir) {
             "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,
+        describeCall: ({ path, headLines, tailLines }) => {
+            if (headLines !== undefined)
+                return `${path} (first ${headLines} lines)`;
+            if (tailLines !== undefined)
+                return `${path} (last ${tailLines} lines)`;
+            return path;
+        },
         execute: async ({ path, headLines, tailLines }, ctx) => {
             if (headLines !== undefined && tailLines !== undefined) {
                 return ok({

package/dist/tools/workspace/workspace-search.js

@@ -47,6 +47,7 @@ export function createWorkspaceSearchTool(pool, embedding) {
                 .describe('Restrict results to one entry type: "input", "output", "summary", or "synthesis"'),
             limit: z.number().int().min(1).max(50).default(8).describe("Maximum number of results to return"),
         }),
+        describeCall: ({ query, type }) => (type === undefined ? query : `${query} (${type})`),
         execute: async ({ query, type, limit }, ctx) => {
             const [vector] = unwrapOrThrow(await embedding.embed([query], ctx.session));
             if (!vector)

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

@@ -28,6 +28,9 @@ export function createWriteFileTool(deps) {
             "variant (no I/O), and one escaping the analysis tree returns " +
             "`out_of_scope`.",
         inputSchema: WriteFileInputSchema,
+        // The path only. `content` is a whole file and must never ride a display
+        // channel, which the emit-site length cap enforces regardless.
+        describeCall: ({ path }) => path,
         execute: async ({ path, content }, ctx) => ok(await deps.mutator.writeFile({ path, content, toolName: "write_file", emit: ctx.emit })),
     });
 }

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

@@ -63,6 +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 { UsageRecorder } from "../billing/usage-recorder.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";
@@ -280,6 +281,12 @@ export interface ExecuteAnalysisDeps {
     readonly runCharge: RunCharge;
     /** Run-authorization seam — the terminal path revokes through `revoke`. */
     readonly runAuthorizer: RunAuthorizer;
+    /**
+     * LLM usage-accounting seam for the in-body synthesizer loop (and the
+     * literature reviewer it delegates to); omitted falls back to the no-op
+     * recorder.
+     */
+    readonly usageRecorder?: UsageRecorder;
     /**
      * Optional, fire-and-forget provenance observation of the run lifecycle.
      * Deliberately invoked directly in the workflow body (NOT wrapped in

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 } : {}),
     };
 }
 /**