@inflexa-ai/harness 0.14.2 → 0.15.0

package/dist/providers/ai-sdk.js

@@ -1,4 +1,4 @@
-import { generateText, streamText } from "ai";
+import { generateText, streamText, wrapLanguageModel } from "ai";
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { APICallError } from "@ai-sdk/provider";
@@ -222,6 +222,10 @@ function createRetry(signal, logger) {
  * vendor's own snake_case.
  *
  * `inputTokens` is the total billed prefix, cache reads included.
+ *
+ * `reasoningTokens` rides the neutral `outputTokenDetails` beside the text
+ * count and is copied verbatim: providers disagree on whether reasoning tokens
+ * are already inside the output total, so the harness reconciles nothing.
  */
 function toChatUsage(usage) {
     if (usage === undefined)
@@ -231,22 +235,72 @@ function toChatUsage(usage) {
         outputTokens: usage.outputTokens,
         cacheCreationInputTokens: usage.inputTokenDetails?.cacheWriteTokens,
         cacheReadInputTokens: usage.inputTokenDetails?.cacheReadTokens,
+        reasoningTokens: usage.outputTokenDetails?.reasoningTokens,
     };
 }
-function responseFromMessages(messages, fallbackText, finishReason, rawFinishReason, usage) {
+/** The id of the model bound into this provider — a bare id string is its own id. */
+function requestedModelIdOf(model) {
+    return typeof model === "string" ? model : model.modelId;
+}
+/**
+ * Capture the served model id at the raw model boundary, because that is the
+ * only place it is still distinguishable from the requested one: `generateText`
+ * and `streamText` both coalesce an unreported response model id to the bound
+ * model's own id, so reading `result.response.modelId` would silently republish
+ * the requested id as an endpoint's claim. A middleware sees the provider's
+ * result before that fallback applies, so "reported nothing" stays absent.
+ *
+ * Built per call, never per provider: one provider instance serves concurrent
+ * calls, and a shared mutable slot would hand one call another's answer. A bare
+ * model-id string has no wire result to observe, so it captures nothing.
+ */
+function captureServedModelId(model) {
+    if (typeof model === "string")
+        return { model, servedModelId: () => undefined };
+    let served;
+    const wrapped = wrapLanguageModel({
+        model,
+        middleware: {
+            wrapGenerate: async ({ doGenerate }) => {
+                const result = await doGenerate();
+                served = result.response?.modelId;
+                return result;
+            },
+            wrapStream: async ({ doStream }) => {
+                const result = await doStream();
+                return {
+                    ...result,
+                    stream: result.stream.pipeThrough(new TransformStream({
+                        transform(chunk, controller) {
+                            if (chunk.type === "response-metadata" && chunk.modelId !== undefined)
+                                served = chunk.modelId;
+                            controller.enqueue(chunk);
+                        },
+                    })),
+                };
+            },
+        },
+    });
+    return { model: wrapped, servedModelId: () => served };
+}
+function responseFromMessages(input) {
+    const { messages, fallbackText, finishReason, rawFinishReason, requestedModelId, servedModelId } = input;
+    const usage = toChatUsage(input.usage);
     const message = [...messages].reverse().find((m) => m.role === "assistant");
     if (message === undefined) {
-        return {
-            message: { role: "assistant", content: fallbackText },
-            finishReason,
-            rawFinishReason,
-            usage: toChatUsage(usage),
-        };
+        return { message: { role: "assistant", content: fallbackText }, finishReason, rawFinishReason, usage, requestedModelId, servedModelId };
     }
-    return { message, finishReason, rawFinishReason, usage: toChatUsage(usage) };
+    return { message, finishReason, rawFinishReason, usage, requestedModelId, servedModelId };
 }
-function responseFromGenerate(result) {
-    return responseFromMessages(result.responseMessages, result.text, result.finishReason, result.rawFinishReason, result.usage);
+function responseFromGenerate(result, identity) {
+    return responseFromMessages({
+        messages: result.responseMessages,
+        fallbackText: result.text,
+        finishReason: result.finishReason,
+        rawFinishReason: result.rawFinishReason,
+        usage: result.usage,
+        ...identity,
+    });
 }
 /**
  * Drop empty text parts — and messages left with no content at all — before
@@ -279,17 +333,19 @@ export function createAiSdkProvider(deps) {
     const capabilities = { toolCalling: deps.capabilities?.toolCalling ?? true };
     const logger = (deps.logger ?? createNoopLogger()).named("providers.ai-sdk");
     const maxOutputTokens = deps.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS;
+    const requestedModelId = requestedModelIdOf(deps.model);
     routeSdkWarningsTo(logger);
     function chat(req, session, signal) {
         const run = async () => {
             const retry = createRetry(signal, logger);
+            const capture = captureServedModelId(deps.model);
             try {
                 const result = await retry(async () => {
                     // Attribution headers are time-limited; resolving them inside the
                     // retried closure keeps them fresh across a multi-minute window.
                     const headers = await resolveBillingHeaders(deps.resolveBilling, session);
                     return generateText({
-                        model: deps.model,
+                        model: capture.model,
                         system: req.system,
                         messages: sanitizeMessages(req.messages),
                         tools: req.tools,
@@ -304,7 +360,7 @@ export function createAiSdkProvider(deps) {
                         providerOptions: req.providerOptions,
                     });
                 });
-                return ok(responseFromGenerate(result));
+                return ok(responseFromGenerate(result, { requestedModelId, servedModelId: capture.servedModelId() }));
             }
             catch (e) {
                 if (isAbortError(e) || signal?.aborted)
@@ -316,6 +372,7 @@ export function createAiSdkProvider(deps) {
     }
     async function* chatStream(req, session, signal) {
         const retry = createRetry(signal, logger);
+        const capture = captureServedModelId(deps.model);
         try {
             // Retry covers only stream establishment: streamText defers wire errors
             // to consumption, so a failure is not visible until the stream is read.
@@ -328,7 +385,7 @@ export function createAiSdkProvider(deps) {
             const opened = await retry(async () => {
                 const headers = await resolveBillingHeaders(deps.resolveBilling, session);
                 const result = streamText({
-                    model: deps.model,
+                    model: capture.model,
                     system: req.system,
                     messages: sanitizeMessages(req.messages),
                     tools: req.tools,
@@ -364,7 +421,15 @@ export function createAiSdkProvider(deps) {
                 return { kind: "streaming", result, iterator, firstDelta: first.value };
             });
             if (opened.kind === "completed") {
-                const response = responseFromMessages(opened.messages, "", opened.finishReason, opened.rawFinishReason, opened.usage);
+                const response = responseFromMessages({
+                    messages: opened.messages,
+                    fallbackText: "",
+                    finishReason: opened.finishReason,
+                    rawFinishReason: opened.rawFinishReason,
+                    usage: opened.usage,
+                    requestedModelId,
+                    servedModelId: capture.servedModelId(),
+                });
                 yield { type: "done", response };
                 return;
             }
@@ -377,7 +442,17 @@ export function createAiSdkProvider(deps) {
                 text += next.value;
                 yield { type: "text-delta", text: next.value };
             }
-            const response = responseFromMessages(await result.responseMessages, text, await result.finishReason, await result.rawFinishReason, await result.usage);
+            const response = responseFromMessages({
+                messages: await result.responseMessages,
+                fallbackText: text,
+                finishReason: await result.finishReason,
+                rawFinishReason: await result.rawFinishReason,
+                usage: await result.usage,
+                requestedModelId,
+                // Read after the drain: the metadata chunk carrying the served id
+                // reaches the capture only as the stream is consumed.
+                servedModelId: capture.servedModelId(),
+            });
             yield { type: "done", response };
         }
         catch (e) {

package/dist/providers/streaming-chat.js

@@ -67,6 +67,11 @@ export function createStreamingChat(provider, onText) {
                         // response is authoritative, so return it rather than the assembled deltas.
                         if (final !== undefined)
                             return ok(final);
+                        // The partial carries no model identity and no usage: it is
+                        // assembled from deltas rather than from a provider response, so
+                        // nothing here reported which model answered or what it cost.
+                        // Stamping the requested id would manufacture a claim the
+                        // endpoint never made.
                         return ok({ message: { role: "assistant", content: partial }, finishReason: "aborted" });
                     }
                     return err(toProviderError(e, workload));

package/dist/providers/types.d.ts

@@ -46,6 +46,11 @@ export type PromptCachePolicy = {
  * seeds the cache (billed at a premium; it only pays for itself once a later
  * call reads it back).
  *
+ * `reasoningTokens` is exactly what the provider reported — never derived from,
+ * nor reconciled against, `outputTokens`. Whether reasoning tokens are counted
+ * inside the output total varies by provider, so any arithmetic between the two
+ * would be a guess dressed as a figure.
+ *
  * Every field is optional: a provider that reports no usage at all, or reports
  * totals without a cache breakdown, is legitimate. Absent means "not reported",
  * never "zero".
@@ -55,6 +60,7 @@ export interface ChatUsage {
     readonly outputTokens?: number;
     readonly cacheCreationInputTokens?: number;
     readonly cacheReadInputTokens?: number;
+    readonly reasoningTokens?: number;
 }
 export interface ChatResponse {
     readonly message: Extract<ModelMessage, {
@@ -72,6 +78,23 @@ export interface ChatResponse {
     readonly finishReason: FinishReason | "aborted";
     readonly rawFinishReason?: string;
     readonly usage?: ChatUsage;
+    /**
+     * The id of the model this provider instance is bound to — what the caller
+     * asked for. Absent when the binding names no id.
+     */
+    readonly requestedModelId?: string;
+    /**
+     * The model id the provider itself reported as having answered. Absent
+     * whenever the provider reported none — it is NEVER filled in from
+     * `requestedModelId`, because a claim about which model answered is only
+     * worth anything when the endpoint actually made it.
+     *
+     * A value differing from `requestedModelId` is not an error: the pair exists
+     * so a consumer can observe an endpoint or proxy serving a different model
+     * version than the one configured. Treat the comparison as best-effort
+     * diagnostics, never as an invariant.
+     */
+    readonly servedModelId?: string;
 }
 export type ChatStreamEvent = {
     readonly type: "text-delta";

package/dist/providers/types.js

@@ -5,4 +5,5 @@
  * vendor-neutral interfaces. Every call carries an `AgentSession`; billing
  * attribution is resolved lazily at the provider wire boundary.
  */
+const _assertChatUsageFields = true;
 export {};

package/dist/runtime/assemble.d.ts

@@ -15,6 +15,7 @@
  * before launch — a blue/green drain treats them as a single cohort.
  */
 import { type ConversationAgentDeps } from "../agents/conversation-agent.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ResourcePolicy } from "../config/resource-limits.js";
 import type { AgentDefinition } from "../loop/types.js";
 import { type ExecuteAnalysisDeps, type ExecuteAnalysisInput, type ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
@@ -27,12 +28,20 @@ export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxSt
  * Deps bundles for the durable workflows. `executeAnalysis` is a builder
  * because its `sandboxStepCallable` is the registered sandbox-step callable,
  * which does not exist until registration runs inside `assembleCoreRuntime`.
+ *
+ * Each bag omits `usageRecorder` for the same reason `ConversationAssemblyDeps`
+ * does: the recorder is resolved once below and stamped onto every bag this
+ * call registers, so one runtime reports to one ledger. Leaving it settable
+ * here would let an embedder wire a recorder the workflows use and the
+ * conversation agent does not — a half-wired ledger that reads as a complete
+ * one. The protection has to hold on both sides of the assembly, not just the
+ * conversation side.
  */
 export interface CoreWorkflowDeps {
-    readonly sandboxStep: SandboxStepDeps;
-    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => ExecuteAnalysisDeps;
-    readonly executeTargetAssessment: ExecuteTargetAssessmentDeps;
-    readonly dataProfile: DataProfileDeps;
+    readonly sandboxStep: Omit<SandboxStepDeps, "usageRecorder">;
+    readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => Omit<ExecuteAnalysisDeps, "usageRecorder">;
+    readonly executeTargetAssessment: Omit<ExecuteTargetAssessmentDeps, "usageRecorder">;
+    readonly dataProfile: Omit<DataProfileDeps, "usageRecorder">;
 }
 /** The registered, callable workflow handles. */
 export interface RegisteredWorkflows {
@@ -42,11 +51,12 @@ export interface RegisteredWorkflows {
     readonly dataProfile: (input: DataProfileWorkflowInput) => Promise<void>;
 }
 /**
- * Conversation-agent deps minus the workflow callable and the resource
- * policy — `assembleCoreRuntime` supplies those itself so a caller cannot wire
- * a stale callable or a policy that diverges from the one the workflows see.
+ * Conversation-agent deps minus the workflow callable, the resource policy, and
+ * the usage recorder — `assembleCoreRuntime` supplies those itself so a caller
+ * cannot wire a stale callable, a policy that diverges from the one the
+ * workflows see, or a recorder that only half the agent tree reports to.
  */
-export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy">;
+export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy" | "usageRecorder">;
 export interface CoreRuntimeDeps {
     readonly conversation: ConversationAssemblyDeps;
     readonly workflows: CoreWorkflowDeps;
@@ -55,6 +65,13 @@ export interface CoreRuntimeDeps {
      * point for planner/routing guidance and workflow-input budget snapshots.
      */
     readonly resourcePolicy?: ResourcePolicy;
+    /**
+     * LLM usage-accounting seam. Resolved once here and stamped onto the
+     * conversation agent and every workflow deps bag this call registers, so
+     * one runtime reports to one ledger. Omitted falls back to
+     * `createNoopUsageRecorder()`.
+     */
+    readonly usageRecorder?: UsageRecorder;
 }
 export interface CoreRuntime {
     readonly conversationAgent: AgentDefinition;

package/dist/runtime/assemble.js

@@ -15,20 +15,23 @@
  * before launch — a blue/green drain treats them as a single cohort.
  */
 import { createConversationAgent } from "../agents/conversation-agent.js";
+import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { registerExecuteAnalysis } from "../workflows/execute-analysis.js";
 import { registerSandboxStep } from "../workflows/sandbox-step.js";
 import { registerExecuteTargetAssessment, } from "../workflows/execute-target-assessment.js";
 import { registerDataProfileWorkflow } from "../tasks/data-profile.js";
 export function assembleCoreRuntime(deps) {
     const { conversation, workflows: wf, resourcePolicy } = deps;
-    const sandboxStep = registerSandboxStep(wf.sandboxStep);
-    const executeAnalysis = registerExecuteAnalysis(wf.buildExecuteAnalysis(sandboxStep));
-    const executeTargetAssessment = registerExecuteTargetAssessment(wf.executeTargetAssessment);
-    const dataProfile = registerDataProfileWorkflow(wf.dataProfile);
+    const usageRecorder = deps.usageRecorder ?? createNoopUsageRecorder();
+    const sandboxStep = registerSandboxStep({ ...wf.sandboxStep, usageRecorder });
+    const executeAnalysis = registerExecuteAnalysis({ ...wf.buildExecuteAnalysis(sandboxStep), usageRecorder });
+    const executeTargetAssessment = registerExecuteTargetAssessment({ ...wf.executeTargetAssessment, usageRecorder });
+    const dataProfile = registerDataProfileWorkflow({ ...wf.dataProfile, usageRecorder });
     const conversationAgent = createConversationAgent({
         ...conversation,
         executeAnalysisWorkflow: executeAnalysis,
         resourcePolicy,
+        usageRecorder,
     });
     return {
         conversationAgent,

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

@@ -6,6 +6,7 @@
  * into its emitters.
  */
 import type { ChatDataPart, EmitFn } from "../loop/types.js";
+import type { ToolDetailResolver } from "../tools/detail-resolver.js";
 /**
  * Stable reconciliation id for a step's reconciling parts
  * (`data-step-activity`, `data-step-file-tree`). One id per (runId, stepId)
@@ -18,7 +19,27 @@ import type { ChatDataPart, EmitFn } from "../loop/types.js";
  * producers construct it identically.
  */
 export declare function stepPartId(kind: string, runId: string, stepId: string): string;
-export declare function activityForTool(name: string, input?: unknown): string;
+/**
+ * The live-activity phrase for one tool call: the tool's name, then its own
+ * description of this call when it has one.
+ *
+ * The description comes from the tool's `describeCall` hook, resolved through
+ * `resolveDetail` — the same resolver the chat chip and the reloaded transcript
+ * use. A caller supplies the resolver for the agent whose calls it is
+ * describing, because a sandbox agent's tool list is not the conversation
+ * roster's and no single list serves both.
+ *
+ * The name always leads, and that is load-bearing rather than cosmetic. This
+ * phrase is rendered alone, with no tool name beside it — unlike the chat chip,
+ * which prints the name itself and can afford a bare detail. `write_file` and
+ * `edit_file` both describe a call by its path, so a detail on its own would
+ * render a write and an edit of the same file identically.
+ *
+ * A tool with no hook, an unknown tool, and an input its schema rejects all fall
+ * back to the name alone. No verb is added: the phrase is carried on a part that
+ * already states the phase, so "Running" would only restate it.
+ */
+export declare function activityForTool(name: string, input?: unknown, resolveDetail?: ToolDetailResolver): string;
 /** On-change working-tree delta the sandbox executor posts per exec (paths
  *  only; the executor skips directories). */
 export interface SandboxTreeDelta {

package/dist/sandbox/sandbox-step-translate.js

@@ -19,42 +19,29 @@
 export function stepPartId(kind, runId, stepId) {
     return `${kind}-${runId}-${stepId}`;
 }
-/** Friendly live-activity label per sandbox tool id. Falls back to the raw
- *  tool name so a newly added tool still reads sensibly. */
-const TOOL_ACTIVITY = {
-    execute_command: "Running script",
-    write_file: "Writing file",
-    edit_file: "Editing file",
-    read_file: "Reading file",
-    grep: "Searching files",
-    list_files: "Listing files",
-};
-/** Last path segment of a posix/win path-like string. */
-function baseName(p) {
-    const parts = p.split(/[\\/]/);
-    return parts[parts.length - 1] || p;
-}
-/** Display file name for a tool's live-activity label, or null when the input
- *  carries no sensible name. Path tools (`write_file`/`edit_file`/`read_file`)
- *  carry `path`; `execute_command` carries an argv `command` whose first
- *  script-like token names what's running. */
-function activityFileName(name, input) {
-    if (input === null || typeof input !== "object")
-        return null;
-    const obj = input;
-    if (name === "execute_command") {
-        const cmd = obj.command;
-        if (!Array.isArray(cmd))
-            return null;
-        const script = cmd.find((a) => typeof a === "string" && /\.(py|R|r|sh|js|ts|ipynb)$/.test(a));
-        return script ? baseName(script) : null;
-    }
-    return typeof obj.path === "string" && obj.path.length > 0 ? baseName(obj.path) : null;
-}
-export function activityForTool(name, input) {
-    const label = TOOL_ACTIVITY[name] ?? `Running ${name}`;
-    const file = activityFileName(name, input);
-    return file ? `${label} ${file}` : label;
+/**
+ * The live-activity phrase for one tool call: the tool's name, then its own
+ * description of this call when it has one.
+ *
+ * The description comes from the tool's `describeCall` hook, resolved through
+ * `resolveDetail` — the same resolver the chat chip and the reloaded transcript
+ * use. A caller supplies the resolver for the agent whose calls it is
+ * describing, because a sandbox agent's tool list is not the conversation
+ * roster's and no single list serves both.
+ *
+ * The name always leads, and that is load-bearing rather than cosmetic. This
+ * phrase is rendered alone, with no tool name beside it — unlike the chat chip,
+ * which prints the name itself and can afford a bare detail. `write_file` and
+ * `edit_file` both describe a call by its path, so a detail on its own would
+ * render a write and an edit of the same file identically.
+ *
+ * A tool with no hook, an unknown tool, and an input its schema rejects all fall
+ * back to the name alone. No verb is added: the phrase is carried on a part that
+ * already states the phase, so "Running" would only restate it.
+ */
+export function activityForTool(name, input, resolveDetail) {
+    const detail = resolveDetail?.(name, input);
+    return detail === undefined ? name : `${name} ${detail}`;
 }
 /** Extract the tree delta from a `data-sandbox-event` part, or null when the
  *  part is some other sandbox event. The wrapper shape is set by

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

@@ -57,6 +57,7 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
             "clinical-evidence": "clinical-evidence";
         }>;
         actionType: z.ZodOptional<z.ZodEnum<{
+            none: "none";
             "therapeutic-target": "therapeutic-target";
             "predictive-biomarker": "predictive-biomarker";
             "prognostic-biomarker": "prognostic-biomarker";
@@ -65,7 +66,6 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
             "resistance-mechanism": "resistance-mechanism";
             "patient-stratification": "patient-stratification";
             "mechanism-of-action": "mechanism-of-action";
-            none: "none";
         }>>;
         rationale: z.ZodString;
     }, z.core.$strip>>;
@@ -123,6 +123,7 @@ export declare const RunSynthesisSchema: z.ZodObject<{
                 "clinical-evidence": "clinical-evidence";
             }>;
             actionType: z.ZodOptional<z.ZodEnum<{
+                none: "none";
                 "therapeutic-target": "therapeutic-target";
                 "predictive-biomarker": "predictive-biomarker";
                 "prognostic-biomarker": "prognostic-biomarker";
@@ -131,7 +132,6 @@ export declare const RunSynthesisSchema: z.ZodObject<{
                 "resistance-mechanism": "resistance-mechanism";
                 "patient-stratification": "patient-stratification";
                 "mechanism-of-action": "mechanism-of-action";
-                none: "none";
             }>>;
             rationale: z.ZodString;
         }, z.core.$strip>>;

package/dist/state/index.d.ts

@@ -23,6 +23,8 @@ export type { InsertPlanInput, UpsertPlanInput } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export type { DataProfileStatus, DataProfileResult, DataProfileInputFile, DataProfileFile, DataProfileQualityAssessment } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
+export { createAnalysisPurge } from "./purge-analysis.js";
+export type { AnalysisPurge, AnalysisPurgeDeps, AnalysisPurgeOutcome } from "./purge-analysis.js";
 export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, SynthesisStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
 export type { AnalysisStateRow, ArtifactRow, CortexRunRow, StepExecutionRow, CortexPlanRow } from "./schema.js";
 export { insertAssessment, updateProgress, setDossier, markFailed, getAssessment, listAssessmentsByOrg, softDeleteAssessment, TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentRowSchema, } from "./target-assessments.js";

package/dist/state/index.js

@@ -16,5 +16,8 @@ export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes,
 export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
+// Not per-entity: one analysis's whole Postgres footprint, reached from its id
+// alone, with the workflow ledger behind an injected seam.
+export { createAnalysisPurge } from "./purge-analysis.js";
 export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, SynthesisStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
 export { insertAssessment, updateProgress, setDossier, markFailed, getAssessment, listAssessmentsByOrg, softDeleteAssessment, TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentRowSchema, } from "./target-assessments.js";

package/dist/state/init.js

@@ -8,6 +8,9 @@
  */
 import { backfillAiSdkMessageEnvelopes } from "../memory/message-backfill.js";
 import { createNoopLogger } from "../lib/console-logger.js";
+// No ';' may appear anywhere in this text, comments included: it is executed by
+// splitting on ';' (see `DDL.split` below), so a semicolon inside a comment cuts
+// the statement it precedes in half and Postgres rejects the fragment.
 const DDL = `
 -- Analysis-level state (status, context, data-profile tracking, billing identity).
 --
@@ -227,6 +230,25 @@ CREATE INDEX IF NOT EXISTS idx_cortex_regulatory_chunks_metadata
 -- re-sent to the provider on the next turn, where a reordered prefix misses the
 -- prompt cache. JSON stores the text verbatim. Nothing indexes this column, and
 -- the JSON operators retractLastTurn uses work the same on either type.
+--
+-- reported_usage holds a whole turn's TokenUsageRollup — what providers reported
+-- for the turn this row completed — and is written only on the LAST assistant row
+-- of a turn, so a reloaded transcript can show the figure the live turn showed.
+-- It is NOT the tokens column beside it, and the two must never be read for
+-- each other: tokens is an offline js-tiktoken estimate stamped on EVERY row so
+-- the read path can window by budget without a provider round trip, and it exists
+-- for rows no provider ever saw. reported_usage is a provider's own report, and
+-- covers a turn rather than a row. Both are plausible-looking integers on one row,
+-- which is exactly why the column names carry the distinction.
+--
+-- Nullable with no default: absent means nothing was reported, and a zero would
+-- claim a turn cost nothing. A row written before this column existed is absent
+-- for the same reason, so the migration needs no backfill.
+--
+-- JSONB here, unlike message_envelope above. The verbatim-bytes requirement that
+-- forces JSON on the envelope is about model content that is re-sent to the
+-- provider. This record is harness-generated, has a fixed field set, and never
+-- reaches a prompt, so it does not share that requirement.
 CREATE TABLE IF NOT EXISTS messages (
   thread_id     TEXT NOT NULL,
   seq           BIGINT NOT NULL,
@@ -234,6 +256,7 @@ CREATE TABLE IF NOT EXISTS messages (
   content_jsonb JSONB,
   message_envelope JSON,
   tokens        INTEGER NOT NULL,
+  reported_usage JSONB,
   created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   PRIMARY KEY (thread_id, seq)
 );
@@ -432,6 +455,11 @@ export async function initCortexState(pool, injected) {
                 // dropping an absent NOT NULL no-ops, so this is a no-op on fresh DBs.
                 "ALTER TABLE cortex_analysis_state ALTER COLUMN data_profile_status DROP NOT NULL",
                 "ALTER TABLE messages ADD COLUMN IF NOT EXISTS message_envelope JSON",
+                // The turn's reported usage rollup (see the CREATE TABLE comment).
+                // Purely additive: nullable with no default, so adding it rewrites no
+                // row and every pre-existing message reads back with no rollup — which
+                // is the honest value, the figures having never been recorded.
+                "ALTER TABLE messages ADD COLUMN IF NOT EXISTS reported_usage JSONB",
                 // Demote an existing JSONB envelope column to JSON (see the CREATE
                 // TABLE comment). Type-guarded because ALTER ... TYPE rewrites the
                 // whole table and this runs at every boot; scoped to

package/dist/state/purge-analysis.d.ts

@@ -0,0 +1,74 @@
+/**
+ * purgeAnalysis — the single place that knows what an analysis's persisted
+ * Postgres footprint is.
+ *
+ * A host asks for it with an `analysisId` and nothing else: every keyed store,
+ * the analysis's dynamic vector-table name, and its workflow ids are all
+ * derivable from that id, so no caller enumerates tables or supplies a run list.
+ * The workflow ledger is part of the footprint, not a follow-on — the sandbox
+ * transcripts and run-event streams live there and are the dominant share of an
+ * analysis's stored bytes — and it is reached through the injected
+ * `WorkflowPurger` seam so the durability engine stays out of the state layer.
+ *
+ * There is no single transaction across the stages: the purge spans app tables, a
+ * DDL `DROP TABLE`, and the engine's system schema, so instead of faking atomicity
+ * every stage is idempotent and the whole operation is safe to re-run. A purge of
+ * an unknown or already-purged analysis therefore succeeds, reporting zeroes. Each
+ * stage carries the reason it sits where it does.
+ *
+ * A purge is NOT serialized against work still starting on the analysis. The
+ * mapping from an analysis to its workflows is read once, up front, out of
+ * `cortex_runs`; a run inserted after that read is outside the captured set, and
+ * the `cortex_runs` delete later in the same purge removes the only row that could
+ * ever have named it. Its workflow row and every byte cascading off it then belong
+ * to no analysis — no retry reaches them, because nothing is left that attributes
+ * them to one. Quiesce the analysis before purging it: no new runs, no new
+ * data-profile triggers. This module cannot observe a host's in-flight work, so it
+ * does not enforce that.
+ *
+ * What it does not reach, so that absent coverage is never read as delivered:
+ * scheduled operational workflows (they belong to no analysis and accumulate
+ * independently of any purge), target assessments and their annotations (a
+ * separate top-level entity), the shared regulatory corpus, `messages` rows whose
+ * thread row is already gone (nothing attributes them to an analysis), and
+ * workspace files on disk (the embedder owns their disposal).
+ */
+import { ResultAsync } from "neverthrow";
+import type { Pool } from "pg";
+import type { WorkflowPurger } from "../execution/workflow-purger.js";
+import { type DbError } from "../lib/db-result.js";
+import type { Logger } from "../lib/logger.js";
+/**
+ * What one invocation reclaimed. It is a report of this call, not a claim that the
+ * analysis is now empty: a re-run still reclaims whatever a failed stage left
+ * behind, and rows written under a workflow the purge already deleted, which trip
+ * their foreign key.
+ */
+export interface AnalysisPurgeOutcome {
+    readonly threads: number;
+    readonly messages: number;
+    /**
+     * How many workflows the ledger delete targeted, counted immediately before it
+     * and outside any transaction, because the engine owns the delete and reports no
+     * count of its own. It is not a post-delete tally: a row arriving between the
+     * count and the delete is deleted without being counted.
+     */
+    readonly workflows: number;
+    readonly vectorIndexDropped: boolean;
+}
+export interface AnalysisPurgeDeps {
+    readonly pool: Pool;
+    /** The workflow-ledger seam. Cancellation and deletion by id, engine-agnostic. */
+    readonly workflows: WorkflowPurger;
+    readonly logger?: Logger;
+}
+export interface AnalysisPurge {
+    /**
+     * Remove the analysis's entire persisted Postgres footprint. Absence is a
+     * normal outcome: an unknown or already-purged analysis succeeds with zeroes.
+     * Every failure rides the error channel — the operation never reports a purge
+     * it did not achieve. The caller quiesces the analysis first (module note).
+     */
+    purgeAnalysis(analysisId: string): ResultAsync<AnalysisPurgeOutcome, DbError>;
+}
+export declare function createAnalysisPurge({ pool, workflows, logger: injected }: AnalysisPurgeDeps): AnalysisPurge;