stageflow 0.13.0 → 0.16.0

package/dist/envelope/payloadSchema.js

@@ -1,6 +1,49 @@
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { EnvelopeError } from "../types/envelope.js";
+export class UnresolvedSchemaRefError extends Error {
+    ref;
+    constructor(path, ref) {
+        super(`${path}: unresolved $ref "${ref}"`);
+        this.name = "UnresolvedSchemaRefError";
+        this.ref = ref;
+    }
+}
+const SCHEMA_REF_PREFIX = "#/schemas/";
+function readSchemaRefName(ref, path) {
+    if (typeof ref !== "string" || !ref.startsWith(SCHEMA_REF_PREFIX)) {
+        throw new Error(`${path}: $ref must be a JSON Pointer of the form #/schemas/<name>`);
+    }
+    const name = ref.slice(SCHEMA_REF_PREFIX.length);
+    if (!name || name.includes("/")) {
+        throw new Error(`${path}: $ref must be a JSON Pointer of the form #/schemas/<name>`);
+    }
+    return name;
+}
+function derefSchemaNode(node, path, ctx) {
+    if (node === null || typeof node !== "object" || Array.isArray(node)) {
+        throw new Error(`${path}: schema must be an object`);
+    }
+    const schema = node;
+    if (schema.$ref === undefined) {
+        return { schema, stack: ctx.stack };
+    }
+    const name = readSchemaRefName(schema.$ref, path);
+    if (ctx.stack.includes(name)) {
+        const cycle = [...ctx.stack, name]
+            .map((item) => `${SCHEMA_REF_PREFIX}${item}`)
+            .join(" → ");
+        throw new Error(`${path}: $ref cycle involving ${cycle}`);
+    }
+    const target = ctx.schemas?.[name];
+    if (target === undefined) {
+        throw new UnresolvedSchemaRefError(path, `${SCHEMA_REF_PREFIX}${name}`);
+    }
+    return derefSchemaNode(target, path, {
+        schemas: ctx.schemas,
+        stack: [...ctx.stack, name],
+    });
+}
 function readEnum(schema, path, valueType) {
     if (schema.enum === undefined) {
         return undefined;
@@ -84,11 +127,9 @@ function stringOptions(schema, path) {
         ...(maxLength !== undefined ? { maxLength } : {}),
     };
 }
-function compileNode(node, path) {
-    if (node === null || typeof node !== "object" || Array.isArray(node)) {
-        throw new Error(`${path}: schema must be an object`);
-    }
-    const schema = node;
+function compileNode(node, path, ctx) {
+    const { schema, stack } = derefSchemaNode(node, path, ctx);
+    const childCtx = { schemas: ctx.schemas, stack };
     if (typeof schema.type !== "string") {
         throw new Error(`${path}: type is required`);
     }
@@ -138,7 +179,7 @@ function compileNode(node, path) {
                     schema.minItems < 0)) {
                 throw new Error(`${path}: minItems must be a non-negative integer when present`);
             }
-            const items = compileNode(schema.items, `${path}.items`);
+            const items = compileNode(schema.items, `${path}.items`, childCtx);
             base =
                 schema.minItems !== undefined
                     ? Type.Array(items, { minItems: schema.minItems })
@@ -164,7 +205,7 @@ function compileNode(node, path) {
             }
             const compiledProps = {};
             for (const [key, value] of Object.entries(properties)) {
-                const propSchema = compileNode(value, `${path}.properties.${key}`);
+                const propSchema = compileNode(value, `${path}.properties.${key}`, childCtx);
                 compiledProps[key] = required.has(key)
                     ? propSchema
                     : Type.Optional(propSchema);
@@ -181,28 +222,227 @@ function compileNode(node, path) {
     return nullable ? Type.Union([base, Type.Null()]) : base;
 }
 /**
- * Compile a JSON Schema subset used for stage payload_schema.
+ * Compile a JSON Schema subset for IR `payload_schema` / `clone_input_schema`
+ * (YAML: `io.output.schema` / `io.input.schema`).
  * Supported: type object/string/number/integer/boolean/array,
  * properties, required, items, additionalProperties (boolean),
  * minItems, enum, minimum, maximum. String nodes also accept
  * pattern (a JS RegExp validated with the unicode flag), minLength,
  * and maxLength (non-negative integers). Nested nodes accept
  * nullable (boolean), compiling to a union of that type with null;
- * the root object cannot be nullable. Unknown keywords are ignored.
+ * the root object cannot be nullable. `$ref` is resolved against
+ * `options.schemas` using JSON Pointer `#/schemas/<name>`. Unknown
+ * keywords other than `$ref` are ignored.
  */
-export function compilePayloadSchema(raw) {
-    if (raw !== null &&
-        typeof raw === "object" &&
-        !Array.isArray(raw) &&
-        raw.nullable === true) {
+export function compilePayloadSchema(raw, options) {
+    const ctx = { schemas: options?.schemas, stack: [] };
+    const { schema: resolved } = derefSchemaNode(raw, "payload_schema", ctx);
+    if (resolved.nullable === true) {
         throw new Error("payload_schema: root cannot be nullable");
     }
-    const compiled = compileNode(raw, "payload_schema");
+    const compiled = compileNode(raw, "payload_schema", ctx);
     if (!Type.IsObject(compiled)) {
         throw new Error("payload_schema: root type must be object");
     }
     return compiled;
 }
+function isPlainSchemaObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readRequiredKeys(schema) {
+    if (schema.required === undefined)
+        return [];
+    if (!Array.isArray(schema.required) ||
+        !schema.required.every((key) => typeof key === "string")) {
+        return [];
+    }
+    return schema.required;
+}
+function readProperties(schema) {
+    if (!isPlainSchemaObject(schema.properties))
+        return {};
+    return schema.properties;
+}
+function typesCompatible(consumerType, producerType) {
+    if (consumerType === producerType)
+        return true;
+    return consumerType === "number" && producerType === "integer";
+}
+function readEnumValues(schema) {
+    if (!Array.isArray(schema.enum) || schema.enum.length === 0)
+        return undefined;
+    return schema.enum;
+}
+function enumCompatible(consumer, producer, type) {
+    if (type !== "string" && type !== "integer")
+        return true;
+    const consumerEnum = readEnumValues(consumer);
+    const producerEnum = readEnumValues(producer);
+    if (consumerEnum === undefined)
+        return true;
+    if (producerEnum === undefined)
+        return false;
+    const allowed = new Set(consumerEnum);
+    return producerEnum.every((value) => allowed.has(value));
+}
+function patternCompatible(consumer, producer) {
+    const consumerPattern = typeof consumer.pattern === "string" ? consumer.pattern : undefined;
+    const producerPattern = typeof producer.pattern === "string" ? producer.pattern : undefined;
+    if (consumerPattern === undefined)
+        return true;
+    if (producerPattern === undefined)
+        return false;
+    return consumerPattern === producerPattern;
+}
+function numericBound(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return undefined;
+    return value;
+}
+function minBoundFits(consumerBound, producerBound) {
+    const consumer = numericBound(consumerBound);
+    if (consumer === undefined)
+        return true;
+    const producer = numericBound(producerBound);
+    if (producer === undefined)
+        return false;
+    return producer >= consumer;
+}
+function maxBoundFits(consumerBound, producerBound) {
+    const consumer = numericBound(consumerBound);
+    if (consumer === undefined)
+        return true;
+    const producer = numericBound(producerBound);
+    if (producer === undefined)
+        return false;
+    return producer <= consumer;
+}
+function isSubsetNode(consumer, producer, path, ctx) {
+    const consumerDeref = derefSchemaNode(consumer, path, ctx);
+    const producerDeref = derefSchemaNode(producer, path, ctx);
+    const consumerNode = consumerDeref.schema;
+    const producerNode = producerDeref.schema;
+    if (typeof consumerNode.type !== "string" || typeof producerNode.type !== "string") {
+        return false;
+    }
+    if (!typesCompatible(consumerNode.type, producerNode.type)) {
+        return false;
+    }
+    if (producerNode.nullable === true && consumerNode.nullable !== true) {
+        return false;
+    }
+    if (consumerNode.type === "array") {
+        if (consumerNode.items === undefined || producerNode.items === undefined) {
+            return false;
+        }
+        if (!isSubsetNode(consumerNode.items, producerNode.items, `${path}.items`, {
+            schemas: ctx.schemas,
+            stack: consumerDeref.stack,
+        })) {
+            return false;
+        }
+        return minBoundFits(consumerNode.minItems, producerNode.minItems);
+    }
+    if (consumerNode.type === "object") {
+        const consumerRequired = readRequiredKeys(consumerNode);
+        const producerRequired = new Set(readRequiredKeys(producerNode));
+        const producerProps = readProperties(producerNode);
+        const consumerProps = readProperties(consumerNode);
+        for (const key of consumerRequired) {
+            if (!(key in producerProps) || !producerRequired.has(key)) {
+                return false;
+            }
+        }
+        for (const [key, consumerProp] of Object.entries(consumerProps)) {
+            if (producerProps[key] === undefined)
+                continue;
+            if (!isSubsetNode(consumerProp, producerProps[key], `${path}.properties.${key}`, {
+                schemas: ctx.schemas,
+                stack: consumerDeref.stack,
+            })) {
+                return false;
+            }
+        }
+        if (consumerNode.additionalProperties === false) {
+            if (producerNode.additionalProperties !== false) {
+                return false;
+            }
+            for (const key of Object.keys(producerProps)) {
+                if (!(key in consumerProps)) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    if (!enumCompatible(consumerNode, producerNode, consumerNode.type)) {
+        return false;
+    }
+    if (consumerNode.type === "string") {
+        if (!patternCompatible(consumerNode, producerNode))
+            return false;
+        if (!minBoundFits(consumerNode.minLength, producerNode.minLength))
+            return false;
+        if (!maxBoundFits(consumerNode.maxLength, producerNode.maxLength))
+            return false;
+    }
+    if (consumerNode.type === "number" || consumerNode.type === "integer") {
+        if (!minBoundFits(consumerNode.minimum, producerNode.minimum))
+            return false;
+        if (!maxBoundFits(consumerNode.maximum, producerNode.maximum))
+            return false;
+    }
+    return true;
+}
+/**
+ * After `$ref` resolve, true when every success payload that satisfies the
+ * producer schema also satisfies the consumer schema (producer output
+ * assignable to consumer input). Extra producer fields are allowed unless
+ * the consumer sets `additionalProperties: false`, which also requires the
+ * producer to close extras. A number consumer accepts an integer producer;
+ * the reverse is incompatible. Producer enums must be subsets of consumer
+ * enums; a consumer enum with an unconstrained producer is incompatible.
+ * String `pattern` values must be identical when the consumer sets one.
+ * Producer `minimum`/`maximum`, `minLength`/`maxLength`, and array `minItems`
+ * must fit inside the consumer bounds (a consumer bound with an omitted
+ * producer bound is incompatible). A nullable producer is incompatible unless
+ * the consumer is also nullable.
+ */
+export function isPayloadSchemaSubset(consumer, producer, options) {
+    return isSubsetNode(consumer, producer, "payload_schema", {
+        schemas: options?.schemas,
+        stack: [],
+    });
+}
+export function expandPayloadSchemaRefs(raw, options) {
+    return expandSchemaNode(raw, "payload_schema", {
+        schemas: options?.schemas,
+        stack: [],
+    });
+}
+function expandSchemaNode(node, path, ctx) {
+    const { schema, stack } = derefSchemaNode(node, path, ctx);
+    const childCtx = { schemas: ctx.schemas, stack };
+    const clone = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === "$ref")
+            continue;
+        if (key === "properties" && isPlainSchemaObject(value)) {
+            const props = {};
+            for (const [pk, pv] of Object.entries(value)) {
+                props[pk] = expandSchemaNode(pv, `${path}.properties.${pk}`, childCtx);
+            }
+            clone.properties = props;
+            continue;
+        }
+        if (key === "items") {
+            clone.items = expandSchemaNode(value, `${path}.items`, childCtx);
+            continue;
+        }
+        clone[key] = value;
+    }
+    return clone;
+}
 function formatPayloadInstancePath(instancePath) {
     const translated = instancePath.replace(/\//g, ".").replace(/^\./, "");
     return translated ? `payload.${translated}` : "payload";
@@ -212,14 +452,20 @@ function payloadSchemaMismatchDetails(schema, payload) {
         .map((err) => `${formatPayloadInstancePath(err.instancePath)} ${err.message}`)
         .join("; ");
 }
-export function assertEnvelopePayload(envelope, payloadSchema) {
+export function payloadInstanceMismatch(instance, payloadSchema, options) {
+    const schema = compilePayloadSchema(payloadSchema, options);
+    if (Value.Check(schema, instance))
+        return undefined;
+    return payloadSchemaMismatchDetails(schema, instance);
+}
+export function assertEnvelopePayload(envelope, payloadSchema, options) {
     if (payloadSchema === undefined) {
         return;
     }
     if (envelope.status !== "success") {
         return;
     }
-    const schema = compilePayloadSchema(payloadSchema);
+    const schema = compilePayloadSchema(payloadSchema, options);
     if (envelope.payload === undefined) {
         throw new EnvelopeError("payload is required by stage payload_schema");
     }
@@ -230,19 +476,23 @@ export function assertEnvelopePayload(envelope, payloadSchema) {
             : "payload does not match payload_schema");
     }
 }
-export function assertCloneAssignmentPayload(envelope, cloneInputSchema, successorId, itemPath = "") {
+/**
+ * Validate clone/fan-out assignment against the successor's IR
+ * `clone_input_schema` (YAML: `io.input.schema`).
+ */
+export function assertCloneAssignmentPayload(envelope, cloneInputSchema, successorId, itemPath = "", options) {
     if (envelope.status !== "success") {
         return;
     }
-    const schema = compilePayloadSchema(cloneInputSchema);
+    const schema = compilePayloadSchema(cloneInputSchema, options);
     const pathLead = itemPath ? `${itemPath}: ` : "";
     if (envelope.payload === undefined) {
-        throw new EnvelopeError(`${pathLead}clone assignment payload is required by clone_input_schema for ${successorId}`);
+        throw new EnvelopeError(`${pathLead}clone assignment payload is required by io.input.schema for ${successorId}`);
     }
     if (!Value.Check(schema, envelope.payload)) {
         const details = payloadSchemaMismatchDetails(schema, envelope.payload);
         throw new EnvelopeError(details
-            ? `${pathLead}clone assignment payload does not match clone_input_schema for ${successorId}: ${details}`
-            : `${pathLead}clone assignment payload does not match clone_input_schema for ${successorId}`);
+            ? `${pathLead}clone assignment payload does not match io.input.schema for ${successorId}: ${details}`
+            : `${pathLead}clone assignment payload does not match io.input.schema for ${successorId}`);
     }
 }

package/dist/mcp/catalogTools.js

@@ -11,6 +11,7 @@ const taskFileSchema = z.object({
     context: z.string().optional(),
     constraints: z.string().optional(),
     checkout: z.string().optional(),
+    input: z.record(z.string(), z.unknown()).optional(),
 });
 const startRunSchema = z
     .object({

package/dist/package-meta.d.ts

@@ -1,2 +1,2 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.13.0";
+export declare const PACKAGE_VERSION = "0.16.0";

package/dist/package-meta.js

@@ -1,2 +1,2 @@
 export const PACKAGE_NAME = "stageflow";
-export const PACKAGE_VERSION = "0.13.0";
+export const PACKAGE_VERSION = "0.16.0";

package/dist/runstore/pipelineDagSnapshot.js

@@ -1,6 +1,8 @@
 import { hydrateResolvedNeeds } from "../config/pipelineNeeds.js";
 import { mintCloneInstanceIds } from "./stageInstanceId.js";
 export function buildPipelineDagSnapshotFromLoaded(loaded) {
+    // Snapshot JSON keeps IR keys (`completion`, `recovery`, `clone_input_schema`).
+    // Do not rewrite these from target YAML names. Resume hydrates this shape.
     const gate_kinds = {};
     const clone_input_schema = {};
     for (const stage of loaded.stages) {

package/dist/runstore/port.d.ts

@@ -4,10 +4,12 @@ import type { StageEnvelope } from "../types/envelope.js";
 import type { FeedbackLoopConfig, ResolvedPipelineDag } from "../types/pipeline.js";
 import type { CompletionCheck } from "../types/completion.js";
 import type { StageGateKind } from "../types/stage.js";
+import type { StageUsage } from "../types/usage.js";
 export type RunStatus = "created" | "running" | "succeeded" | "failed";
 export type RunPipelineDagSnapshot = ResolvedPipelineDag & {
     stage_ids: string[];
     gate_kinds?: Record<string, StageGateKind[]>;
+    /** IR: per-stage clone assignment schema. YAML: `io.input.schema`. */
     clone_input_schema?: Record<string, unknown>;
 };
 export type StageReadiness = "blocked" | "ready" | "running" | "waiting" | "succeeded" | "failed" | "skipped";
@@ -69,6 +71,8 @@ export type StageSnapshot = {
     last_at?: string;
     pending_prompt?: AskOperatorPrompt;
     attempt_count: number;
+    /** Total $ spent on this stage across every attempt; omitted when no attempt reported usage. */
+    cost_usd?: number;
 };
 export type StageExecution = {
     run_id: string;
@@ -79,6 +83,8 @@ export type StageExecution = {
     started_at?: string;
     finished_at?: string;
     envelope: StageEnvelope | null;
+    cost_usd?: number;
+    usage?: StageUsage;
 };
 export type StageExecutionPatch = {
     status?: StageSnapshot["status"];
@@ -86,6 +92,8 @@ export type StageExecutionPatch = {
     started_at?: string;
     finished_at?: string;
     envelope?: StageEnvelope | null;
+    cost_usd?: number;
+    usage?: StageUsage;
 };
 /** The durable disposition of completion verification for one stage attempt. */
 export type VerificationOutcome = "not_run" | "passed" | "failed" | "error";
@@ -219,6 +227,7 @@ export type CompactStage = {
     status: StageSnapshot["status"];
     attempt_count: number;
     definition_id?: string;
+    cost_usd?: number;
 };
 export type RunSummary = {
     run_id: string;
@@ -245,6 +254,8 @@ export type RunSummary = {
     failed_reason?: string;
     /** The active loop, when a run is currently replaying or awaiting a decision. */
     active_feedback_loop?: FeedbackLoopRecord;
+    /** Sum of every stage's cost_usd; omitted when no stage reported usage. */
+    total_cost_usd?: number;
 };
 export type RunDetail = Omit<RunSummary, "stages"> & {
     task_yaml: string;

package/dist/runstore/runProjection.js

@@ -26,8 +26,15 @@ function compactStages(stages) {
         status: s.status,
         attempt_count: s.attempt_count,
         ...(s.definition_id !== undefined ? { definition_id: s.definition_id } : {}),
+        ...(s.cost_usd !== undefined ? { cost_usd: s.cost_usd } : {}),
     }));
 }
+function totalCostUsd(stages) {
+    const costs = stages.map((s) => s.cost_usd).filter((c) => c !== undefined);
+    if (costs.length === 0)
+        return undefined;
+    return costs.reduce((sum, c) => sum + c, 0);
+}
 function waitingSummaryFromPrompt(prompt) {
     if (!prompt)
         return "Waiting for input";
@@ -89,6 +96,7 @@ function resolveListedStatus(stages, meta, dag) {
 export function projectRunSummary(meta, stages, feedback) {
     const dag = meta.pipeline_dag;
     const waiting = waitingFieldsFromStages(stages);
+    const cost = totalCostUsd(stages);
     if (feedback?.active_feedback_loop?.state === "waiting_for_human" &&
         waiting.waiting_stage_id !== undefined &&
         waiting.waiting_kind === undefined) {
@@ -114,6 +122,7 @@ export function projectRunSummary(meta, stages, feedback) {
         ...(feedback?.active_feedback_loop !== undefined
             ? { active_feedback_loop: feedback.active_feedback_loop }
             : {}),
+        ...(cost !== undefined ? { total_cost_usd: cost } : {}),
     };
 }
 export function projectRunDetail(meta, stages, task_yaml, dagSnapshot, feedback) {

package/dist/runstore/sqlite/SqliteRunStore.js

@@ -78,6 +78,18 @@ function ensureStageExecutionVerificationOutcomeColumn(db) {
         db.exec(`ALTER TABLE stage_executions ADD COLUMN verification_outcome TEXT NOT NULL DEFAULT 'not_run'`);
     }
 }
+function ensureStageExecutionCostColumns(db) {
+    const cols = db
+        .prepare(`PRAGMA table_info(stage_executions)`)
+        .all();
+    const names = new Set(cols.map((c) => c.name));
+    if (!names.has("cost_usd")) {
+        db.exec(`ALTER TABLE stage_executions ADD COLUMN cost_usd REAL`);
+    }
+    if (!names.has("usage_json")) {
+        db.exec(`ALTER TABLE stage_executions ADD COLUMN usage_json TEXT`);
+    }
+}
 function backfillVerificationOutcomes(db) {
     db.exec(`
 UPDATE stage_executions
@@ -184,6 +196,8 @@ function executionFromRow(row) {
         envelope: row.envelope_json
             ? JSON.parse(row.envelope_json)
             : null,
+        ...(row.cost_usd != null ? { cost_usd: row.cost_usd } : {}),
+        ...(row.usage_json != null ? { usage: JSON.parse(row.usage_json) } : {}),
     };
 }
 function verificationCheckResultFromRow(row) {
@@ -292,6 +306,7 @@ export class SqliteRunStore {
         ensureRunLocatorColumns(this.db);
         ensureStageExecutionsTable(this.db);
         ensureStageExecutionVerificationOutcomeColumn(this.db);
+        ensureStageExecutionCostColumns(this.db);
         ensureStageEventsAttemptColumn(this.db);
         ensureVerificationCheckResultsTable(this.db);
         ensureFeedbackReplayStagePassEnvelopeColumn(this.db);
@@ -432,7 +447,7 @@ export class SqliteRunStore {
                 verification_outcome: "not_run",
             });
             const row = this.db
-                .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json
+                .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json, cost_usd, usage_json
            FROM stage_executions
            WHERE run_id = ? AND stage_id = ? AND attempt = ?`)
                 .get(runId, stageId, attempt);
@@ -442,7 +457,7 @@ export class SqliteRunStore {
     async listStageExecutions(runId, stageId) {
         await this.ready();
         const rows = this.db
-            .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json
+            .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json, cost_usd, usage_json
          FROM stage_executions
          WHERE run_id = ? AND stage_id = ?
          ORDER BY attempt ASC`)
@@ -452,7 +467,7 @@ export class SqliteRunStore {
     async getLatestStageExecution(runId, stageId) {
         await this.ready();
         const row = this.db
-            .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json
+            .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json, cost_usd, usage_json
          FROM stage_executions
          WHERE run_id = ? AND stage_id = ?
          ORDER BY attempt DESC
@@ -471,7 +486,7 @@ export class SqliteRunStore {
     async getStageExecution(runId, stageId, attempt) {
         await this.ready();
         const row = this.db
-            .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json
+            .prepare(`SELECT run_id, stage_id, attempt, status, verification_outcome, started_at, finished_at, envelope_json, cost_usd, usage_json
          FROM stage_executions
          WHERE run_id = ? AND stage_id = ? AND attempt = ?`)
             .get(runId, stageId, attempt);
@@ -509,6 +524,14 @@ export class SqliteRunStore {
             params.envelope_json =
                 patch.envelope != null ? JSON.stringify(patch.envelope) : null;
         }
+        if (patch.cost_usd !== undefined) {
+            sets.push("cost_usd = @cost_usd");
+            params.cost_usd = patch.cost_usd;
+        }
+        if (patch.usage !== undefined) {
+            sets.push("usage_json = @usage_json");
+            params.usage_json = JSON.stringify(patch.usage);
+        }
         if (sets.length === 0)
             return;
         const result = this.db

package/dist/runstore/sqlite/schema.d.ts

@@ -1 +1 @@
-export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS runs (\n  run_id TEXT PRIMARY KEY,\n  pipeline_id TEXT NOT NULL,\n  task_id TEXT,\n  task_yaml TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  checkout_root TEXT,\n  pipeline_dag_json TEXT,\n  git_sha TEXT,\n  ci_pr_url TEXT,\n  ci_job_url TEXT,\n  pipeline_path TEXT,\n  task_path TEXT,\n  project_root TEXT\n);\n\nCREATE TABLE IF NOT EXISTS stages (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  status TEXT,\n  summary TEXT,\n  envelope_json TEXT,\n  started_at TEXT,\n  finished_at TEXT,\n  PRIMARY KEY (run_id, stage_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS stage_events (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  at TEXT NOT NULL,\n  event TEXT NOT NULL,\n  payload_json TEXT,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_runs_status_created\n  ON runs (status, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_runs_pipeline_created\n  ON runs (pipeline_id, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_stage_events_run_stage_at\n  ON stage_events (run_id, stage_id, at);\n\nCREATE TABLE IF NOT EXISTS stage_executions (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  status TEXT NOT NULL,\n  verification_outcome TEXT NOT NULL DEFAULT 'not_run',\n  started_at TEXT,\n  finished_at TEXT,\n  envelope_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_stage_executions_run_stage\n  ON stage_executions (run_id, stage_id, attempt);\n\nCREATE TABLE IF NOT EXISTS verification_check_results (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  check_id TEXT NOT NULL,\n  check_type TEXT NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  evidence_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt, check_id),\n  FOREIGN KEY (run_id, stage_id, attempt)\n    REFERENCES stage_executions(run_id, stage_id, attempt)\n);\n\nCREATE INDEX IF NOT EXISTS idx_verification_check_results_execution\n  ON verification_check_results (run_id, stage_id, attempt, check_id);\n\nCREATE TABLE IF NOT EXISTS feedback_loops (\n  run_id TEXT NOT NULL,\n  loop_id TEXT NOT NULL,\n  source_stage_id TEXT NOT NULL,\n  source_attempt INTEGER NOT NULL,\n  policy_json TEXT NOT NULL,\n  state TEXT NOT NULL,\n  current_replay_id TEXT,\n  current_replay_number INTEGER,\n  deferred_send_back_json TEXT,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, loop_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_feedback_loops_run_state\n  ON feedback_loops (run_id, state, created_at);\n\nCREATE TABLE IF NOT EXISTS feedback_replays (\n  run_id TEXT NOT NULL,\n  replay_id TEXT NOT NULL,\n  loop_id TEXT NOT NULL,\n  source_stage_id TEXT NOT NULL,\n  source_attempt INTEGER NOT NULL,\n  target_stage_id TEXT NOT NULL,\n  replay_number INTEGER NOT NULL,\n  max_replays INTEGER NOT NULL,\n  replay_session TEXT NOT NULL,\n  route_stage_ids_json TEXT NOT NULL,\n  feedback_envelope_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, replay_id),\n  FOREIGN KEY (run_id, loop_id) REFERENCES feedback_loops(run_id, loop_id)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_feedback_replays_loop_number\n  ON feedback_replays (run_id, loop_id, replay_number);\nCREATE INDEX IF NOT EXISTS idx_feedback_replays_run_loop\n  ON feedback_replays (run_id, loop_id, created_at);\n\nCREATE TABLE IF NOT EXISTS feedback_replay_stage_passes (\n  run_id TEXT NOT NULL,\n  replay_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  stage_attempt INTEGER NOT NULL,\n  session_origin_attempt INTEGER,\n  session_mode TEXT NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  emitted_envelope_json TEXT,\n  PRIMARY KEY (run_id, replay_id, stage_id),\n  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_feedback_replay_stage_passes_replay\n  ON feedback_replay_stage_passes (run_id, replay_id, stage_id);\n\nCREATE TABLE IF NOT EXISTS fork_generations (\n  run_id TEXT NOT NULL,\n  generation_id TEXT NOT NULL,\n  replay_id TEXT,\n  fork_parent_stage_id TEXT NOT NULL,\n  generation_number INTEGER NOT NULL,\n  clone_stage_ids_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, generation_id),\n  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_fork_generations_parent_number\n  ON fork_generations (run_id, fork_parent_stage_id, generation_number);\nCREATE INDEX IF NOT EXISTS idx_fork_generations_run_replay\n  ON fork_generations (run_id, replay_id, created_at);\n";
+export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS runs (\n  run_id TEXT PRIMARY KEY,\n  pipeline_id TEXT NOT NULL,\n  task_id TEXT,\n  task_yaml TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  checkout_root TEXT,\n  pipeline_dag_json TEXT,\n  git_sha TEXT,\n  ci_pr_url TEXT,\n  ci_job_url TEXT,\n  pipeline_path TEXT,\n  task_path TEXT,\n  project_root TEXT\n);\n\nCREATE TABLE IF NOT EXISTS stages (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  status TEXT,\n  summary TEXT,\n  envelope_json TEXT,\n  started_at TEXT,\n  finished_at TEXT,\n  PRIMARY KEY (run_id, stage_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS stage_events (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  at TEXT NOT NULL,\n  event TEXT NOT NULL,\n  payload_json TEXT,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_runs_status_created\n  ON runs (status, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_runs_pipeline_created\n  ON runs (pipeline_id, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_stage_events_run_stage_at\n  ON stage_events (run_id, stage_id, at);\n\nCREATE TABLE IF NOT EXISTS stage_executions (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  status TEXT NOT NULL,\n  verification_outcome TEXT NOT NULL DEFAULT 'not_run',\n  started_at TEXT,\n  finished_at TEXT,\n  envelope_json TEXT,\n  cost_usd REAL,\n  usage_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_stage_executions_run_stage\n  ON stage_executions (run_id, stage_id, attempt);\n\nCREATE TABLE IF NOT EXISTS verification_check_results (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  check_id TEXT NOT NULL,\n  check_type TEXT NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  evidence_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt, check_id),\n  FOREIGN KEY (run_id, stage_id, attempt)\n    REFERENCES stage_executions(run_id, stage_id, attempt)\n);\n\nCREATE INDEX IF NOT EXISTS idx_verification_check_results_execution\n  ON verification_check_results (run_id, stage_id, attempt, check_id);\n\nCREATE TABLE IF NOT EXISTS feedback_loops (\n  run_id TEXT NOT NULL,\n  loop_id TEXT NOT NULL,\n  source_stage_id TEXT NOT NULL,\n  source_attempt INTEGER NOT NULL,\n  policy_json TEXT NOT NULL,\n  state TEXT NOT NULL,\n  current_replay_id TEXT,\n  current_replay_number INTEGER,\n  deferred_send_back_json TEXT,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, loop_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_feedback_loops_run_state\n  ON feedback_loops (run_id, state, created_at);\n\nCREATE TABLE IF NOT EXISTS feedback_replays (\n  run_id TEXT NOT NULL,\n  replay_id TEXT NOT NULL,\n  loop_id TEXT NOT NULL,\n  source_stage_id TEXT NOT NULL,\n  source_attempt INTEGER NOT NULL,\n  target_stage_id TEXT NOT NULL,\n  replay_number INTEGER NOT NULL,\n  max_replays INTEGER NOT NULL,\n  replay_session TEXT NOT NULL,\n  route_stage_ids_json TEXT NOT NULL,\n  feedback_envelope_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, replay_id),\n  FOREIGN KEY (run_id, loop_id) REFERENCES feedback_loops(run_id, loop_id)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_feedback_replays_loop_number\n  ON feedback_replays (run_id, loop_id, replay_number);\nCREATE INDEX IF NOT EXISTS idx_feedback_replays_run_loop\n  ON feedback_replays (run_id, loop_id, created_at);\n\nCREATE TABLE IF NOT EXISTS feedback_replay_stage_passes (\n  run_id TEXT NOT NULL,\n  replay_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  stage_attempt INTEGER NOT NULL,\n  session_origin_attempt INTEGER,\n  session_mode TEXT NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  emitted_envelope_json TEXT,\n  PRIMARY KEY (run_id, replay_id, stage_id),\n  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_feedback_replay_stage_passes_replay\n  ON feedback_replay_stage_passes (run_id, replay_id, stage_id);\n\nCREATE TABLE IF NOT EXISTS fork_generations (\n  run_id TEXT NOT NULL,\n  generation_id TEXT NOT NULL,\n  replay_id TEXT,\n  fork_parent_stage_id TEXT NOT NULL,\n  generation_number INTEGER NOT NULL,\n  clone_stage_ids_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, generation_id),\n  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_fork_generations_parent_number\n  ON fork_generations (run_id, fork_parent_stage_id, generation_number);\nCREATE INDEX IF NOT EXISTS idx_fork_generations_run_replay\n  ON fork_generations (run_id, replay_id, created_at);\n";

package/dist/runstore/sqlite/schema.js

@@ -57,6 +57,8 @@ CREATE TABLE IF NOT EXISTS stage_executions (
   started_at TEXT,
   finished_at TEXT,
   envelope_json TEXT,
+  cost_usd REAL,
+  usage_json TEXT,
   PRIMARY KEY (run_id, stage_id, attempt),
   FOREIGN KEY (run_id) REFERENCES runs(run_id)
 );

package/dist/runstore/stageExecution.d.ts

@@ -1,10 +1,13 @@
 import type { StageEnvelope } from "../types/envelope.js";
+import type { StageUsage } from "../types/usage.js";
 import type { StageLogEvent, StageSnapshot } from "./port.js";
 export type StageExecutionPatch = {
     status?: StageSnapshot["status"];
     started_at?: string;
     finished_at?: string;
     envelope?: StageEnvelope | null;
+    cost_usd?: number;
+    usage?: StageUsage;
 };
 export declare function executionStatusFromEvents(events: StageLogEvent[]): StageSnapshot["status"];
 export declare function deriveExecutionPatchFromEvent(event: StageLogEvent, current: Pick<StageSnapshot, "status"> & {

package/dist/runstore/stageExecution.js

@@ -14,9 +14,13 @@ export function deriveExecutionPatchFromEvent(event, current) {
     else if (eventName === "waiting_for_input") {
         patch.status = "waiting_for_input";
     }
-    else if (eventName === "succeeded" || eventName === "failed") {
-        patch.status = eventName;
+    else if (event.event === "succeeded" || event.event === "failed") {
+        patch.status = event.event;
         patch.finished_at = at;
+        if (event.usage) {
+            patch.cost_usd = event.usage.costUsd;
+            patch.usage = event.usage;
+        }
     }
     return patch;
 }

package/dist/runstore/stageSnapshot.js

@@ -18,11 +18,14 @@ export async function buildStageSnapshotFromStore(store, runId, stageId, workspa
     let status;
     let envelope;
     let attempt_count;
+    let cost_usd;
     if (latest !== null) {
         events = await store.listStageEvents(runId, stageId, latest.attempt);
         status = stageStatusFromEvents(events);
         envelope = await tryReadEnvelope(store, runId, stageId, latest);
         attempt_count = await store.countStageAttempts(runId, stageId);
+        const executions = await store.listStageExecutions(runId, stageId);
+        cost_usd = sumStageExecutionCost(executions);
     }
     else {
         events = await store.listStageEvents(runId, stageId);
@@ -42,5 +45,13 @@ export async function buildStageSnapshotFromStore(store, runId, stageId, workspa
         last_at,
         attempt_count,
         ...(pending ? { pending_prompt: pending } : {}),
+        ...(cost_usd !== undefined ? { cost_usd } : {}),
     };
 }
+/** Sum cost across every attempt — retries are real spend too, so a stage's total isn't just its latest attempt. */
+function sumStageExecutionCost(executions) {
+    const costs = executions.map((e) => e.cost_usd).filter((c) => c !== undefined);
+    if (costs.length === 0)
+        return undefined;
+    return costs.reduce((sum, c) => sum + c, 0);
+}