@inflexa-ai/harness 0.14.1 → 0.15.0

package/README.md

@@ -34,6 +34,7 @@ import {
     createLocalRunAuthorizer,       // RunAuthorizer    seam (local default)
     createNoopBillingResolver,      // ResolveBilling   seam
     createNoopRunCharge,            // RunCharge        seam
+    createNoopUsageRecorder,        // UsageRecorder    seam
     createNoopArtifactRegistry,     // ArtifactRegistry seam
     UnavailablePreviewPublisher,    // PreviewPublisher seam
     createDbosRunLauncher,          // shared RunLauncher
@@ -46,7 +47,7 @@ import {
 } from "@inflexa-ai/harness";
 ```
 
-`assembleCoreRuntime` is the single composition point: it registers the durable workflows and builds the conversation agent over them. The harness declares **five capability seams** an embedder wires — `RunAuthorizer`, `ResolveBilling`, `ArtifactRegistry`, `RunCharge`, `PreviewPublisher` — plus the **shared `RunLauncher`** (one host-neutral realization, `createDbosRunLauncher`). Local, dependency-free realizations of all five ship from the barrel; an embedder constructs them (or its own) and passes them in. The harness only ever sees the interface.
+`assembleCoreRuntime` is the single composition point: it registers the durable workflows and builds the conversation agent over them. The harness declares **six capability seams** an embedder wires — `RunAuthorizer`, `ResolveBilling`, `ArtifactRegistry`, `RunCharge`, `UsageRecorder`, `PreviewPublisher` — plus the **shared `RunLauncher`** (one host-neutral realization, `createDbosRunLauncher`). Local, dependency-free realizations of all six ship from the barrel; an embedder constructs them (or its own) and passes them in. The harness only ever sees the interface.
 
 ## Logging
 

package/dist/agents/conversation-agent.d.ts

@@ -40,6 +40,7 @@ import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { RunLauncher } from "../execution/run-launcher.js";
 import { type SubmitReportDeps } from "../tools/iterate-report.js";
 import type { Logger } from "../lib/logger.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
 /** Canonical agent id — the single source of truth. */
 export declare const CONVERSATION_AGENT_ID: "conversation-agent";
 /**
@@ -51,6 +52,12 @@ export declare const CONVERSATION_AGENT_ID: "conversation-agent";
 export interface ConversationAgentDeps extends EnvironmentStorePaths {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
+    /**
+     * LLM usage-accounting seam, handed to every loop-driving tool this agent
+     * owns so a sub-agent's calls land in the same ledger as the turn's.
+     * Omitted falls back to the no-op recorder.
+     */
+    readonly usageRecorder?: UsageRecorder;
     /** The LLM seam every loop-driving tool runs its sub-agent on. */
     readonly provider: ChatProvider;
     /** Postgres pool — plan persistence, run inspection, workspace index, working memory. */

package/dist/agents/conversation-agent.js

@@ -46,7 +46,7 @@ export const CONVERSATION_AGENT_ID = "conversation-agent";
 const CONVERSATION_MAX_ITERATIONS = 50;
 /** Build the conversation `AgentDefinition` with every tool fully dep-bound. */
 export function createConversationAgent(deps) {
-    const { provider, pool, embedding, workspaceFs, model, utilityProvider, utilityModel, executeAnalysisWorkflow, resolveWorkspaceRoot, runAuthorizer, runLauncher, createPreviewPublisher, bioKeys, templatesDir, skillsDir, chrome, resourcePolicy, hostTools, refStorePath, packagesFile, } = deps;
+    const { provider, pool, embedding, workspaceFs, model, utilityProvider, utilityModel, executeAnalysisWorkflow, resolveWorkspaceRoot, runAuthorizer, runLauncher, createPreviewPublisher, bioKeys, templatesDir, skillsDir, chrome, resourcePolicy, hostTools, refStorePath, packagesFile, usageRecorder, } = deps;
     const workingMemory = createWorkingMemory(pool);
     const ncbi = createNcbiTools(bioKeys);
     const chemDb = createChemDbTools(bioKeys, { ...(deps.logger ? { logger: deps.logger } : {}) });
@@ -96,6 +96,7 @@ export function createConversationAgent(deps) {
             conversation: { provider, model },
             pool,
             resourcePolicy,
+            usageRecorder,
             ...(refStorePath ? { refStorePath } : {}),
             ...(packagesFile ? { packagesFile } : {}),
             ...(deps.logger ? { logger: deps.logger } : {}),
@@ -124,15 +125,16 @@ export function createConversationAgent(deps) {
             skillsDir,
             chrome,
             createPreviewPublisher,
+            usageRecorder,
         }),
         // Display.
         showUserTool,
         createShowPlanTool(pool),
         showFileTool,
         // Batch literature/biology research (sub-agent as a loop-driving tool).
-        createLiteratureReviewerTool({ provider, model, bioKeys }),
+        createLiteratureReviewerTool({ provider, model, bioKeys, usageRecorder }),
         // Cross-domain analogy generation (sub-agent as a loop-driving tool).
-        createGenerateAnalogyReportTool({ provider, model, bioKeys }),
+        createGenerateAnalogyReportTool({ provider, model, bioKeys, usageRecorder }),
         // Workspace semantic search + raw read/grep over the read seam.
         createWorkspaceSearchTool(pool, embedding),
         createReadFileTool(workspaceFs),

package/dist/app/synthesize-run.d.ts

@@ -24,6 +24,7 @@ import type { RunFinding } from "../workflows/execute-analysis.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import type { SynthesisStatus } from "../state/index.js";
 import type { Logger } from "../lib/logger.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
 export interface SynthesizeRunDeps {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
@@ -37,6 +38,8 @@ export interface SynthesizeRunDeps {
     readonly synthesisModel: string;
     /** API keys for the bio/chem tools the embedded literature reviewer uses. */
     readonly bioKeys: BioToolKeys;
+    /** LLM usage-accounting seam for the synthesizer loop; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
 }
 /** Optional fields for a progress update, mirroring the wire part. */
 export interface SynthesisProgressExtra {

package/dist/app/synthesize-run.js

@@ -22,7 +22,7 @@ import { loadPlan, queryRun } from "../state/index.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 export async function synthesizeRun(deps, params) {
-    const { pool, provider, embedding, resolveWorkspaceRoot, synthesisModel, bioKeys } = deps;
+    const { pool, provider, embedding, resolveWorkspaceRoot, synthesisModel, bioKeys, usageRecorder } = deps;
     const { analysisId, runId, completedSteps, session, emit, onProgress } = params;
     await onProgress("starting", "Beginning literature-grounded synthesis");
     try {
@@ -47,6 +47,7 @@ export async function synthesizeRun(deps, params) {
             session: synthesizerSession,
             model: synthesisModel,
             bioKeys,
+            usageRecorder,
             summaries,
             planNarrative,
             runId,

package/dist/billing/noop-usage-recorder.d.ts

@@ -0,0 +1,7 @@
+import type { UsageRecorder } from "./usage-recorder.js";
+/**
+ * Local/OSS usage recorder: drops every record. No ledger, no I/O — the
+ * default an embedder that wires nothing gets. Runs behave exactly as they did
+ * before the seam existed.
+ */
+export declare function createNoopUsageRecorder(): UsageRecorder;

package/dist/billing/noop-usage-recorder.js

@@ -0,0 +1,10 @@
+/**
+ * Local/OSS usage recorder: drops every record. No ledger, no I/O — the
+ * default an embedder that wires nothing gets. Runs behave exactly as they did
+ * before the seam existed.
+ */
+export function createNoopUsageRecorder() {
+    return {
+        record: () => { },
+    };
+}

package/dist/billing/usage-recorder.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `UsageRecorder` — the per-call LLM usage-accounting seam.
+ *
+ * Sibling of `ResolveBilling` and `RunCharge`, and complementary to both:
+ * `ResolveBilling` stamps attribution onto a wire call, `RunCharge` brackets a
+ * run for managed billing, and `UsageRecorder` streams the fine-grained token
+ * telemetry every completed LLM call produces. The harness names no storage or
+ * display technology — it emits records; the embedder decides where they land.
+ *
+ * The loop is the single delivery site (it sees every reply in both execution
+ * modes and already holds the session), so a realization is wired once at the
+ * composition root and reaches every `runAgent` invocation through the deps
+ * bags. OSS default: `createNoopUsageRecorder` (`./noop-usage-recorder.ts`).
+ */
+import type { Scope } from "../auth/types.js";
+import type { ChatUsage } from "../providers/types.js";
+/** One completed LLM call's token usage, with the attribution held at the call site. */
+export interface LlmUsageRecord {
+    /**
+     * Idempotency key. Stable across every replay of the same call: under a
+     * `RunFrame` it composes the `runId`, the frame's `stepId` when it carries
+     * one, the session's provenance call path, the dispatching tool call's id
+     * when the loop runs nested inside one, and the loop's deterministic step
+     * name; outside a `RunFrame` (the chat path, where no replay exists) it is
+     * freshly minted. Every component past the frame is load-bearing, because
+     * a step name is unique only within one loop invocation and loops routinely
+     * share a frame: the `stepId` keeps sibling step workflows of one run
+     * apart, the call path keeps distinct agent chains under one frame apart,
+     * and the invocation id keeps parallel dispatches of one sub-agent apart.
+     * The harness guarantees key stability, not at-most-once delivery —
+     * consumers MUST upsert on this key, or a replayed workflow body will
+     * double-count the call.
+     */
+    readonly recordKey: string;
+    /** Agent that made the call — a sub-agent records under its own id. */
+    readonly agentId: string;
+    /** Provenance path from the root agent down to `agentId`. */
+    readonly callPath: readonly string[];
+    /** Scope ids as attribution: `analysisId` or `targetAssessmentId`. */
+    readonly scope: Scope;
+    /** Present only for calls made inside a run (the session carries a `RunFrame`). */
+    readonly runId?: string;
+    /** Present only for calls made inside a run step. */
+    readonly stepId?: string;
+    /** Model the harness asked for; absent when the provider does not report it. */
+    readonly requestedModelId?: string;
+    /** Model that actually answered; absent when the endpoint does not report it. */
+    readonly servedModelId?: string;
+    /** What the provider reported. Unreported figures stay absent, never zeroed. */
+    readonly usage: ChatUsage;
+}
+/**
+ * Records one `LlmUsageRecord` per completed LLM call.
+ *
+ * Fire-and-forget: the loop neither awaits `record` nor guards it, so a
+ * realization MUST NOT throw and MUST NOT block — buffer and flush
+ * internally, and own your error handling (diagnostics belong on the injected
+ * `Logger`). A recorder that violates the contract fails or stalls the run it
+ * was only meant to observe.
+ */
+export interface UsageRecorder {
+    record(record: LlmUsageRecord): void;
+}

package/dist/billing/usage-recorder.js

@@ -0,0 +1,15 @@
+/**
+ * `UsageRecorder` — the per-call LLM usage-accounting seam.
+ *
+ * Sibling of `ResolveBilling` and `RunCharge`, and complementary to both:
+ * `ResolveBilling` stamps attribution onto a wire call, `RunCharge` brackets a
+ * run for managed billing, and `UsageRecorder` streams the fine-grained token
+ * telemetry every completed LLM call produces. The harness names no storage or
+ * display technology — it emits records; the embedder decides where they land.
+ *
+ * The loop is the single delivery site (it sees every reply in both execution
+ * modes and already holds the session), so a realization is wired once at the
+ * composition root and reaches every `runAgent` invocation through the deps
+ * bags. OSS default: `createNoopUsageRecorder` (`./noop-usage-recorder.ts`).
+ */
+export {};

package/dist/contracts/chat-events.d.ts

@@ -10,6 +10,7 @@
  * Every event carries `source` — the agent call chain at the point of
  * emission, derived from the harness `Session.callPath`.
  */
+import type { TokenUsageRollup } from "./usage.js";
 /**
  * Provenance stamped on every chat-stream event: the emitting agent and the
  * call chain that reached it (e.g. `["conversation-agent"]`, or
@@ -25,6 +26,28 @@ export interface TextDeltaEvent {
     text: string;
     source: EventSource;
 }
+/**
+ * How a tool call ended.
+ *
+ * Three states, not a boolean: a user who rejects an approval made a decision,
+ * and reporting that decision as a fault misdescribes it. The loop already
+ * separates the two in its control flow — a denial ends the turn, an error is
+ * one the model reads and retries around — so the observation channel carries
+ * the same distinction. One field rather than two booleans, because two would
+ * admit the impossible "not an error, but denied".
+ */
+export type ToolOutcome = "ok" | "error" | "denied";
+/**
+ * One line naming what a tool call is doing, produced by the tool's own
+ * `describeCall` hook and normalized at the emit site.
+ *
+ * Opaque display text. A consumer renders it and derives nothing from it — no
+ * splitting, no keying on separators. The contract is harness-owned so it can
+ * widen when a renderer needs structure; parsing it would recreate the schema
+ * coupling the hook exists to remove. Absent when the tool declares no hook, or
+ * when the detail could not be produced.
+ */
+export type ToolCallDetail = string;
 /** A tool call has been dispatched. */
 export interface ToolStartedEvent {
     type: "tool-started";
@@ -32,6 +55,8 @@ export interface ToolStartedEvent {
     toolUseId: string;
     /** The tool name. */
     name: string;
+    /** See {@link ToolCallDetail}. Absent — never empty — when none was produced. */
+    detail?: ToolCallDetail;
     source: EventSource;
 }
 /** A tool call has resolved. */
@@ -39,14 +64,30 @@ export interface ToolFinishedEvent {
     type: "tool-finished";
     toolUseId: string;
     name: string;
-    /** True when the tool produced an `is_error` result. */
-    isError: boolean;
+    /** How the call ended. See {@link ToolOutcome}. */
+    outcome: ToolOutcome;
+    /** The same detail the matching `tool-started` carried. */
+    detail?: ToolCallDetail;
     source: EventSource;
 }
-/** The agent loop produced its terminal reply — the turn is complete. */
+/**
+ * The agent loop produced its terminal reply — the turn is complete.
+ *
+ * Both rollups are absent whenever no covered call reported usage; neither is
+ * ever an all-zero figure. A turn that dies instead of finishing emits
+ * `ChatErrorEvent` and therefore no rollup at all — the usage-record ledger,
+ * not this event, is the complete account of what a turn spent.
+ */
 export interface FinishEvent {
     type: "finish";
     source: EventSource;
+    /** What this loop's own LLM calls used, the forced wrap-up included. */
+    usage?: TokenUsageRollup;
+    /**
+     * The whole turn's total — this loop's calls plus every descendant loop's
+     * (sub-agent tools included). Present only on the turn's root loop.
+     */
+    turnUsage?: TokenUsageRollup;
 }
 /** The turn failed. `reason` is a machine-readable code when one applies. */
 export interface ChatErrorEvent {

package/dist/contracts/chat-parts.d.ts

@@ -9,8 +9,9 @@
  *   Run lifecycle:   run-started, dag-state, run-completed, run-failed, run-synthesis,
  *                    synthesis-progress
  *   Per-step live:   step-activity, step-file-tree
- *   Per-step final:  step-output, step-summary
+ *   Per-step final:  step-output, step-summary, step-usage
  */
+import type { TokenUsageRollup } from "./usage.js";
 export interface PlanStep {
     id: string;
     name: string;
@@ -201,6 +202,36 @@ export interface StepSummaryPart {
     /** Free-form markdown body. Render with a markdown renderer. */
     markdown: string;
 }
+/**
+ * What one analysis-run step's agent loop reported spending, emitted when that
+ * loop completes.
+ *
+ * `usage` is the step's rollup and is required: a part exists to carry one, so a
+ * step whose loop reported nothing emits no part at all rather than one with an
+ * absent or zeroed figure. Per-call granularity is the usage-record ledger's
+ * job, never this part's.
+ *
+ * Scoped to analysis runs. Workflows without step parts (target assessment,
+ * ephemeral runs, data profiling) reach the ledger through the recorder seam and
+ * carry no usage part.
+ */
+export interface StepUsagePart {
+    type: "data-step-usage";
+    /** Stable ID for reconciliation — unique per step within a run. */
+    id: string;
+    runId: string;
+    stepId: string;
+    agentId: string;
+    /**
+     * The model id the step's agent was configured to run under — the identity
+     * the rollup is attributable to. Whether the endpoint actually served that
+     * model is a per-call question the usage-record ledger answers; a rollup
+     * spans calls and cannot.
+     */
+    modelId: string;
+    /** Summed token usage across this step loop's LLM calls. */
+    usage: TokenUsageRollup;
+}
 /**
  * Emitted when a step agent declares it cannot fulfil its step via
  * `report_blocker` (see the harness-sandbox-agents spec). A blocked step has no deliverables; the
@@ -233,6 +264,11 @@ export interface RunCompletedPart {
      * to explain why (e.g., synthesis failed but step summaries are available).
      */
     note?: string;
+    /**
+     * The run's aggregate token usage — the sum of what its steps reported.
+     * Absent when no step reported any, never an all-zero figure.
+     */
+    usage?: TokenUsageRollup;
 }
 export interface SynthesizedFinding {
     stepId: string;
@@ -323,4 +359,4 @@ export interface DataPreviewFailedPart {
     /** Optional taxonomy of failure kinds. */
     errorKind?: "render" | "submit" | "build" | "timeout" | "internal";
 }
-export type CortexChatPart = PresentationPart | PlanPart | RunCardPart | FileReferencePart | AskPart | RunStartedPart | DagStatePart | StepActivityPart | StepFileTreePart | StepOutputPart | StepSummaryPart | StepBlockedPart | RunSynthesisPart | SynthesisProgressPart | RunCompletedPart | RunFailedPart | PreviewPart | DataPreviewFailedPart;
+export type CortexChatPart = PresentationPart | PlanPart | RunCardPart | FileReferencePart | AskPart | RunStartedPart | DagStatePart | StepActivityPart | StepFileTreePart | StepOutputPart | StepSummaryPart | StepUsagePart | StepBlockedPart | RunSynthesisPart | SynthesisProgressPart | RunCompletedPart | RunFailedPart | PreviewPart | DataPreviewFailedPart;

package/dist/contracts/chat-parts.js

@@ -9,6 +9,6 @@
  *   Run lifecycle:   run-started, dag-state, run-completed, run-failed, run-synthesis,
  *                    synthesis-progress
  *   Per-step live:   step-activity, step-file-tree
- *   Per-step final:  step-output, step-summary
+ *   Per-step final:  step-output, step-summary, step-usage
  */
 export {};

package/dist/contracts/data-profile.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The data profile's durable-frame identity, on the Cortex wire vocabulary.
+ *
+ * This lives in `contracts/` — not beside the workflow that stamps it — for the same reason every
+ * other name here does: it is a value a CONSUMER reads back, and `contracts/` is the one part of the
+ * package a consumer can import without inheriting the harness's own dependencies. The workflow
+ * module that uses it pulls in DBOS, the sandbox client, and the profiler agent graph; a host that
+ * imported the literal from there would pay ~120ms of module loading to obtain a string, on every
+ * command that touches its ledger.
+ *
+ * That is not a packaging detail to be worked around at the call site. A constant whose whole purpose
+ * is to be compared against stored data belongs where the data's vocabulary is declared.
+ */
+/**
+ * The `runId` the harness stamps on every LLM call the data profile makes.
+ *
+ * A literal, not a minted id: the profile has no run row in any ledger, so this is the only thing
+ * identifying its work as the profile's. A consumer needs it to READ BACK what the harness recorded —
+ * usage accounting carries one run-id column, so a host reporting consumption "by run" finds profile
+ * calls sitting among real runs and can separate them only by comparing against this value.
+ *
+ * Exported rather than merely documented so that comparison is a compile-time coupling. A host
+ * holding its own copy of the string would keep compiling through a rename here, and quietly resume
+ * reporting the profile as an unnamed run — a failure with no red test anywhere.
+ */
+export declare const DATA_PROFILE_RUN_LITERAL: "data-profile";

package/dist/contracts/data-profile.js

@@ -0,0 +1,26 @@
+/**
+ * The data profile's durable-frame identity, on the Cortex wire vocabulary.
+ *
+ * This lives in `contracts/` — not beside the workflow that stamps it — for the same reason every
+ * other name here does: it is a value a CONSUMER reads back, and `contracts/` is the one part of the
+ * package a consumer can import without inheriting the harness's own dependencies. The workflow
+ * module that uses it pulls in DBOS, the sandbox client, and the profiler agent graph; a host that
+ * imported the literal from there would pay ~120ms of module loading to obtain a string, on every
+ * command that touches its ledger.
+ *
+ * That is not a packaging detail to be worked around at the call site. A constant whose whole purpose
+ * is to be compared against stored data belongs where the data's vocabulary is declared.
+ */
+/**
+ * The `runId` the harness stamps on every LLM call the data profile makes.
+ *
+ * A literal, not a minted id: the profile has no run row in any ledger, so this is the only thing
+ * identifying its work as the profile's. A consumer needs it to READ BACK what the harness recorded —
+ * usage accounting carries one run-id column, so a host reporting consumption "by run" finds profile
+ * calls sitting among real runs and can separate them only by comparing against this value.
+ *
+ * Exported rather than merely documented so that comparison is a compile-time coupling. A host
+ * holding its own copy of the string would keep compiling through a rename here, and quietly resume
+ * reporting the profile as an unnamed run — a failure with no red test anywhere.
+ */
+export const DATA_PROFILE_RUN_LITERAL = "data-profile";

package/dist/contracts/index.d.ts

@@ -1,5 +1,7 @@
-export type { PlanStep, PresentationContent, PresentationPart, PlanPart, RunCardPart, FileReferenceEntry, FileReferencePart, AskPart, RunStartedPart, StepStatus, DagStepState, DagStatePart, StepPhase, StepActivityPart, FileTreeEntry, StepFileTreePart, StepOutputFile, StepOutputPart, StepSummaryPart, StepBlockedPart, SynthesizedFinding, BiologicalTheme, RunSynthesisPart, SynthesisPhase, SynthesisProgressPart, RunCompletedFinding, RunCompletedPart, RunFailedPart, PreviewPart, DataPreviewFailedPart, CortexChatPart, } from "./chat-parts.js";
+export type { PlanStep, PresentationContent, PresentationPart, PlanPart, RunCardPart, FileReferenceEntry, FileReferencePart, AskPart, RunStartedPart, StepStatus, DagStepState, DagStatePart, StepPhase, StepActivityPart, FileTreeEntry, StepFileTreePart, StepOutputFile, StepOutputPart, StepSummaryPart, StepUsagePart, StepBlockedPart, SynthesizedFinding, BiologicalTheme, RunSynthesisPart, SynthesisPhase, SynthesisProgressPart, RunCompletedFinding, RunCompletedPart, RunFailedPart, PreviewPart, DataPreviewFailedPart, CortexChatPart, } from "./chat-parts.js";
 export type { EventSource, TextDeltaEvent, ToolStartedEvent, ToolFinishedEvent, FinishEvent, ChatErrorEvent, CortexChatEvent } from "./chat-events.js";
+export type { TokenUsageRollup } from "./usage.js";
+export { DATA_PROFILE_RUN_LITERAL } from "./data-profile.js";
 export type { TextPart, ToolCallPart, CortexPart, CortexMessage } from "./message.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./part-registry.js";
 export type { CortexChatPartType, PartDescriptor, PartEmitter, PartConsumer } from "./part-registry.js";

package/dist/contracts/index.js

@@ -1,3 +1,4 @@
+export { DATA_PROFILE_RUN_LITERAL } from "./data-profile.js";
 export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./part-registry.js";
 export { AnalogyCoverageSchema, AnalogyReportSchema, AnalogyReportErrorSchema, AnalogicalReasonerOutputSchema } from "./analogy-report.js";
 export { CoverageSchema, EntitySchema, SummarySchema, LiabilitySummarySchema, TractabilitySchema, IndicationsSchema, DrugInteractionsSchema, ClinicalDevelopmentSchema, SafetyProfileSchema, OffTissueRiskSchema, EvidenceConflictsSchema, EvidenceTimelineSchema, TranslationalChainSchema, AdditionalEvidenceSchema, DiscoveryTrialsSchema, DossierSchema, DossierSchemaV3Legacy, DossierV4Schema, DossierV5Schema, DossierV5BodySchema, ClinicalTrialAttributionV5Schema, ClinicalDevelopmentV5Schema, RegulatoryActionRowV5Schema, QualityGateStatusSchema, QualityGatesSchema, LiabilitySummaryV4Schema, ClinicalDevelopmentV4Schema, SafetyProfileV4Schema, OrganRiskRowV4Schema, ReferenceBiologyV4Shape, isDossier, dossierJsonSchema, SECTION_BLURBS, TargetAssessmentPhaseSchema, TargetAssessmentProgressEventSchema, } from "./target-dossier.js";

package/dist/contracts/message.d.ts

@@ -6,7 +6,9 @@
  * discriminant is `type`, so `switch (part.type) { case "data-report-preview": ... }`
  * narrows the union member without any `as` cast.
  */
+import type { ToolCallDetail, ToolOutcome } from "./chat-events.js";
 import type { CortexChatPart } from "./chat-parts.js";
+import type { TokenUsageRollup } from "./usage.js";
 /** A plain assistant/user text run. */
 export interface TextPart {
     type: "text";
@@ -24,7 +26,13 @@ export interface ToolCallPart {
     toolCallId: string;
     toolName: string;
     status: "started" | "finished";
-    isError?: boolean;
+    /**
+     * How the call ended. Absent while `status` is `"started"` — the outcome is
+     * not known yet. See {@link ToolOutcome}.
+     */
+    outcome?: ToolOutcome;
+    /** See {@link ToolCallDetail}. Absent when no detail was produced. */
+    detail?: ToolCallDetail;
 }
 /** The discriminated union of every part the chat path can carry. */
 export type CortexPart = TextPart | ToolCallPart | CortexChatPart;
@@ -39,4 +47,16 @@ export interface CortexMessage {
      * existing consumer is unaffected.
      */
     interrupted?: boolean;
+    /**
+     * What providers reported for the TURN this message completed — the same
+     * figure `FinishEvent.turnUsage` carries to a live surface, so a reloaded
+     * transcript renders what the live turn rendered. Carried only on the
+     * assistant message that ended a turn.
+     *
+     * Absent means no figure was reported: a turn whose calls reported nothing, a
+     * message stored before rollups were persisted, or any message that did not
+     * end a turn. Never an all-zero rollup — "spent nothing" and "was told
+     * nothing" stay distinguishable.
+     */
+    usage?: TokenUsageRollup;
 }

package/dist/contracts/part-registry.js

@@ -10,6 +10,7 @@ export const PART_REGISTRY = {
     "data-step-file-tree": { emitter: "workflow", consumer: "sidebar", transient: true, reconciling: true },
     "data-step-output": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: false },
     "data-step-summary": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: false },
+    "data-step-usage": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: false },
     "data-step-blocked": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: false },
     "data-run-synthesis": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: false },
     "data-synthesis-progress": { emitter: "workflow", consumer: "sidebar", transient: false, reconciling: true },

package/dist/contracts/schemas/chat-events.d.ts

@@ -14,10 +14,17 @@ export declare const TextDeltaEventSchema: z.ZodObject<{
         callPath: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+/** Mirrors the `ToolOutcome` union — three states, never a boolean. */
+export declare const ToolOutcomeSchema: z.ZodEnum<{
+    error: "error";
+    ok: "ok";
+    denied: "denied";
+}>;
 export declare const ToolStartedEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"tool-started">;
     toolUseId: z.ZodString;
     name: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
     source: z.ZodObject<{
         agentId: z.ZodString;
         callPath: z.ZodArray<z.ZodString>;
@@ -27,7 +34,12 @@ export declare const ToolFinishedEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"tool-finished">;
     toolUseId: z.ZodString;
     name: z.ZodString;
-    isError: z.ZodBoolean;
+    outcome: z.ZodEnum<{
+        error: "error";
+        ok: "ok";
+        denied: "denied";
+    }>;
+    detail: z.ZodOptional<z.ZodString>;
     source: z.ZodObject<{
         agentId: z.ZodString;
         callPath: z.ZodArray<z.ZodString>;
@@ -39,6 +51,20 @@ export declare const FinishEventSchema: z.ZodObject<{
         agentId: z.ZodString;
         callPath: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
+    usage: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodOptional<z.ZodNumber>;
+        outputTokens: z.ZodOptional<z.ZodNumber>;
+        cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+        cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
+        reasoningTokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    turnUsage: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodOptional<z.ZodNumber>;
+        outputTokens: z.ZodOptional<z.ZodNumber>;
+        cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+        cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
+        reasoningTokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const ChatErrorEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"error">;
@@ -60,6 +86,7 @@ export declare const CortexChatEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject
     type: z.ZodLiteral<"tool-started">;
     toolUseId: z.ZodString;
     name: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
     source: z.ZodObject<{
         agentId: z.ZodString;
         callPath: z.ZodArray<z.ZodString>;
@@ -68,7 +95,12 @@ export declare const CortexChatEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject
     type: z.ZodLiteral<"tool-finished">;
     toolUseId: z.ZodString;
     name: z.ZodString;
-    isError: z.ZodBoolean;
+    outcome: z.ZodEnum<{
+        error: "error";
+        ok: "ok";
+        denied: "denied";
+    }>;
+    detail: z.ZodOptional<z.ZodString>;
     source: z.ZodObject<{
         agentId: z.ZodString;
         callPath: z.ZodArray<z.ZodString>;
@@ -79,6 +111,20 @@ export declare const CortexChatEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject
         agentId: z.ZodString;
         callPath: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
+    usage: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodOptional<z.ZodNumber>;
+        outputTokens: z.ZodOptional<z.ZodNumber>;
+        cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+        cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
+        reasoningTokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    turnUsage: z.ZodOptional<z.ZodObject<{
+        inputTokens: z.ZodOptional<z.ZodNumber>;
+        outputTokens: z.ZodOptional<z.ZodNumber>;
+        cacheCreationInputTokens: z.ZodOptional<z.ZodNumber>;
+        cacheReadInputTokens: z.ZodOptional<z.ZodNumber>;
+        reasoningTokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"error">;
     message: z.ZodString;

package/dist/contracts/schemas/chat-events.js

@@ -2,6 +2,7 @@
  * Zod schemas for Cortex-native chat-stream events — validation at boundaries.
  */
 import { z } from "zod";
+import { TokenUsageRollupSchema } from "./usage.js";
 export const EventSourceSchema = z.object({
     agentId: z.string(),
     callPath: z.array(z.string()),
@@ -11,22 +12,28 @@ export const TextDeltaEventSchema = z.object({
     text: z.string(),
     source: EventSourceSchema,
 });
+/** Mirrors the `ToolOutcome` union — three states, never a boolean. */
+export const ToolOutcomeSchema = z.enum(["ok", "error", "denied"]);
 export const ToolStartedEventSchema = z.object({
     type: z.literal("tool-started"),
     toolUseId: z.string(),
     name: z.string(),
+    detail: z.string().optional(),
     source: EventSourceSchema,
 });
 export const ToolFinishedEventSchema = z.object({
     type: z.literal("tool-finished"),
     toolUseId: z.string(),
     name: z.string(),
-    isError: z.boolean(),
+    outcome: ToolOutcomeSchema,
+    detail: z.string().optional(),
     source: EventSourceSchema,
 });
 export const FinishEventSchema = z.object({
     type: z.literal("finish"),
     source: EventSourceSchema,
+    usage: TokenUsageRollupSchema.optional(),
+    turnUsage: TokenUsageRollupSchema.optional(),
 });
 export const ChatErrorEventSchema = z.object({
     type: z.literal("error"),