@inflexa-ai/harness 0.14.2 → 0.15.1

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"),

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

@@ -104,8 +104,8 @@ export declare const FileReferencePartSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const AskStatusSchema: z.ZodEnum<{
-    pending: "pending";
     aborted: "aborted";
+    pending: "pending";
     resolved: "resolved";
     rejected: "rejected";
     expired: "expired";
@@ -117,8 +117,8 @@ export declare const AskPartSchema: z.ZodObject<{
     command: z.ZodString;
     detail: z.ZodOptional<z.ZodString>;
     status: z.ZodEnum<{
-        pending: "pending";
         aborted: "aborted";
+        pending: "pending";
         resolved: "resolved";
         rejected: "rejected";
         expired: "expired";
@@ -279,6 +279,21 @@ export declare const StepSummaryPartSchema: z.ZodObject<{
     agentId: z.ZodString;
     markdown: z.ZodString;
 }, z.core.$strip>;
+export declare const StepUsagePartSchema: z.ZodObject<{
+    type: z.ZodLiteral<"data-step-usage">;
+    id: z.ZodString;
+    runId: z.ZodString;
+    stepId: z.ZodString;
+    agentId: z.ZodString;
+    modelId: z.ZodString;
+    usage: 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 StepBlockedPartSchema: z.ZodObject<{
     type: z.ZodLiteral<"data-step-blocked">;
     id: z.ZodString;
@@ -314,6 +329,13 @@ export declare const RunCompletedPartSchema: z.ZodObject<{
         }>;
     }, z.core.$strip>>;
     note: z.ZodOptional<z.ZodString>;
+    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>>;
 }, z.core.$strip>;
 export declare const SynthesizedFindingSchema: z.ZodObject<{
     stepId: z.ZodString;
@@ -512,8 +534,8 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     command: z.ZodString;
     detail: z.ZodOptional<z.ZodString>;
     status: z.ZodEnum<{
-        pending: "pending";
         aborted: "aborted";
+        pending: "pending";
         resolved: "resolved";
         rejected: "rejected";
         expired: "expired";
@@ -607,6 +629,20 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     stepId: z.ZodString;
     agentId: z.ZodString;
     markdown: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"data-step-usage">;
+    id: z.ZodString;
+    runId: z.ZodString;
+    stepId: z.ZodString;
+    agentId: z.ZodString;
+    modelId: z.ZodString;
+    usage: 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<"data-step-blocked">;
     id: z.ZodString;
@@ -691,6 +727,13 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         }>;
     }, z.core.$strip>>;
     note: z.ZodOptional<z.ZodString>;
+    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>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"data-run-failed">;
     runId: z.ZodString;

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

@@ -2,6 +2,7 @@
  * Zod schemas for Cortex chat data parts — validation at boundaries.
  */
 import { z } from "zod";
+import { TokenUsageRollupSchema } from "./usage.js";
 // ── Presentation ────────────────────────────────────────────────────
 export const PlanStepSchema = z.object({
     id: z.string(),
@@ -181,6 +182,16 @@ export const StepSummaryPartSchema = z.object({
     agentId: z.string(),
     markdown: z.string(),
 });
+// ── Step Usage ──────────────────────────────────────────────────────
+export const StepUsagePartSchema = z.object({
+    type: z.literal("data-step-usage"),
+    id: z.string(),
+    runId: z.string(),
+    stepId: z.string(),
+    agentId: z.string(),
+    modelId: z.string(),
+    usage: TokenUsageRollupSchema,
+});
 export const StepBlockedPartSchema = z.object({
     type: z.literal("data-step-blocked"),
     id: z.string(),
@@ -203,6 +214,7 @@ export const RunCompletedPartSchema = z.object({
     artifactCount: z.number(),
     findings: z.array(RunCompletedFindingSchema),
     note: z.string().optional(),
+    usage: TokenUsageRollupSchema.optional(),
 });
 // ── Run Synthesis ──────────────────────────────────────────────────
 export const SynthesizedFindingSchema = z.object({
@@ -295,6 +307,7 @@ export const CortexChatPartSchema = z.discriminatedUnion("type", [
     StepFileTreePartSchema,
     StepOutputPartSchema,
     StepSummaryPartSchema,
+    StepUsagePartSchema,
     StepBlockedPartSchema,
     RunSynthesisPartSchema,
     SynthesisProgressPartSchema,

package/dist/contracts/schemas/index.d.ts

@@ -1,2 +1,3 @@
-export { PlanStepSchema, PresentationContentSchema, PresentationPartSchema, PlanPartSchema, RunCardPartSchema, FileReferenceEntrySchema, FileReferencePartSchema, RunStartedPartSchema, StepStatusSchema, DagStepStateSchema, DagStatePartSchema, StepPhaseSchema, StepActivityPartSchema, FileTreeEntrySchema, StepFileTreePartSchema, StepOutputFileSchema, StepOutputPartSchema, StepSummaryPartSchema, StepBlockedPartSchema, SynthesizedFindingSchema, BiologicalThemeSchema, RunSynthesisPartSchema, SynthesisPhaseSchema, SynthesisProgressPartSchema, RunCompletedFindingSchema, RunCompletedPartSchema, RunFailedPartSchema, PreviewPartSchema, DataPreviewFailedPartSchema, CortexChatPartSchema, } from "./chat-parts.js";
+export { PlanStepSchema, PresentationContentSchema, PresentationPartSchema, PlanPartSchema, RunCardPartSchema, FileReferenceEntrySchema, FileReferencePartSchema, RunStartedPartSchema, StepStatusSchema, DagStepStateSchema, DagStatePartSchema, StepPhaseSchema, StepActivityPartSchema, FileTreeEntrySchema, StepFileTreePartSchema, StepOutputFileSchema, StepOutputPartSchema, StepSummaryPartSchema, StepUsagePartSchema, StepBlockedPartSchema, SynthesizedFindingSchema, BiologicalThemeSchema, RunSynthesisPartSchema, SynthesisPhaseSchema, SynthesisProgressPartSchema, RunCompletedFindingSchema, RunCompletedPartSchema, RunFailedPartSchema, PreviewPartSchema, DataPreviewFailedPartSchema, CortexChatPartSchema, } from "./chat-parts.js";
 export { EventSourceSchema, TextDeltaEventSchema, ToolStartedEventSchema, ToolFinishedEventSchema, FinishEventSchema, ChatErrorEventSchema, CortexChatEventSchema, } from "./chat-events.js";
+export { TokenUsageRollupSchema } from "./usage.js";

package/dist/contracts/schemas/index.js

@@ -1,2 +1,3 @@
-export { PlanStepSchema, PresentationContentSchema, PresentationPartSchema, PlanPartSchema, RunCardPartSchema, FileReferenceEntrySchema, FileReferencePartSchema, RunStartedPartSchema, StepStatusSchema, DagStepStateSchema, DagStatePartSchema, StepPhaseSchema, StepActivityPartSchema, FileTreeEntrySchema, StepFileTreePartSchema, StepOutputFileSchema, StepOutputPartSchema, StepSummaryPartSchema, StepBlockedPartSchema, SynthesizedFindingSchema, BiologicalThemeSchema, RunSynthesisPartSchema, SynthesisPhaseSchema, SynthesisProgressPartSchema, RunCompletedFindingSchema, RunCompletedPartSchema, RunFailedPartSchema, PreviewPartSchema, DataPreviewFailedPartSchema, CortexChatPartSchema, } from "./chat-parts.js";
+export { PlanStepSchema, PresentationContentSchema, PresentationPartSchema, PlanPartSchema, RunCardPartSchema, FileReferenceEntrySchema, FileReferencePartSchema, RunStartedPartSchema, StepStatusSchema, DagStepStateSchema, DagStatePartSchema, StepPhaseSchema, StepActivityPartSchema, FileTreeEntrySchema, StepFileTreePartSchema, StepOutputFileSchema, StepOutputPartSchema, StepSummaryPartSchema, StepUsagePartSchema, StepBlockedPartSchema, SynthesizedFindingSchema, BiologicalThemeSchema, RunSynthesisPartSchema, SynthesisPhaseSchema, SynthesisProgressPartSchema, RunCompletedFindingSchema, RunCompletedPartSchema, RunFailedPartSchema, PreviewPartSchema, DataPreviewFailedPartSchema, CortexChatPartSchema, } from "./chat-parts.js";
 export { EventSourceSchema, TextDeltaEventSchema, ToolStartedEventSchema, ToolFinishedEventSchema, FinishEventSchema, ChatErrorEventSchema, CortexChatEventSchema, } from "./chat-events.js";
+export { TokenUsageRollupSchema } from "./usage.js";

package/dist/contracts/schemas/usage.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Zod schema for the token-usage rollup — validation at boundaries.
+ */
+import { z } from "zod";
+export declare const TokenUsageRollupSchema: 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>;

package/dist/contracts/schemas/usage.js

@@ -0,0 +1,18 @@
+/**
+ * Zod schema for the token-usage rollup — validation at boundaries.
+ */
+import { z } from "zod";
+/**
+ * One reported count. Token counts are whole tokens and cannot run negative, so
+ * the schema rejects fractions and negatives rather than passing them through as
+ * plain numbers. Optional throughout: absent means "not reported", never zero.
+ */
+const tokenCount = z.number().int().nonnegative().optional();
+export const TokenUsageRollupSchema = z.object({
+    inputTokens: tokenCount,
+    outputTokens: tokenCount,
+    cacheCreationInputTokens: tokenCount,
+    cacheReadInputTokens: tokenCount,
+    reasoningTokens: tokenCount,
+});
+const _assertSchemaFields = true;

package/dist/contracts/usage.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Token-usage rollups on the Cortex wire vocabulary.
+ *
+ * A rollup is the sum of what providers reported across some set of LLM calls
+ * — one agent loop, one whole turn, one run step. It is declared here, and not
+ * imported from the provider seam, because `contracts/` is the sole
+ * Cortex↔consumer wire contract and must stay free of the harness's own
+ * dependencies: a frontend importing these types should not inherit a
+ * typecheck dependency on the AI SDK.
+ *
+ * Every field is optional and absent means "not reported" — never zero. A set
+ * of calls that reported nothing carries no rollup at all rather than an
+ * all-zero one, so a consumer can tell "spent nothing" from "was told nothing".
+ */
+export interface TokenUsageRollup {
+    /** Total billed prefix, cache reads included. */
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    /** Prefix tokens written into the provider's prompt cache. */
+    readonly cacheCreationInputTokens?: number;
+    /** Prefix tokens served from the provider's prompt cache. */
+    readonly cacheReadInputTokens?: number;
+    /**
+     * Exactly what the provider reported — never derived from, nor reconciled
+     * against, `outputTokens`. Whether reasoning tokens sit inside the output
+     * total varies by provider, so arithmetic between the two is a guess.
+     */
+    readonly reasoningTokens?: number;
+}
+/**
+ * The rollup's fields as values — the single enumeration a fold can iterate.
+ *
+ * This shape is declared four times over: here, on the provider seam's
+ * `ChatUsage`, on the loop's mutable `AgentRunUsage`, and on the Zod schema
+ * beside this file. Nothing but this list joins them, and it is deliberately
+ * the *only* thing that does: `contracts/` is the Cortex↔consumer wire
+ * vocabulary and must not import the loop, the providers, or the AI SDK, so a
+ * shared base type is not available to it. What is available is a
+ * dependency-free constant every side may import — the loop folds by iterating
+ * it (`loop/metrics.ts:addChatUsage`), and the declarations that cannot be
+ * expressed in terms of it are pinned to it by key-set assertions at their own
+ * sites, which is why adding a sixth count in one place fails `tsc` instead of
+ * silently going unfolded.
+ *
+ * `satisfies` rejects a name that is not a field; the assertion below rejects a
+ * field that is not named. Both directions are needed — either alone leaves one
+ * kind of drift compiling.
+ */
+export declare const TOKEN_USAGE_FIELDS: readonly ["inputTokens", "outputTokens", "cacheCreationInputTokens", "cacheReadInputTokens", "reasoningTokens"];
+/** One token-usage field name. */
+export type TokenUsageField = (typeof TOKEN_USAGE_FIELDS)[number];

package/dist/contracts/usage.js

@@ -0,0 +1,41 @@
+/**
+ * Token-usage rollups on the Cortex wire vocabulary.
+ *
+ * A rollup is the sum of what providers reported across some set of LLM calls
+ * — one agent loop, one whole turn, one run step. It is declared here, and not
+ * imported from the provider seam, because `contracts/` is the sole
+ * Cortex↔consumer wire contract and must stay free of the harness's own
+ * dependencies: a frontend importing these types should not inherit a
+ * typecheck dependency on the AI SDK.
+ *
+ * Every field is optional and absent means "not reported" — never zero. A set
+ * of calls that reported nothing carries no rollup at all rather than an
+ * all-zero one, so a consumer can tell "spent nothing" from "was told nothing".
+ */
+/**
+ * The rollup's fields as values — the single enumeration a fold can iterate.
+ *
+ * This shape is declared four times over: here, on the provider seam's
+ * `ChatUsage`, on the loop's mutable `AgentRunUsage`, and on the Zod schema
+ * beside this file. Nothing but this list joins them, and it is deliberately
+ * the *only* thing that does: `contracts/` is the Cortex↔consumer wire
+ * vocabulary and must not import the loop, the providers, or the AI SDK, so a
+ * shared base type is not available to it. What is available is a
+ * dependency-free constant every side may import — the loop folds by iterating
+ * it (`loop/metrics.ts:addChatUsage`), and the declarations that cannot be
+ * expressed in terms of it are pinned to it by key-set assertions at their own
+ * sites, which is why adding a sixth count in one place fails `tsc` instead of
+ * silently going unfolded.
+ *
+ * `satisfies` rejects a name that is not a field; the assertion below rejects a
+ * field that is not named. Both directions are needed — either alone leaves one
+ * kind of drift compiling.
+ */
+export const TOKEN_USAGE_FIELDS = [
+    "inputTokens",
+    "outputTokens",
+    "cacheCreationInputTokens",
+    "cacheReadInputTokens",
+    "reasoningTokens",
+];
+const _assertFieldsComplete = true;

package/dist/execution/artifact-metadata.d.ts

@@ -25,6 +25,7 @@ import type { LoopMessage } from "../loop/types.js";
 import type { AgentChat } from "../providers/types.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import type { Logger } from "../lib/logger.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
 export interface ArtifactForMetadata {
     /** Path used to update `cortex_artifacts` after metadata generation. */
     readonly dbPath: string;
@@ -36,6 +37,8 @@ export interface ArtifactForMetadata {
 export interface GenerateFileMetadataOptions {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
+    /** LLM usage-accounting seam for the describer loop; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
     readonly provider: AgentChat;
     readonly session: AgentSession;
     readonly artifacts: readonly ArtifactForMetadata[];

package/dist/execution/artifact-metadata.js

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

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

@@ -0,0 +1,30 @@
+/**
+ * DBOS realization of the `WorkflowPurger` seam — the single production adapter,
+ * shared by every embedder. Host-neutral: it references only DBOS, which the
+ * harness already depends on.
+ *
+ * It is built on `DBOSClient`, not the static `DBOS` facade. The facade's
+ * workflow-management calls require a launched engine and throw without one,
+ * which would make a purge impossible from exactly the process that needs it
+ * most: a headless command holding nothing but a pool. `DBOSClient` accepts a
+ * pre-built pool and needs no launch, so one realization serves a booted host and
+ * a headless one alike and no embedder has to choose between two purgers. The
+ * engine's system database is the same database as the application pool, so the
+ * injected pool already reaches the ledger.
+ *
+ * The engine owns the deletion itself, including the breadth-first walk over
+ * `parent_workflow_id` that reaches child step workflows. Its single
+ * `DELETE FROM dbos.workflow_status WHERE workflow_uuid = ANY(...)` is all the
+ * dependent tables need: step outputs, streams, inputs, events, notifications,
+ * and queue rows each hold an `ON DELETE CASCADE` foreign key to
+ * `workflow_status`, so they go with the status row.
+ */
+import type { Pool } from "pg";
+import type { Logger } from "../lib/logger.js";
+import type { WorkflowPurger } from "./workflow-purger.js";
+export interface DbosWorkflowPurgerDeps {
+    /** Pool onto the engine's system database — the same database the application pool holds. */
+    readonly pool: Pool;
+    readonly logger?: Logger;
+}
+export declare function createDbosWorkflowPurger({ pool, logger: injected }: DbosWorkflowPurgerDeps): WorkflowPurger;

package/dist/execution/dbos-workflow-purger.js

@@ -0,0 +1,193 @@
+/**
+ * DBOS realization of the `WorkflowPurger` seam — the single production adapter,
+ * shared by every embedder. Host-neutral: it references only DBOS, which the
+ * harness already depends on.
+ *
+ * It is built on `DBOSClient`, not the static `DBOS` facade. The facade's
+ * workflow-management calls require a launched engine and throw without one,
+ * which would make a purge impossible from exactly the process that needs it
+ * most: a headless command holding nothing but a pool. `DBOSClient` accepts a
+ * pre-built pool and needs no launch, so one realization serves a booted host and
+ * a headless one alike and no embedder has to choose between two purgers. The
+ * engine's system database is the same database as the application pool, so the
+ * injected pool already reaches the ledger.
+ *
+ * The engine owns the deletion itself, including the breadth-first walk over
+ * `parent_workflow_id` that reaches child step workflows. Its single
+ * `DELETE FROM dbos.workflow_status WHERE workflow_uuid = ANY(...)` is all the
+ * dependent tables need: step outputs, streams, inputs, events, notifications,
+ * and queue rows each hold an `ON DELETE CASCADE` foreign key to
+ * `workflow_status`, so they go with the status row.
+ */
+import { DBOSClient } from "@dbos-inc/dbos-sdk";
+import { errAsync, okAsync } from "neverthrow";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { tryMutation, tryQuery } from "../lib/db-result.js";
+/**
+ * The schema the engine keeps its ledger in. The raw SQL below names it literally,
+ * `DBOSClient` defaults to it, and the schema probe asks after this same name — the
+ * SDK accepts a `systemDatabaseSchemaName`, so moving a deployment's ledger has to
+ * move all three together.
+ */
+const SYSTEM_SCHEMA = "dbos";
+/**
+ * SQLSTATE `undefined_table` — the answer both when the engine never created its
+ * schema and when `workflow_status` is gone from beneath a schema that exists. Only
+ * the first is nothing to purge, so the code on its own settles nothing.
+ */
+const UNDEFINED_TABLE = "42P01";
+function isUndefinedTable(e) {
+    const cause = e.cause;
+    return cause !== null && typeof cause === "object" && "code" in cause && cause.code === UNDEFINED_TABLE;
+}
+/**
+ * Route the client's own diagnostics — pool errors and idle-client errors — onto
+ * the injected sink. Left unset, the SDK builds a console logger of its own, and
+ * a host whose UI owns stdout discards those records entirely.
+ *
+ * The SDK renders every entry to a string before delegating, and splits a failure
+ * across both parameters: the text arrives as the entry, the stack — with any
+ * `cause` chain already folded into it — as `metadata.stack`. So the entry is the
+ * record's message at every level, `error` included, and engine wording stays
+ * queryable in one place instead of the message at three levels and a field at the
+ * fourth. The stack rides beside it under the key `defaultErrorFields` uses.
+ * `errorFields` is not the tool here: it normalizes a thrown value, and an entry
+ * the SDK has already rendered takes its `String(...)` branch, which emits a bare
+ * message and drops the one stack the SDK bothered to hand over.
+ */
+function asEngineLogger(logger) {
+    const render = (entry) => (typeof entry === "string" ? entry : String(entry));
+    return {
+        debug: (entry) => logger.debug(render(entry)),
+        info: (entry) => logger.info(render(entry)),
+        warn: (entry) => logger.warn(render(entry)),
+        error: (entry, metadata) => logger.error(render(entry), metadata?.stack === undefined ? undefined : { stack: metadata.stack }),
+    };
+}
+export function createDbosWorkflowPurger({ pool, logger: injected }) {
+    const logger = (injected ?? createNoopLogger()).named("workflow-purger");
+    // One client per factory, not per call. Creating a client does no I/O, but the
+    // client registers `error` and `connect` handlers on the pool it is handed, so a
+    // client per purge would accumulate handler pairs on a long-lived pool. Its
+    // `destroy()` ends that pool, so a client over an injected pool must never be
+    // destroyed either — which leaves a per-call client nothing to release. Creation
+    // is lazy so building a purger stays free for a host that never purges.
+    let pending;
+    const engine = () => {
+        // `create` never initializes the system database, and initialization is the
+        // only path that reads the connection string once a pool is supplied — so the
+        // url is unreachable from this client rather than merely untaken, and there is
+        // none to thread through the seam.
+        pending ??= DBOSClient.create({ systemDatabaseUrl: "", systemDatabasePool: pool, logger: asEngineLogger(logger) });
+        return pending;
+    };
+    /**
+     * Whether the engine's schema exists at all — the only thing that separates a
+     * ledger the engine never created from one that is broken. It costs a round trip
+     * only on the failure path that consults it, and a positive answer is memoized for
+     * the purger's lifetime, since nothing drops the schema once the engine has made
+     * it. A negative answer is deliberately not memoized: a purger can be built before
+     * the launch that creates the schema, and caching absence would go on reading a
+     * ledger that has since broken as one that was never there.
+     */
+    let schemaConfirmed = false;
+    const systemSchemaExists = () => {
+        if (schemaConfirmed)
+            return okAsync(true);
+        return tryQuery("workflowPurger.systemSchemaPresent", async () => {
+            const { rows } = await pool.query({
+                text: `SELECT EXISTS (SELECT 1 FROM information_schema.schemata WHERE schema_name = $1) AS present`,
+                values: [SYSTEM_SCHEMA],
+            });
+            return rows[0]?.present ?? false;
+        }).map((present) => {
+            schemaConfirmed = present;
+            return present;
+        });
+    };
+    /**
+     * Recover a ledger the engine never created into `fallback`. A missing table
+     * beneath a schema that does exist stays on the error channel along with every
+     * other failure — an SDK rename, a manual drop, or a half-applied migration
+     * reaches the caller as one, rather than as a purge that reclaimed nothing.
+     */
+    function whenLedgerAbsent(fallback) {
+        return (e) => isUndefinedTable(e) ? systemSchemaExists().andThen((present) => (present ? errAsync(e) : okAsync(fallback))) : errAsync(e);
+    }
+    /**
+     * How many ledger rows the delete is about to take, read immediately before it,
+     * because the engine's delete reports no count of its own. This is a read only:
+     * the walk it mirrors selects the same set the delete targets — requested ids that
+     * exist, plus their descendants when asked — while the delete itself and its
+     * cascades stay engine-owned.
+     */
+    const countDoomed = (workflowIds, includeDescendants) => tryQuery("workflowPurger.countDoomed", async () => {
+        const { rows } = await pool.query(includeDescendants
+            ? {
+                // The non-recursive term unnests the requested ids rather than
+                // reading them out of the ledger, so a descendant is still
+                // reached when the id it descends from has already been
+                // removed; the outer count then keeps only rows that exist.
+                text: `WITH RECURSIVE doomed AS (
+                                     SELECT unnest($1::text[]) AS workflow_uuid
+                                     UNION
+                                     SELECT child.workflow_uuid
+                                       FROM dbos.workflow_status child
+                                       JOIN doomed ON child.parent_workflow_id = doomed.workflow_uuid
+                                 )
+                                 SELECT COUNT(*)::int AS total
+                                 FROM dbos.workflow_status
+                                 WHERE workflow_uuid IN (SELECT workflow_uuid FROM doomed)`,
+                values: [workflowIds],
+            }
+            : {
+                text: `SELECT COUNT(*)::int AS total FROM dbos.workflow_status WHERE workflow_uuid = ANY($1)`,
+                values: [workflowIds],
+            });
+        return rows[0]?.total ?? 0;
+    });
+    return {
+        findByIdPrefix(prefix) {
+            return tryQuery("workflowPurger.findByIdPrefix", async () => {
+                const { rows } = await pool.query({
+                    // `starts_with` rather than a parameterized LIKE pattern: a namespace
+                    // carrying `_` or `%` would match as a wildcard there and sweep in
+                    // workflows belonging to a different analysis.
+                    text: `SELECT workflow_uuid FROM dbos.workflow_status WHERE starts_with(workflow_uuid, $1)`,
+                    values: [prefix],
+                });
+                return rows.map((row) => row.workflow_uuid);
+            }).orElse(whenLedgerAbsent([]));
+        },
+        cancel(workflowIds) {
+            if (workflowIds.length === 0)
+                return okAsync(undefined);
+            return tryMutation("workflowPurger.cancel", async () => {
+                const client = await engine();
+                // Descendants too: the delete side reaches them, so roots-only
+                // cancellation would leave child step executors writing behind it.
+                await client.cancelWorkflows([...workflowIds], { cancelChildren: true });
+            })
+                .map(() => {
+                logger.debug("cancelled workflows", { requested: workflowIds.length });
+            })
+                .orElse(whenLedgerAbsent(undefined));
+        },
+        deleteWorkflows(workflowIds, includeDescendants = false) {
+            if (workflowIds.length === 0)
+                return okAsync(0);
+            const ids = [...workflowIds];
+            return countDoomed(ids, includeDescendants)
+                .andThen((doomed) => tryMutation("workflowPurger.deleteWorkflows", async () => {
+                const client = await engine();
+                await client.deleteWorkflows(ids, includeDescendants);
+                return doomed;
+            }))
+                .map((deleted) => {
+                logger.debug("deleted workflows", { deleted, includeDescendants });
+                return deleted;
+            })
+                .orElse(whenLedgerAbsent(0));
+        },
+    };
+}

package/dist/execution/post-step-pipeline.d.ts

@@ -17,6 +17,7 @@ import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import type { ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
 import type { StepSummary } from "../schemas/step-summary.js";
 import type { Logger } from "../lib/logger.js";
+import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ArtifactRegistry } from "./artifact-registry.js";
 import { type FileMetadataEntry } from "./artifact-metadata.js";
 import type { PostStepArtifacts, PostStepContext, StepOutputs } from "../workflows/sandbox-step.js";
@@ -28,6 +29,8 @@ export interface PostStepPipelineDeps {
     readonly pool: Pool;
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
+    /** LLM usage-accounting seam for the metadata + summary loops; omitted falls back to the no-op recorder. */
+    readonly usageRecorder?: UsageRecorder;
     /** Non-streaming chat — the metadata + summary sub-agent loops. */
     readonly provider: AgentChat;
     /** Write-side embedder for the vector index. */

package/dist/execution/post-step-pipeline.js

@@ -36,6 +36,7 @@ export async function generateStepFileMetadata(deps, postCtx, manifest) {
     }));
     const result = await coreGenerateFileMetadata({
         provider: deps.provider,
+        usageRecorder: deps.usageRecorder,
         session,
         artifacts: artifactsForMeta,
         resourceId: input.analysisId,
@@ -61,6 +62,7 @@ export async function generateStepSummaryAndWrite(deps, postCtx, manifest) {
     const { input, session, transcript, writePrefix } = postCtx;
     const summary = await coreGenerateStepSummary({
         provider: deps.provider,
+        usageRecorder: deps.usageRecorder,
         session,
         modelId: deps.model,
         messages: transcript,