@inflexa-ai/harness 0.14.1 → 0.15.0

package/dist/execution/report-runner.d.ts

@@ -38,6 +38,8 @@ import type { ChatProvider } from "../providers/types.js";
 import type { PreviewPublisher } from "../tools/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";
+import type { AgentRunUsage } from "../loop/metrics.js";
 export interface ReportRunnerDeps {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
@@ -50,6 +52,8 @@ export interface ReportRunnerDeps {
     /** Skills root; the report-builder gets read-only `report-html` skill tools. */
     readonly skillsDir: string;
     readonly chrome: ChromeConfig;
+    /** LLM usage-accounting seam for the report-builder loop; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
 }
 export interface ReportRunnerOptions {
     readonly resourceId: string;
@@ -75,6 +79,18 @@ export interface ReportRunnerOptions {
     readonly signal: AbortSignal;
     /** Event sink — forwarded to the agent loop. */
     readonly emit: EmitFn;
+    /**
+     * The calling turn's usage accumulator (`ctx.turnUsage`), so the
+     * report-builder loop's tokens land in the turn total its root reports.
+     */
+    readonly turnUsage?: AgentRunUsage;
+    /**
+     * The dispatching tool call's id (`ctx.invocationId`), which discriminates
+     * the builder loop's usage record keys from those of a sibling iteration
+     * dispatched in the same round — same frame, same call path, same
+     * loop-local step names.
+     */
+    readonly invocationId?: string;
 }
 export type ReportRunnerResult = {
     ok: true;

package/dist/execution/report-runner.js

@@ -148,6 +148,10 @@ export async function runReportIteration(deps, opts) {
                 emit: opts.emit,
                 runStep: passthroughStep,
                 resolved: () => outcome !== undefined,
+                usageRecorder: deps.usageRecorder,
+                // Fold the builder's calls into the turn total the root loop reports.
+                turnUsage: opts.turnUsage,
+                invocationId: opts.invocationId,
             }, {
                 tools: [buildReportTool, submitReportTool],
                 nudge: "You stopped without calling submit_report, so this report version " +

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

@@ -27,6 +27,7 @@ import { type RunSynthesis } from "../schemas/run-synthesis.js";
 import type { StepSummary } from "../schemas/step-summary.js";
 import type { ChatDataPart, EmitFn } from "../loop/types.js";
 import type { ChatProvider } from "../providers/types.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { RunSession } from "../auth/types.js";
 import { type Tool } from "../tools/define-tool.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
@@ -66,6 +67,8 @@ export interface GenerateRunSynthesisInput {
     readonly model: string;
     /** API keys for the bio/chem tools the embedded literature reviewer uses. */
     readonly bioKeys: BioToolKeys;
+    /** LLM usage-accounting seam for the synthesizer + reviewer loops; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
     /** Step summaries from the completed run. Non-empty. */
     readonly summaries: readonly StepSummary[];
     /** Plan analytical narrative for context. */

package/dist/execution/run-synthesis.js

@@ -349,6 +349,7 @@ export async function generateRunSynthesis(input) {
         provider: input.provider,
         model: input.model,
         bioKeys: input.bioKeys,
+        usageRecorder: input.usageRecorder,
     });
     const validateTool = buildValidateTool(innerCtx);
     const submitTool = buildSubmitTool(holder, innerCtx);
@@ -370,6 +371,7 @@ export async function generateRunSynthesis(input) {
         emit,
         runStep: passthroughStep,
         resolved: () => holder.outcome !== null,
+        usageRecorder: input.usageRecorder,
     };
     await runToTerminal(agent, [{ role: "user", content: prompt }], input.session, loopDeps, {
         tools: [submitTool, blockerTool],

package/dist/execution/step-summary.d.ts

@@ -30,9 +30,12 @@ import type { AgentChat } from "../providers/types.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import { type StepSummary } from "../schemas/step-summary.js";
 import type { Logger } from "../lib/logger.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
 export interface GenerateStepSummaryOptions {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
+    /** LLM usage-accounting seam for the summary loop; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
     readonly provider: AgentChat;
     readonly session: AgentSession;
     readonly modelId: string;

package/dist/execution/step-summary.js

@@ -88,6 +88,7 @@ export async function generateStepSummary(opts) {
             signal,
             emit: () => { },
             runStep: passthroughStep,
+            usageRecorder: opts.usageRecorder,
         });
     }
     catch (err) {

package/dist/execution/workflow-purger.d.ts

@@ -0,0 +1,38 @@
+/**
+ * WorkflowPurger — the durability-engine seam for reclaiming workflow rows.
+ *
+ * Most of what an analysis stores lives in the durability engine's own ledger —
+ * sandbox-agent step outputs, the run-event streams, workflow inputs — not in the
+ * harness's `cortex_*` tables, so removing an analysis has to reach that ledger.
+ * The engine is quarantined out of the state layer, the tools, and the loop
+ * (`RunLauncher` holds that line for the launch direction); this seam is the
+ * reclaim direction of the same quarantine. It speaks only in workflow ids, so a
+ * caller never names an engine type.
+ *
+ * Cancellation is a separate verb from deletion, and a caller uses it first:
+ * deleting the status row of a running workflow does not stop the executor
+ * running it, and that executor goes on writing rows behind the delete. A caller
+ * that cannot cancel must not proceed to a delete whose completeness it can no
+ * longer claim.
+ *
+ * Absence is a normal outcome throughout. A host may purge from a process that
+ * never launched the durable runtime, and the engine creates its schema at first
+ * launch — so a missing ledger means "nothing to purge", not a failure. Unknown
+ * ids are likewise ignored rather than rejected, which is what makes a re-run of
+ * an already-reclaimed purge succeed.
+ */
+import type { ResultAsync } from "neverthrow";
+import type { DbError } from "../lib/db-result.js";
+export interface WorkflowPurger {
+    /** Workflow ids in a given id namespace (e.g. `dataprofile:{analysisId}:`). Empty when the ledger has no schema yet. */
+    findByIdPrefix(prefix: string): ResultAsync<string[], DbError>;
+    /** Cancel the given workflows so no executor keeps writing behind a purge. Unknown ids are ignored. */
+    cancel(workflowIds: readonly string[]): ResultAsync<void, DbError>;
+    /**
+     * Delete the given workflows, and their descendants when `includeDescendants`.
+     * Resolves to how many workflows the delete targeted, counted immediately before
+     * it — a post-fact tally is not available, because the engine owns the delete and
+     * reports no count of its own.
+     */
+    deleteWorkflows(workflowIds: readonly string[], includeDescendants?: boolean): ResultAsync<number, DbError>;
+}

package/dist/execution/workflow-purger.js

@@ -0,0 +1,24 @@
+/**
+ * WorkflowPurger — the durability-engine seam for reclaiming workflow rows.
+ *
+ * Most of what an analysis stores lives in the durability engine's own ledger —
+ * sandbox-agent step outputs, the run-event streams, workflow inputs — not in the
+ * harness's `cortex_*` tables, so removing an analysis has to reach that ledger.
+ * The engine is quarantined out of the state layer, the tools, and the loop
+ * (`RunLauncher` holds that line for the launch direction); this seam is the
+ * reclaim direction of the same quarantine. It speaks only in workflow ids, so a
+ * caller never names an engine type.
+ *
+ * Cancellation is a separate verb from deletion, and a caller uses it first:
+ * deleting the status row of a running workflow does not stop the executor
+ * running it, and that executor goes on writing rows behind the delete. A caller
+ * that cannot cancel must not proceed to a delete whose completeness it can no
+ * longer claim.
+ *
+ * Absence is a normal outcome throughout. A host may purge from a process that
+ * never launched the durable runtime, and the engine creates its schema at first
+ * launch — so a missing ledger means "nothing to purge", not a failure. Unknown
+ * ids are likewise ignored rather than rejected, which is what makes a re-run of
+ * an already-reclaimed purge succeed.
+ */
+export {};

package/dist/index.d.ts

@@ -16,6 +16,8 @@ export { createNoopBillingResolver } from "./billing/noop-resolver.js";
 export type { ResolveBilling, ResolvableSession, BillingMap, BillingHeaders, BillingFetchResult } from "./billing/resolver.js";
 export { createNoopRunCharge } from "./billing/noop-run-charge.js";
 export type { RunCharge } from "./billing/run-charge.js";
+export { createNoopUsageRecorder } from "./billing/noop-usage-recorder.js";
+export type { UsageRecorder, LlmUsageRecord } from "./billing/usage-recorder.js";
 export { createNoopArtifactRegistry } from "./execution/noop-artifact-registry.js";
 export type { ArtifactRegistry, ArtifactRegistrationInput, ArtifactSyncInput, ExternalRegistrationResult } from "./execution/artifact-registry.js";
 export type { ArtifactManifestEntry } from "./schemas/artifact-manifest.js";
@@ -24,6 +26,9 @@ export { UnavailablePreviewPublisher } from "./tools/report/preview-publisher.js
 export type { PreviewPublisher, PreviewMintResult } from "./tools/report/preview-publisher.js";
 export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 export type { RunLauncher, LaunchOptions } from "./execution/run-launcher.js";
+export { createDbosWorkflowPurger } from "./execution/dbos-workflow-purger.js";
+export type { DbosWorkflowPurgerDeps } from "./execution/dbos-workflow-purger.js";
+export type { WorkflowPurger } from "./execution/workflow-purger.js";
 export { defineTool, isToolError } from "./tools/define-tool.js";
 export type { Tool, ToolDefinition, ToolContext, ToolError } from "./tools/define-tool.js";
 export { createAskGateway } from "./tools/approval/gateway.js";
@@ -39,7 +44,7 @@ export type { AgentSession, RequestSession, RunSession, Identity, Scope, Credent
 export { makeLocalAuth } from "./auth/local-auth-context.js";
 export { createAnthropicProvider } from "./providers/anthropic.js";
 export type { AnthropicProviderDeps } from "./providers/anthropic.js";
-export { createConfiguredAiSdkProvider } from "./providers/ai-sdk.js";
+export { createConfiguredAiSdkProvider, DEFAULT_MAX_OUTPUT_TOKENS } from "./providers/ai-sdk.js";
 export type { AiSdkProviderConfig, ConfiguredAiSdkProviderDeps } from "./providers/ai-sdk.js";
 export { createEmbeddingProvider } from "./providers/embedding.js";
 export type { EmbeddingProviderDeps } from "./providers/embedding.js";
@@ -56,10 +61,14 @@ export { createThreadHistory } from "./memory/thread-history.js";
 export type { ThreadHistory, StoredMessage, MessagePage, RetractOutcome } from "./memory/thread-history.js";
 export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
 export { contentToCortexMessages } from "./memory/content-to-cortex.js";
+export type { ContentToCortexOptions } from "./memory/content-to-cortex.js";
 export { createCardResolver } from "./memory/reconstruct-cards.js";
 export type { ToolCardResolver, StoredToolCallForCard } from "./memory/reconstruct-cards.js";
-export type { CortexChatEvent, TextDeltaEvent, ToolStartedEvent, ToolFinishedEvent, FinishEvent, ChatErrorEvent } from "./contracts/chat-events.js";
-export type { CortexChatPart, PresentationPart, PresentationContent, PlanPart, RunCardPart, FileReferencePart, FileReferenceEntry, RunStartedPart, DagStatePart, DagStepState, StepStatus, StepActivityPart, StepPhase, StepFileTreePart, FileTreeEntry, StepOutputPart, StepOutputFile, StepSummaryPart, StepBlockedPart, RunSynthesisPart, SynthesizedFinding, BiologicalTheme, SynthesisProgressPart, SynthesisPhase, RunCompletedPart, RunCompletedFinding, RunFailedPart, PreviewPart, DataPreviewFailedPart, } from "./contracts/chat-parts.js";
+export { createDetailResolver } from "./tools/detail-resolver.js";
+export type { ToolDetailResolver } from "./tools/detail-resolver.js";
+export type { CortexChatEvent, TextDeltaEvent, ToolStartedEvent, ToolFinishedEvent, ToolOutcome, ToolCallDetail, FinishEvent, ChatErrorEvent, } from "./contracts/chat-events.js";
+export type { TokenUsageRollup } from "./contracts/usage.js";
+export type { CortexChatPart, PresentationPart, PresentationContent, PlanPart, RunCardPart, FileReferencePart, FileReferenceEntry, RunStartedPart, DagStatePart, DagStepState, StepStatus, StepActivityPart, StepPhase, StepFileTreePart, FileTreeEntry, StepOutputPart, StepOutputFile, StepSummaryPart, StepUsagePart, StepBlockedPart, RunSynthesisPart, SynthesizedFinding, BiologicalTheme, SynthesisProgressPart, SynthesisPhase, RunCompletedPart, RunCompletedFinding, RunFailedPart, PreviewPart, DataPreviewFailedPart, } from "./contracts/chat-parts.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";
 export type { CortexChatPartType, PartDescriptor, PartEmitter, PartConsumer } from "./contracts/part-registry.js";
 export { launchDbos, shutdownDbos, sweepEphemeralWorkflows } from "./runtime/dbos.js";
@@ -71,10 +80,23 @@ export type { PoolConfig } from "./lib/storage.js";
 export type { Pool } from "pg";
 export { registerDataProfileWorkflow, triggerDataProfile, runDataProfile } from "./tasks/data-profile.js";
 export type { DataProfileDeps, DataProfileWorkflowInput, DataProfileTriggerDeps, DataProfileTriggerParams, DataProfileTriggerResult, } from "./tasks/data-profile.js";
+/**
+ * The synthetic run id the data-profile workflow stamps onto its own frame — the profile has no run
+ * row, so this literal is the only thing that identifies its work as the profile's.
+ *
+ * An embedder needs it to READ BACK what the harness recorded: usage accounting carries one run-id
+ * column, so a host reporting "consumption by run" sees profile calls sitting among real runs and can
+ * only separate them by comparing against this value. Exported rather than documented so that
+ * comparison is a compile-time coupling — a host holding a copy of the string would keep compiling
+ * through a rename here and quietly resume reporting the profile as an unnamed run.
+ */
+export { DATA_PROFILE_RUN_LITERAL } from "./contracts/data-profile.js";
 export { initCortexState } from "./state/init.js";
 export { upsertAnalysis } from "./state/analyses.js";
 export { clearDataProfile, loadDataProfileStatus, tryRetryDataProfile, reconcileOrphanedDataProfile } from "./state/data-profile.js";
 export type { DataProfileInputFile, DataProfileResult, DataProfileStatus } from "./state/data-profile.js";
+export { createAnalysisPurge } from "./state/purge-analysis.js";
+export type { AnalysisPurge, AnalysisPurgeDeps, AnalysisPurgeOutcome } from "./state/purge-analysis.js";
 export type { StagedInput } from "./execution/staged-input.js";
 export type { ResolveWorkspaceRoot } from "./workspace/paths.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";

package/dist/index.js

@@ -17,12 +17,20 @@ export { createLocalRunAuthorizer } from "./auth/local-run-authorizer.js";
 export { createNoopBillingResolver } from "./billing/noop-resolver.js";
 // Seam: run-level billing bracket.
 export { createNoopRunCharge } from "./billing/noop-run-charge.js";
+// Seam: per-call LLM usage accounting. `record` is fire-and-forget — the loop
+// neither awaits nor guards it, so a realization must not throw and must not
+// block. Wired as the optional `usageRecorder` of `assembleCoreRuntime`;
+// unwired, every call is dropped by `createNoopUsageRecorder`.
+export { createNoopUsageRecorder } from "./billing/noop-usage-recorder.js";
 // Seam: artifact registration.
 export { createNoopArtifactRegistry } from "./execution/noop-artifact-registry.js";
 // Seam: report preview publishing.
 export { UnavailablePreviewPublisher } from "./tools/report/preview-publisher.js";
 // Run launching.
 export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
+// Seam: workflow-ledger reclamation — cancels and deletes an analysis's rows in
+// the durability engine's own ledger, so no caller names an engine type.
+export { createDbosWorkflowPurger } from "./execution/dbos-workflow-purger.js";
 // Tool primitive.
 export { defineTool, isToolError } from "./tools/define-tool.js";
 // Seam: tool approval (`ctx.ask`). `createAskGateway` realizes the `Ask` seam
@@ -48,7 +56,7 @@ export { createAnthropicProvider } from "./providers/anthropic.js";
 // union discriminated over the `anthropic` and `openai-compatible` kinds — with
 // `ConfiguredAiSdkProviderDeps` as its argument shape. `createAnthropicProvider`
 // above is a convenience over this union's `anthropic` arm.
-export { createConfiguredAiSdkProvider } from "./providers/ai-sdk.js";
+export { createConfiguredAiSdkProvider, DEFAULT_MAX_OUTPUT_TOKENS } from "./providers/ai-sdk.js";
 export { createEmbeddingProvider } from "./providers/embedding.js";
 // Prompt caching. `PromptCachePolicy` is the harness's vendor-neutral cache
 // directive; a composition root sets it per run via `RunAgentOptions.promptCache`
@@ -93,6 +101,11 @@ export { createThreadHistory } from "./memory/thread-history.js";
 export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
 export { contentToCortexMessages } from "./memory/content-to-cortex.js";
 export { createCardResolver } from "./memory/reconstruct-cards.js";
+// The call-detail resolver, the reload counterpart of the `describeCall` hook a
+// tool declares. Built over a tool list the HOST supplies — its own composed
+// roster, `HarnessRuntime.conversationAgent.tools` — because tools contributed
+// through the host-tools seam are invisible to any map the harness holds.
+export { createDetailResolver } from "./tools/detail-resolver.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./contracts/part-registry.js";
 // Embedder runtime surface — what a same-process host needs to run durable
 // workflows itself: the DBOS lifecycle, per-workflow registration + triggers,
@@ -121,6 +134,17 @@ export { createPool } from "./lib/storage.js";
 // via `tryRetryDataProfile` and then started with `runDataProfile` (the managed retry
 // route's shape — embedders mirror it).
 export { registerDataProfileWorkflow, triggerDataProfile, runDataProfile } from "./tasks/data-profile.js";
+/**
+ * The synthetic run id the data-profile workflow stamps onto its own frame — the profile has no run
+ * row, so this literal is the only thing that identifies its work as the profile's.
+ *
+ * An embedder needs it to READ BACK what the harness recorded: usage accounting carries one run-id
+ * column, so a host reporting "consumption by run" sees profile calls sitting among real runs and can
+ * only separate them by comparing against this value. Exported rather than documented so that
+ * comparison is a compile-time coupling — a host holding a copy of the string would keep compiling
+ * through a rename here and quietly resume reporting the profile as an unnamed run.
+ */
+export { DATA_PROFILE_RUN_LITERAL } from "./contracts/data-profile.js";
 // Ledger surface the embedder needs around a trigger: schema init at boot,
 // the analysis-state seed (the trigger's CAS transitions the row this creates
 // — without it every trigger reports "failed"), and run-state observation.
@@ -133,6 +157,9 @@ export { upsertAnalysis } from "./state/analyses.js";
 // analysis's input set empties (deferring on a running workflow), so the UI
 // stops advertising a profile that describes files the analysis no longer has.
 export { clearDataProfile, loadDataProfileStatus, tryRetryDataProfile, reconcileOrphanedDataProfile } from "./state/data-profile.js";
+// Analysis reclamation — `purgeAnalysis` reclaims an analysis's whole Postgres
+// footprint from its id alone; workspace files stay the embedder's to dispose of.
+export { createAnalysisPurge } from "./state/purge-analysis.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";
 export { MachineBudgetSchema, ResourceLimitsSchema, ResourcePolicySchema, ResourceSpecSchema, parseResourcePolicy } from "./config/resource-limits.js";
 export { createWorkspaceFilesystem } from "./workspace/filesystem.js";

package/dist/lib/metrics.js

@@ -14,5 +14,6 @@ export const artifactReconcileDropped = meter.createCounter("cortex.artifact.rec
 export const lineageInputDropped = meter.createCounter("cortex.artifact.reconcile.input_dropped", {
     description: "Tracked input reads dropped from lineage at reconcile because they are " +
         "not content-attestable files of the analysis (directory reads, " +
-        "out-of-tree resolutions). Tagged by agent_id, step_id, reason.",
+        "out-of-tree resolutions, paths absent at reconcile). Tagged by " +
+        "agent_id, step_id, reason.",
 });

package/dist/loop/metrics.d.ts

@@ -28,20 +28,38 @@
  * `MeterProvider` is registered globally at runtime (production: the OTLP
  * exporter from `harness/lib/otel.ts`; tests: an in-memory reader).
  */
+import { type TokenUsageRollup } from "../contracts/usage.js";
 import type { ChatUsage } from "../providers/types.js";
 /**
  * Token usage summed over every LLM call one `runAgent` made. Each field stays
  * `undefined` until some call actually reports it, so "the provider told us
  * nothing" never masquerades as a measured zero.
+ *
+ * The fold is wider than the instruments: `reasoningTokens` is carried for the
+ * usage records and the finish rollups, and deliberately has no OTel counter —
+ * whether a provider counts reasoning inside `outputTokens` varies, so a
+ * cross-agent counter would sum figures that do not mean the same thing.
  */
 export interface AgentRunUsage {
     inputTokens?: number;
     outputTokens?: number;
     cacheCreationInputTokens?: number;
     cacheReadInputTokens?: number;
+    reasoningTokens?: number;
 }
 /** Fold one call's reported usage into a run's running total. */
 export declare function addChatUsage(total: AgentRunUsage, usage: ChatUsage | undefined): void;
+/**
+ * Whether anything was ever folded in. An accumulator no call reported into
+ * stays empty, and the surfaces that carry a rollup must then carry none at
+ * all rather than an all-zero figure.
+ *
+ * It also accepts the wire-shaped `TokenUsageRollup`, so a surface that RECEIVES
+ * a rollup (thread history storing a turn's) decides "reported nothing" with the
+ * same predicate the loop used to decide whether to emit one. Restating the rule
+ * at either end is how the two would come to disagree.
+ */
+export declare function hasReportedUsage(usage: AgentRunUsage | ChatUsage | TokenUsageRollup | undefined): boolean;
 /** Record one completed `runAgent` invocation. */
 export declare function recordAgentRun(run: {
     readonly agentId: string;

package/dist/loop/metrics.js

@@ -29,6 +29,7 @@
  * exporter from `harness/lib/otel.ts`; tests: an in-memory reader).
  */
 import { metrics } from "@opentelemetry/api";
+import { TOKEN_USAGE_FIELDS } from "../contracts/usage.js";
 let instruments;
 function getInstruments() {
     if (instruments === undefined) {
@@ -61,16 +62,32 @@ function getInstruments() {
     }
     return instruments;
 }
+const _assertRunUsageFields = true;
 /** Fold one call's reported usage into a run's running total. */
 export function addChatUsage(total, usage) {
     if (usage === undefined)
         return;
-    for (const key of ["inputTokens", "outputTokens", "cacheCreationInputTokens", "cacheReadInputTokens"]) {
+    for (const key of TOKEN_USAGE_FIELDS) {
         const value = usage[key];
         if (value !== undefined)
             total[key] = (total[key] ?? 0) + value;
     }
 }
+/**
+ * Whether anything was ever folded in. An accumulator no call reported into
+ * stays empty, and the surfaces that carry a rollup must then carry none at
+ * all rather than an all-zero figure.
+ *
+ * It also accepts the wire-shaped `TokenUsageRollup`, so a surface that RECEIVES
+ * a rollup (thread history storing a turn's) decides "reported nothing" with the
+ * same predicate the loop used to decide whether to emit one. Restating the rule
+ * at either end is how the two would come to disagree.
+ */
+export function hasReportedUsage(usage) {
+    if (usage === undefined)
+        return false;
+    return Object.values(usage).some((value) => value !== undefined);
+}
 /** Record one completed `runAgent` invocation. */
 export function recordAgentRun(run) {
     const { iterations, capHits, inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens } = getInstruments();

package/dist/loop/run-agent.d.ts

@@ -1,13 +1,26 @@
 import { type FinishReason } from "ai";
 import type { AgentSession } from "../auth/types.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { Logger } from "../lib/logger.js";
 import type { AgentChat, ChatRequest, PromptCachePolicy } from "../providers/types.js";
 import { type AskApproval, type AskRequest } from "../tools/approval/contract.js";
+import { type AgentRunUsage } from "./metrics.js";
 import type { AgentDefinition, EmitFn, LoopMessage, RunStep } from "./types.js";
 export interface AgentFinish {
     readonly reason: FinishReason | "aborted" | "max_iterations" | "denied";
     readonly cappedOut: boolean;
     readonly truncationRecoveries: number;
+    /**
+     * What this loop's own LLM calls reported, the forced wrap-up included.
+     * Absent when no call reported anything — never an all-zero figure.
+     */
+    readonly usage?: AgentRunUsage;
+    /**
+     * The whole turn's total, every descendant loop included. Present only on
+     * the loop that created the turn accumulator — the run whose options
+     * carried none, which is by construction the turn's root.
+     */
+    readonly turnUsage?: AgentRunUsage;
 }
 export interface RunAgentResult {
     readonly messages: LoopMessage[];
@@ -67,6 +80,28 @@ export interface RunAgentOptions {
      * progress is emitted and then dropped. This is where it survives.
      */
     readonly logger?: Logger;
+    /**
+     * Per-call LLM usage-accounting seam. Omitted falls back to the no-op
+     * recorder. Delivery is fire-and-forget by contract — the loop neither
+     * awaits `record` nor guards it, so a realization must not throw or block.
+     */
+    readonly usageRecorder?: UsageRecorder;
+    /**
+     * The turn's usage accumulator, supplied by whatever ran this loop as part
+     * of a larger turn (a sub-agent-running tool passes `ctx.turnUsage`). A run
+     * that receives none creates its own and is therefore the turn's root: it
+     * alone reports `turnUsage` on its finish.
+     */
+    readonly turnUsage?: AgentRunUsage;
+    /**
+     * The id of the tool call this loop runs inside, supplied by a
+     * sub-agent-running tool from its `ctx.invocationId`. It is what separates
+     * two dispatches of the *same* sub-agent in one round — they share the run
+     * frame, the call path, and every loop-local step name — in the usage
+     * record key. Absent for a loop that is not nested inside a tool dispatch
+     * (a chat turn's root, a workflow step body, a background task).
+     */
+    readonly invocationId?: string;
 }
 export declare function runAgent(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: RunAgentOptions): Promise<RunAgentResult>;
 export declare function finalText(messages: readonly LoopMessage[]): string;