stageflow 0.15.0 → 0.18.0

package/dist/runtime/stageAttemptBootstrap.js

@@ -4,7 +4,9 @@ import { MCP_CATALOG_FILENAME, STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV, StageMcpError,
 import { attemptArtifactsDir } from "../runstore/workspaceLayout.js";
 import { resolveCloneEmitContext, resolveForkEmitContext } from "../config/resolveForkEmitContext.js";
 import { createAttemptQaTrailReader } from "../hitl/qaTrail.js";
+import { assertPriorInputPayload, payloadInstanceMismatch, } from "../envelope/payloadSchema.js";
 import { buildCompletedEnvelopesFromRun, resolvePriorEnvelope, } from "./envelopeRouting.js";
+import { assignment } from "./cloneSchedule.js";
 import { resumeSessionFilePath } from "./stageAttemptContext.js";
 import { buildStageRoots, rootsForStageWorker, withResolvedAuthPath, } from "./stageRoots.js";
 async function resolveStageSkillForRun(stage, catalog) {
@@ -76,6 +78,51 @@ async function openStageWithOperatorCatalog(agent, input, catalog, factoryCwd, a
         };
     }
 }
+function assertPriorsMatchCloneInput(cloneInputSchema, childId, priorResult, task, skipCloneAssignment) {
+    if (cloneInputSchema === undefined)
+        return { ok: true };
+    if (skipCloneAssignment)
+        return { ok: true };
+    try {
+        if (priorResult.priorEnvelopesByStage !== undefined) {
+            for (const value of Object.values(priorResult.priorEnvelopesByStage)) {
+                const envelopes = Array.isArray(value) ? value : [value];
+                for (const envelope of envelopes) {
+                    if (envelope.status !== "success")
+                        continue;
+                    assertPriorInputPayload(envelope, cloneInputSchema, childId);
+                }
+            }
+            return { ok: true };
+        }
+        if (priorResult.joinPriors !== undefined) {
+            for (const envelope of priorResult.joinPriors) {
+                if (envelope.status !== "success")
+                    continue;
+                assertPriorInputPayload(envelope, cloneInputSchema, childId);
+            }
+            return { ok: true };
+        }
+        if (priorResult.prior !== null) {
+            assertPriorInputPayload(priorResult.prior, cloneInputSchema, childId);
+            return { ok: true };
+        }
+        const details = payloadInstanceMismatch(task.input ?? {}, cloneInputSchema);
+        if (details !== undefined) {
+            return {
+                ok: false,
+                reason: `task input does not match io.input.schema for ${childId}: ${details}`,
+            };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 function resolveAttemptRoots(input, stageId) {
     const baseRoots = input.roots ??
         (input.workerRoots
@@ -136,15 +183,20 @@ export async function openStageAttempt(input) {
     const definitionId = input.stage.id;
     const completedEnvelopes = input.completedEnvelopes ??
         (await buildCompletedEnvelopesFromRun(input.store, input.runId, undefined, input.dag));
-    const priorResult = await resolvePriorEnvelope({
-        dag: input.dag,
-        stageId,
-        completedEnvelopes,
-        store: input.store,
-        runId: input.runId,
-    });
+    const assigned = assignment(input.dag, stageId, definitionId, completedEnvelopes);
+    const priorResult = assigned ??
+        (await resolvePriorEnvelope({
+            dag: input.dag,
+            stageId,
+            completedEnvelopes,
+            store: input.store,
+            runId: input.runId,
+        }));
     if (!priorResult.ok)
         return priorResult;
+    const priorInput = assertPriorsMatchCloneInput(input.stage.clone_input_schema, stageId, priorResult, input.task, false);
+    if (!priorInput.ok)
+        return priorInput;
     const roots = resolveAttemptRoots(input, stageId);
     const attempt = input.attemptCtx?.attempt ?? 1;
     const resumeToken = input.resumeToken ??
@@ -152,9 +204,6 @@ export async function openStageAttempt(input) {
     const forkEmitContext = resolveForkEmitContext(input.dag, definitionId);
     const snapshot = input.dag;
     const cloneEmitContext = resolveCloneEmitContext(input.dag, definitionId, {
-        ...(input.stage.clone_actions !== undefined
-            ? { allowedActions: input.stage.clone_actions }
-            : {}),
         ...(snapshot.clone_input_schema !== undefined
             ? { successorCloneInputSchemas: snapshot.clone_input_schema }
             : {}),
@@ -163,7 +212,7 @@ export async function openStageAttempt(input) {
     const runtimeNode = input.dag.nodes.find((node) => node.id === stageId);
     const isDynamicCloneInstance = runtimeNode?.definition_id !== undefined &&
         runtimeNode.definition_id !== runtimeNode.id;
-    const feedbackLoopEmitContext = isDynamicCloneInstance || runtimeNode?.clonable === true
+    const feedbackLoopEmitContext = isDynamicCloneInstance
         ? undefined
         : runtimeNode?.feedback_loop;
     const repairContext = await repairContextForAttempt(input, stageId, attempt);

package/dist/runtime/stageRunner.js

@@ -54,7 +54,7 @@ async function finalizeStageResult(options) {
             store,
             runId,
             stageId,
-            event: { event: "failed", reason: result.reason },
+            event: { event: "failed", reason: result.reason, usage: result.usage },
             attemptCtx,
         });
         console.error(`Stage ${stageId} failed: ${result.reason}`);
@@ -64,7 +64,7 @@ async function finalizeStageResult(options) {
         store,
         runId,
         stageId,
-        event: { event: "succeeded" },
+        event: { event: "succeeded", usage: result.usage },
         attemptCtx,
     });
     console.error(`Stage ${stageId} succeeded.`);

package/dist/runtime/taskInput.js

@@ -34,21 +34,9 @@ export function checkTaskEntryInput(task, loaded, options) {
         const stage = stageById.get(rootId);
         if (stage?.clone_input_schema === undefined)
             continue;
-        if (task.input === undefined) {
-            findings.push({
-                severity: "warning",
-                code: "task.entry_input_unmet",
-                path: findingPath,
-                message: `Task has no input; entry stage "${rootId}" requires io.input`,
-                category: "task",
-                pipelineId: loaded.pipeline.id,
-                stageId: rootId,
-            });
-            continue;
-        }
         let details;
         try {
-            details = payloadInstanceMismatch(task.input, stage.clone_input_schema);
+            details = payloadInstanceMismatch(task.input ?? {}, stage.clone_input_schema);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);

package/dist/tools/emitStageEnvelope.d.ts

@@ -14,12 +14,12 @@ import type { TSchema } from "typebox/type";
 import { type PreEmitCheckOptions } from "../envelope/preEmitChecks.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { FeedbackLoopConfig } from "../types/pipeline.js";
-import { type CloneEmitContext, type ForkEmitContext } from "../types/forkChoice.js";
+import type { CloneEmitContext, ForkEmitContext } from "../types/forkChoice.js";
 export type EmitCapture = {
     envelope?: StageEnvelope;
     error?: string;
 };
-export declare function createEmitStageEnvelopeTool(capture: EmitCapture, payloadSchema?: unknown, forkEmitContext?: ForkEmitContext, cloneEmitContext?: CloneEmitContext, preEmitCheckOptions?: PreEmitCheckOptions, feedbackLoopEmitContext?: FeedbackLoopConfig): {
+export declare function createEmitStageEnvelopeTool(capture: EmitCapture, payloadSchema?: unknown, forkEmitContext?: ForkEmitContext, _cloneEmitContext?: CloneEmitContext, preEmitCheckOptions?: PreEmitCheckOptions, feedbackLoopEmitContext?: FeedbackLoopConfig): {
     name: string;
     label: string;
     description: string;
@@ -29,7 +29,6 @@ export declare function createEmitStageEnvelopeTool(capture: EmitCapture, payloa
         artifacts: Type.TArray<Type.TString>;
         payload: Type.TOptional<TSchema>;
         fork_choice: Type.TArray<Type.TString>;
-        clone_forks?: Type.TArray<TSchema> | undefined;
         feedback_loop?: Type.TOptional<TSchema> | undefined;
         checklist_attestations: Type.TOptional<Type.TArray<Type.TObject<{
             check_id: Type.TString;

package/dist/tools/emitStageEnvelope.js

@@ -12,11 +12,9 @@
 import { Type } from "typebox";
 import { assertRequiredEnvelope, isAdvancingEnvelope, } from "../envelope/check.js";
 import { assertFeedbackLoopAction } from "../envelope/feedbackLoop.js";
-import { assertCloneForks } from "../envelope/cloneForks.js";
 import { normalizeForkChoice } from "../envelope/forkChoice.js";
 import { assertEnvelopePayload, compilePayloadSchema, } from "../envelope/payloadSchema.js";
 import { assertPreEmitChecks, } from "../envelope/preEmitChecks.js";
-import { CLONE_ACTIONS, } from "../types/forkChoice.js";
 function stringLiteralsSchema(values) {
     if (values.length === 1) {
         return Type.Literal(values[0]);
@@ -42,56 +40,6 @@ function feedbackLoopActionSchema(context) {
         }, { additionalProperties: false }),
     ]);
 }
-function cloneForksItemSchema(cloneEmitContext) {
-    const allowedActions = cloneEmitContext.allowedActions ?? [...CLONE_ACTIONS];
-    const allowSkip = allowedActions.includes("skip");
-    const allowOnce = allowedActions.includes("once");
-    const allowFanout = allowedActions.includes("fanout");
-    const variants = [];
-    for (const successor of cloneEmitContext.clonableSuccessors) {
-        const successorId = Type.Literal(successor.successorId);
-        const nestedPayload = successor.cloneInputSchema !== undefined
-            ? compilePayloadSchema(successor.cloneInputSchema)
-            : undefined;
-        const nestedEnvelope = stageEnvelopeSchema(nestedPayload);
-        if (allowSkip) {
-            variants.push(Type.Object({
-                successor_id: successorId,
-                action: Type.Literal("skip"),
-            }, { additionalProperties: false }));
-        }
-        if (allowOnce) {
-            variants.push(Type.Object({
-                successor_id: successorId,
-                action: Type.Literal("once"),
-                envelope: nestedEnvelope,
-            }));
-        }
-        if (allowFanout) {
-            variants.push(Type.Object({
-                successor_id: successorId,
-                action: Type.Literal("fanout"),
-                mode: Type.Union([
-                    Type.Literal("parallel"),
-                    Type.Literal("sequential"),
-                ]),
-                clones: Type.Array(Type.Object({
-                    envelope: nestedEnvelope,
-                }), { minItems: 2, maxItems: successor.cloneCap }),
-            }));
-        }
-    }
-    if (variants.length === 0) {
-        return Type.Object({
-            successor_id: Type.String(),
-            action: stringLiteralsSchema(allowedActions),
-        });
-    }
-    if (variants.length === 1) {
-        return variants[0];
-    }
-    return Type.Union(variants);
-}
 function toolResult(text, details, options) {
     return {
         content: [{ type: "text", text }],
@@ -100,7 +48,7 @@ function toolResult(text, details, options) {
         ...(options?.terminate ? { terminate: true } : {}),
     };
 }
-export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitContext, cloneEmitContext, preEmitCheckOptions, feedbackLoopEmitContext) {
+export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitContext, _cloneEmitContext, preEmitCheckOptions, feedbackLoopEmitContext) {
     const compiledPayload = payloadSchema !== undefined
         ? compilePayloadSchema(payloadSchema)
         : undefined;
@@ -118,13 +66,6 @@ export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitCont
             fork_choice: forkEmitContext !== undefined && feedbackLoopEmitContext === undefined
                 ? Type.Array(Type.String())
                 : Type.Optional(Type.Array(Type.String())),
-            ...(cloneEmitContext !== undefined
-                ? {
-                    clone_forks: feedbackLoopEmitContext === undefined
-                        ? Type.Array(cloneForksItemSchema(cloneEmitContext))
-                        : Type.Optional(Type.Array(cloneForksItemSchema(cloneEmitContext))),
-                }
-                : {}),
             ...(feedbackLoopEmitContext !== undefined
                 ? {
                     feedback_loop: Type.Optional(feedbackLoopActionSchema(feedbackLoopEmitContext)),
@@ -150,11 +91,6 @@ export function createEmitStageEnvelopeTool(capture, payloadSchema, forkEmitCont
                     forkEmitContext !== undefined) {
                     normalizeForkChoice(envelope.fork_choice, "emit", forkEmitContext);
                 }
-                if (envelope.status !== "failure" &&
-                    !isSendBack &&
-                    cloneEmitContext !== undefined) {
-                    assertCloneForks(envelope, cloneEmitContext);
-                }
                 assertEnvelopePayload(envelope, payloadSchema);
                 if (envelope.status !== "failure") {
                     await assertPreEmitChecks(envelope, preEmitCheckOptions);

package/dist/types/envelope.d.ts

@@ -1,4 +1,3 @@
-import type { CloneForkItem } from "./forkChoice.js";
 export type EnvelopeStatus = "success" | "failure";
 export type FeedbackLoopAction = {
     action: "continue";
@@ -12,7 +11,6 @@ export type StageEnvelope = {
     artifacts: string[];
     payload?: Record<string, unknown>;
     fork_choice?: string[];
-    clone_forks?: CloneForkItem[];
     feedback_loop?: FeedbackLoopAction;
     /** Agent's explicit acknowledgement of pipeline-owned checklist items. */
     checklist_attestations?: Array<{

package/dist/types/forkChoice.d.ts

@@ -1,4 +1,3 @@
-import type { StageEnvelope } from "./envelope.js";
 export type ForkChoiceShape = {
     cardinality: "one" | "subset";
     allowNone: boolean;
@@ -9,21 +8,6 @@ export type ForkEmitContext = {
 };
 export declare const CLONE_ACTIONS: readonly ["skip", "once", "fanout"];
 export type CloneAction = (typeof CLONE_ACTIONS)[number];
-export type CloneForkItem = {
-    successor_id: string;
-    action: "skip";
-} | {
-    successor_id: string;
-    action: "once";
-    envelope: StageEnvelope;
-} | {
-    successor_id: string;
-    action: "fanout";
-    mode: "parallel" | "sequential";
-    clones: Array<{
-        envelope: StageEnvelope;
-    }>;
-};
 export type CloneSuccessorEmit = {
     successorId: string;
     cloneCap: number;

package/dist/types/pipeline.d.ts

@@ -1,4 +1,3 @@
-import type { CloneAction } from "./forkChoice.js";
 import type { LoadedStageConfig, StageGateKind, StageIoYaml } from "./stage.js";
 import type { CompletionContract, RecoveryPolicy } from "./completion.js";
 export type PipelineConfig = {
@@ -16,15 +15,75 @@ export type PipelineForkConfig = {
     allow_none: boolean;
 };
 export type NeedTerminalState = "succeeded" | "failed" | "skipped";
+export type RouteIfOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "not_in";
+export type RouteIfLeafPredicate = {
+    field: string;
+    op: RouteIfOp;
+    value: unknown;
+};
+export type RouteIfAllPredicate = {
+    all: RouteIfPredicate[];
+    field?: never;
+};
+export type RouteIfAnyPredicate = {
+    any: RouteIfPredicate[];
+    field?: never;
+};
+export type RouteIfNotPredicate = {
+    not: RouteIfPredicate;
+    field?: never;
+};
+export type RouteIfPredicate = RouteIfLeafPredicate | RouteIfAllPredicate | RouteIfAnyPredicate | RouteIfNotPredicate;
 export type PipelineNeedEdge = {
     id: string;
     on: NeedTerminalState[];
+    if?: RouteIfPredicate;
 };
 export type PipelineNeedItem = string | {
     id: string;
     on?: NeedTerminalState[];
 };
 export type PipelineNeeds = string | PipelineNeedEdge[];
+/**
+ * Terminal states a route entry (or its inverted predecessor edge) can gate on.
+ * Same domain as `NeedTerminalState` — kept as a distinct alias since `route`
+ * is a separate vocabulary from `needs` (see docs/yaml-catalog.md).
+ */
+export type RouteTerminalState = NeedTerminalState;
+/**
+ * A forward route entry: hands off from the declaring stage to `to`, gated on
+ * the declaring stage's own terminal state (`on`, defaulting to succeeded-only).
+ */
+export type PipelineRouteForwardEntry = {
+    to: string;
+    on?: RouteTerminalState | RouteTerminalState[];
+    if?: RouteIfPredicate;
+};
+/**
+ * A loop route entry (ticket 03, route-based-pipeline-wiring spec): sends
+ * execution back to a declared ancestor of the source stage instead of
+ * continuing forward, carrying the same replay policy `FeedbackLoopConfig`
+ * carries today — `target` renamed to `to` for naming consistency with
+ * forward entries. Contributes no forward DAG edge (`toRouteEdges` skips
+ * it), so it is excluded from cycle detection; it is a runtime-only replay
+ * schedule over the already-resolved forward graph.
+ */
+export type PipelineRouteLoopEntry = {
+    type: "loop";
+    to: string;
+    max_replays: number;
+    on_max_replays: "require_continue" | "wait_for_human";
+    replay_session: "resume" | "new_session";
+};
+export type PipelineRouteEntry = PipelineRouteForwardEntry | PipelineRouteLoopEntry;
+/** A stage's outbound `route` field: where execution goes next. */
+export type PipelineRoute = PipelineRouteEntry[];
+/** Normalized forward route edge (post-parse): `on` is always populated. */
+export type PipelineRouteEdge = {
+    to: string;
+    on: RouteTerminalState[];
+    if?: RouteIfPredicate;
+};
 /** Runtime feedback-loop policy declared by the stage that can send work back. */
 export type FeedbackLoopConfig = {
     target: string;
@@ -32,43 +91,44 @@ export type FeedbackLoopConfig = {
     on_max_replays: "require_continue" | "wait_for_human";
     replay_session: "resume" | "new_session";
 };
+export type CloneMode = "parallel" | "sequential";
 export type PipelineStageRef = {
     id: string;
-    needs?: string | PipelineNeedItem[];
-    fork?: {
-        select: "one" | "subset";
-        allow_none?: boolean;
-    };
-    clonable?: boolean;
-    clone_cap?: number;
     /** IR: after-phase checks. YAML: `verify` items whose `when` includes `after`. */
     completion?: CompletionContract;
     /** IR: after-phase failure policy. YAML: `on_verify_fail`. */
     recovery?: RecoveryPolicy;
-    feedback_loop?: FeedbackLoopConfig;
     /** Omitted means this stage is safe to include in a feedback replay. */
     replay_safe?: boolean;
+    /** Pipeline wiring vocabulary (see docs/yaml-catalog.md). */
+    route?: PipelineRouteEntry[];
+    /** Marks this stage as a pipeline entry point. */
+    entry?: boolean;
+    clone_cap?: number;
+    clone_mode?: CloneMode;
 };
 /**
- * Pipeline YAML stage entry (both dialects). Target authoring is `io` / `verify`
- * / `on_verify_fail`. The payload_schema / pre_emit_checks / completion /
- * recovery keys are the legacy YAML dialect (and also the IR names after compile).
- * New catalog fields: add target YAML keys here and compile them in yamlDialect.ts.
+ * Catalog YAML stage entry (`io` / `verify` / `on_verify_fail`). Not IR.
+ * Dual-read of `payload_schema` / `pre_emit_checks` / `completion` / `recovery`
+ * stays in `legacyYaml.ts` on the raw record.
  */
-export type PipelineStageYamlEntry = PipelineStageRef & {
+export type PipelineStageYamlEntry = {
+    id?: string;
     uses?: string;
     system_prompt?: string;
     model?: string;
-    payload_schema?: unknown;
     gate_kinds?: StageGateKind[];
-    clone_input_schema?: unknown;
-    clone_actions?: CloneAction[];
+    timeout_ms?: number;
     skill?: string;
     mcp?: string[];
+    replay_safe?: boolean;
+    route?: PipelineRouteEntry[];
+    entry?: boolean;
+    clone_cap?: number;
+    clone_mode?: CloneMode;
     io?: StageIoYaml;
     verify?: unknown;
     on_verify_fail?: RecoveryPolicy;
-    pre_emit_checks?: unknown;
 };
 export type PipelineIncludeEntry = {
     local: string;
@@ -79,20 +139,16 @@ export type PipelineFragmentConfig = {
 };
 export type NormalizedPipelineStageEntry = {
     id: string;
-    needs?: PipelineNeeds;
-    fork?: {
-        select: "one" | "subset";
-        allow_none?: boolean;
-    };
-    clonable?: boolean;
-    clone_cap?: number;
     /** IR after compile. YAML `verify` after-phase / `on_verify_fail`. */
     completion?: CompletionContract;
     recovery?: RecoveryPolicy;
-    feedback_loop?: FeedbackLoopConfig;
     replay_safe?: boolean;
+    route?: PipelineRouteEntry[];
+    entry?: boolean;
     skill?: string;
     mcp?: string[];
+    clone_cap?: number;
+    clone_mode?: CloneMode;
     body: {
         kind: "inline";
         raw: Record<string, unknown>;
@@ -116,8 +172,9 @@ export type ResolvedPipelineStageNode = {
     ancestors: string[];
     stageIndex: number;
     fork?: PipelineForkConfig;
-    clonable?: boolean;
     clone_cap?: number;
+    clone_mode?: CloneMode;
+    clone_array_field?: string;
     definition_id?: string;
     /** Persisted on pipeline_dag. YAML `verify` after-phase. */
     completion?: CompletionContract;
@@ -125,6 +182,8 @@ export type ResolvedPipelineStageNode = {
     recovery?: RecoveryPolicy;
     feedback_loop?: FeedbackLoopConfig;
     replay_safe?: boolean;
+    /** Present (true) only when this stage was declared `entry: true`. */
+    entry?: boolean;
 };
 export type ResolvedPipelineDag = {
     nodes: ResolvedPipelineStageNode[];

package/dist/types/stage.d.ts

@@ -1,14 +1,19 @@
 import type { PreEmitCheck } from "./preEmitCheck.js";
-import type { CloneAction } from "./forkChoice.js";
+/** Typed emit/schema fields from `compileTargetContract`. Not catalog YAML keys. */
+export type CompiledStageEmitBody = {
+    payload_schema?: unknown;
+    clone_input_schema?: unknown;
+    pre_emit_checks?: PreEmitCheck[];
+};
 export declare const STAGE_GATE_KINDS: readonly ["free_text", "confirm", "multi_question", "artifact_backed"];
 export type StageGateKind = (typeof STAGE_GATE_KINDS)[number];
 /** Target YAML `io:` block. Compiles onto StageConfig.payload_schema / clone_input_schema. */
 export type StageIoYaml = {
-    input?: {
-        schema?: unknown;
+    input: {
+        schema: unknown;
     };
-    output?: {
-        schema?: unknown;
+    output: {
+        schema: unknown;
     };
 };
 /**
@@ -27,9 +32,8 @@ export type StageConfig = {
     gate_kinds?: StageGateKind[];
     /** IR: emit-phase checks. YAML: `verify` items whose `when` includes `emit`. */
     pre_emit_checks?: PreEmitCheck[];
-    /** IR: clone/fan-out assignment schema. YAML: `io.input.schema`. */
+    /** IR: inbound assignment schema. YAML: `io.input.schema`. */
     clone_input_schema?: unknown;
-    clone_actions?: CloneAction[];
     /** Optional stage wall-clock timeout in milliseconds (default 60 minutes). */
     timeout_ms?: number;
     skill?: string;

package/dist/types/usage.d.ts

@@ -0,0 +1,16 @@
+/** Per-model token/cost breakdown, as computed by the backend SDK itself. */
+export type ModelUsageBreakdown = {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+    costUsd: number;
+};
+/** Accumulated LLM usage/cost for one stage attempt, across every turn/call it made. */
+export type StageUsage = {
+    costUsd: number;
+    models: Record<string, ModelUsageBreakdown>;
+};
+/** Merge one model's usage from a single call into an accumulator, in place. */
+export declare function addModelUsage(usage: StageUsage, model: string, delta: Partial<ModelUsageBreakdown>): void;
+export declare function emptyStageUsage(): StageUsage;

package/dist/types/usage.js

@@ -0,0 +1,24 @@
+function emptyBreakdown() {
+    return {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadInputTokens: 0,
+        cacheCreationInputTokens: 0,
+        costUsd: 0,
+    };
+}
+/** Merge one model's usage from a single call into an accumulator, in place. */
+export function addModelUsage(usage, model, delta) {
+    const current = usage.models[model] ?? emptyBreakdown();
+    usage.models[model] = {
+        inputTokens: current.inputTokens + (delta.inputTokens ?? 0),
+        outputTokens: current.outputTokens + (delta.outputTokens ?? 0),
+        cacheReadInputTokens: current.cacheReadInputTokens + (delta.cacheReadInputTokens ?? 0),
+        cacheCreationInputTokens: current.cacheCreationInputTokens + (delta.cacheCreationInputTokens ?? 0),
+        costUsd: current.costUsd + (delta.costUsd ?? 0),
+    };
+    usage.costUsd += delta.costUsd ?? 0;
+}
+export function emptyStageUsage() {
+    return { costUsd: 0, models: {} };
+}