@vauban-org/agent-sdk 0.16.0

package/dist/economy/circuit-breaker.js

@@ -0,0 +1,104 @@
+/**
+ * Fleet-level cost circuit breaker.
+ * Pauses all new cycles when rolling spend exceeds threshold.
+ * @public
+ */
+const DEFAULT_CONFIG = {
+    thresholdUsd: 10.0,
+    windowMs: 3_600_000,
+    cooldownMs: 300_000,
+};
+export class FleetCircuitBreaker {
+    cfg;
+    _state = "closed";
+    _openedAt;
+    _halfOpenConsumed = false;
+    _window = [];
+    _now;
+    constructor(config, _now = Date.now) {
+        this.cfg = { ...DEFAULT_CONFIG, ...config };
+        this._now = _now;
+    }
+    /** Returns true if a new cycle should be ALLOWED. False = circuit open. */
+    canProceed() {
+        this._evict();
+        const now = this._now();
+        if (this._state === "open") {
+            if (this._openedAt !== undefined && now - this._openedAt >= this.cfg.cooldownMs) {
+                this._state = "half-open";
+                this._halfOpenConsumed = false;
+            }
+            else {
+                return false;
+            }
+        }
+        if (this._state === "half-open") {
+            if (this._halfOpenConsumed) {
+                return false;
+            }
+            this._halfOpenConsumed = true;
+            return true;
+        }
+        // closed: check threshold
+        return this._windowSpend() <= this.cfg.thresholdUsd;
+    }
+    /** Record a cycle's cost. May trip the breaker. */
+    recordCost(costUsd) {
+        const now = this._now();
+        this._window.push({ ts: now, costUsd });
+        this._evict();
+        if (this._state === "closed") {
+            if (this._windowSpend() > this.cfg.thresholdUsd) {
+                this._trip(now);
+            }
+        }
+        else if (this._state === "half-open") {
+            // Probe completed — evaluate
+            const spend = this._windowSpend();
+            if (spend > this.cfg.thresholdUsd) {
+                this._trip(now);
+            }
+            else {
+                // probe succeeded
+                this._state = "closed";
+                this._openedAt = undefined;
+                this._halfOpenConsumed = false;
+            }
+        }
+        // If open: record but don't change state
+    }
+    /** Current state. */
+    get state() {
+        return this._state;
+    }
+    /** Manually reset (e.g. after operator review). */
+    reset() {
+        this._state = "closed";
+        this._openedAt = undefined;
+        this._halfOpenConsumed = false;
+        this._window = [];
+    }
+    /** Total spend in current window. */
+    get windowSpend() {
+        this._evict();
+        return this._windowSpend();
+    }
+    // ── private helpers ────────────────────────────────────────────────────────
+    _evict() {
+        const cutoff = this._now() - this.cfg.windowMs;
+        let i = 0;
+        while (i < this._window.length && this._window[i].ts < cutoff)
+            i++;
+        if (i > 0)
+            this._window.splice(0, i);
+    }
+    _windowSpend() {
+        return this._window.reduce((sum, e) => sum + e.costUsd, 0);
+    }
+    _trip(now) {
+        this._state = "open";
+        this._openedAt = now;
+        this._halfOpenConsumed = false;
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/economy/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../../src/economy/circuit-breaker.ts"],"names":[],"mappings":"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"}

package/dist/economy/economy-router.d.ts

@@ -0,0 +1,103 @@
+/**
+ * economy/economy-router — High-level EconomyRouter with tier catalog + circuit breaker.
+ *
+ * Promoted from forge/src/agents/shared/economy/forge-economy.ts (inline logic)
+ * to a reusable SDK module.
+ *
+ * Design goals:
+ *   - Tier catalog is data-driven (injected via EconomyRouterOpts.tiers)
+ *   - Circuit breaker triggers on $/h threshold (configurable, default $10)
+ *   - Cost recording with optional EventBusPort publish `cc.cost.recorded`
+ *   - Multi-tenant isolation via forTenant()
+ *
+ * @public
+ */
+import type { EventBusPort } from "../ports/event-bus.js";
+export interface ProviderTier {
+    name: "free" | "cheap" | "mid" | "premium";
+    costPerInputToken: number;
+    costPerOutputToken: number;
+    qualityScore: number;
+}
+export interface EconomyRouterOpts {
+    tiers: ProviderTier[];
+    hourlyBudgetUsd: number;
+    monthlyBudgetUsd: number;
+    defaultTier: ProviderTier["name"];
+    /** Called when the circuit breaker opens. */
+    onCircuitBreak?: (reason: string) => void;
+    /** Optional event bus for publishing cc.cost.recorded events. */
+    eventBus?: EventBusPort;
+    /** Rolling window for hourly budget. Default: 3_600_000ms (1h). */
+    windowMs?: number;
+    /** Monthly window. Default: 30 * 24 * 3_600_000ms. */
+    monthlyWindowMs?: number;
+    /** Injected clock for testability. Default: Date.now. */
+    _now?: () => number;
+    /** Tenant identifier (set by forTenant). */
+    _tenantId?: string;
+}
+export interface CostEntry {
+    agentId: string;
+    costUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    ts: number;
+}
+export declare class EconomyRouter {
+    private readonly _tiers;
+    private readonly _opts;
+    private readonly _hourlyWindowMs;
+    private readonly _monthlyWindowMs;
+    private readonly _now;
+    private readonly _history;
+    private _circuitOpen;
+    private _circuitOpenedAt;
+    /** Cooldown before circuit can auto-reset. 5 minutes. */
+    private static readonly COOLDOWN_MS;
+    constructor(opts: EconomyRouterOpts);
+    /**
+     * Select the most appropriate tier for a given complexity (0-1 scale).
+     * Falls back to defaultTier if the mapped tier is not in the catalog.
+     */
+    selectTier(complexity: number, _agentId?: string): ProviderTier;
+    /**
+     * Record a completed cycle's cost. Publishes cc.cost.recorded if an
+     * EventBusPort is provided.
+     */
+    recordCycle(agentId: string, costUsd: number, tokens: {
+        input: number;
+        output: number;
+    }): void;
+    /**
+     * Total cost in the rolling hourly window.
+     */
+    hourlySpend(): number;
+    /**
+     * Total cost in the rolling monthly window.
+     */
+    monthlySpend(): number;
+    /**
+     * Check whether a new cycle may proceed given estimated cost.
+     *
+     * Returns `{ ok: false, reason }` if:
+     *   - Circuit breaker is open
+     *   - Estimated cost would push hourly spend over budget
+     *   - Estimated cost would push monthly spend over budget
+     */
+    canProceed(estimatedCostUsd: number): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    /**
+     * Create a scoped router for a specific tenant.
+     *
+     * The scoped router shares the same tier catalog and configuration
+     * but maintains isolated spend history and circuit breaker state.
+     */
+    forTenant(tenantId: string): EconomyRouter;
+    private _defaultTier;
+}
+//# sourceMappingURL=economy-router.d.ts.map

package/dist/economy/economy-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"economy-router.d.ts","sourceRoot":"","sources":["../../src/economy/economy-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAI1D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;IAC3C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAClC,6CAA6C;IAC7C,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,iEAAiE;IACjE,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,MAAM,CAAC;IACpB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;CACZ;AAiBD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,yDAAyD;IACzD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAW;gBAElC,IAAI,EAAE,iBAAiB;IAQnC;;;OAGG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY;IAK/D;;;OAGG;IACH,WAAW,CACT,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GACxC,IAAI;IA6CP;;OAEG;IACH,WAAW,IAAI,MAAM;IAOrB;;OAEG;IACH,YAAY,IAAI,MAAM;IAOtB;;;;;;;OAOG;IACH,UAAU,CACR,gBAAgB,EAAE,MAAM,GACvB;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAoC/C;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa;IAW1C,OAAO,CAAC,YAAY;CAQrB"}

package/dist/economy/economy-router.js

@@ -0,0 +1,176 @@
+/**
+ * economy/economy-router — High-level EconomyRouter with tier catalog + circuit breaker.
+ *
+ * Promoted from forge/src/agents/shared/economy/forge-economy.ts (inline logic)
+ * to a reusable SDK module.
+ *
+ * Design goals:
+ *   - Tier catalog is data-driven (injected via EconomyRouterOpts.tiers)
+ *   - Circuit breaker triggers on $/h threshold (configurable, default $10)
+ *   - Cost recording with optional EventBusPort publish `cc.cost.recorded`
+ *   - Multi-tenant isolation via forTenant()
+ *
+ * @public
+ */
+// ─── Complexity → tier selection ──────────────────────────────────────────────
+/**
+ * Map a 0-1 complexity score to a tier name.
+ * 0.0-0.25 → free, 0.25-0.5 → cheap, 0.5-0.75 → mid, 0.75-1.0 → premium
+ */
+function complexityToTierName(complexity) {
+    if (complexity < 0.25)
+        return "free";
+    if (complexity < 0.5)
+        return "cheap";
+    if (complexity < 0.75)
+        return "mid";
+    return "premium";
+}
+// ─── EconomyRouter ────────────────────────────────────────────────────────────
+export class EconomyRouter {
+    _tiers;
+    _opts;
+    _hourlyWindowMs;
+    _monthlyWindowMs;
+    _now;
+    _history = [];
+    _circuitOpen = false;
+    _circuitOpenedAt;
+    /** Cooldown before circuit can auto-reset. 5 minutes. */
+    static COOLDOWN_MS = 300_000;
+    constructor(opts) {
+        this._opts = opts;
+        this._tiers = new Map(opts.tiers.map((t) => [t.name, t]));
+        this._hourlyWindowMs = opts.windowMs ?? 3_600_000;
+        this._monthlyWindowMs = opts.monthlyWindowMs ?? 30 * 24 * 3_600_000;
+        this._now = opts._now ?? (() => Date.now());
+    }
+    /**
+     * Select the most appropriate tier for a given complexity (0-1 scale).
+     * Falls back to defaultTier if the mapped tier is not in the catalog.
+     */
+    selectTier(complexity, _agentId) {
+        const preferred = complexityToTierName(complexity);
+        return this._tiers.get(preferred) ?? this._defaultTier();
+    }
+    /**
+     * Record a completed cycle's cost. Publishes cc.cost.recorded if an
+     * EventBusPort is provided.
+     */
+    recordCycle(agentId, costUsd, tokens) {
+        const now = this._now();
+        this._history.push({
+            agentId,
+            costUsd,
+            inputTokens: tokens.input,
+            outputTokens: tokens.output,
+            ts: now,
+        });
+        // Check circuit breaker
+        if (!this._circuitOpen) {
+            if (this.hourlySpend() > this._opts.hourlyBudgetUsd) {
+                this._circuitOpen = true;
+                this._circuitOpenedAt = now;
+                const reason = `hourly budget exceeded: ${this.hourlySpend().toFixed(4)} USD > ${this._opts.hourlyBudgetUsd} USD`;
+                this._opts.onCircuitBreak?.(reason);
+            }
+        }
+        // Publish event if EventBusPort provided
+        if (this._opts.eventBus !== undefined) {
+            const tenantId = this._opts._tenantId;
+            void this._opts.eventBus.publish({
+                id: `cc-cost-${now}-${agentId}`,
+                specversion: "1.0",
+                source: "cc",
+                type: "cc.cost.recorded",
+                time: new Date(now).toISOString(),
+                datacontenttype: "application/json",
+                data: {
+                    agentId,
+                    costUsd,
+                    tokens,
+                    ...(tenantId !== undefined ? { tenantId } : {}),
+                },
+            }, "cc.cost");
+        }
+    }
+    /**
+     * Total cost in the rolling hourly window.
+     */
+    hourlySpend() {
+        const cutoff = this._now() - this._hourlyWindowMs;
+        return this._history
+            .filter((e) => e.ts >= cutoff)
+            .reduce((sum, e) => sum + e.costUsd, 0);
+    }
+    /**
+     * Total cost in the rolling monthly window.
+     */
+    monthlySpend() {
+        const cutoff = this._now() - this._monthlyWindowMs;
+        return this._history
+            .filter((e) => e.ts >= cutoff)
+            .reduce((sum, e) => sum + e.costUsd, 0);
+    }
+    /**
+     * Check whether a new cycle may proceed given estimated cost.
+     *
+     * Returns `{ ok: false, reason }` if:
+     *   - Circuit breaker is open
+     *   - Estimated cost would push hourly spend over budget
+     *   - Estimated cost would push monthly spend over budget
+     */
+    canProceed(estimatedCostUsd) {
+        // Auto-reset circuit breaker after cooldown
+        if (this._circuitOpen && this._circuitOpenedAt !== undefined) {
+            if (this._now() - this._circuitOpenedAt >= EconomyRouter.COOLDOWN_MS) {
+                this._circuitOpen = false;
+                this._circuitOpenedAt = undefined;
+            }
+        }
+        if (this._circuitOpen) {
+            return { ok: false, reason: "circuit-breaker-open" };
+        }
+        const projectedHourly = this.hourlySpend() + estimatedCostUsd;
+        if (projectedHourly > this._opts.hourlyBudgetUsd) {
+            return {
+                ok: false,
+                reason: `hourly budget would be exceeded: ${projectedHourly.toFixed(4)} > ${this._opts.hourlyBudgetUsd} USD`,
+            };
+        }
+        const projectedMonthly = this.monthlySpend() + estimatedCostUsd;
+        if (projectedMonthly > this._opts.monthlyBudgetUsd) {
+            return {
+                ok: false,
+                reason: `monthly budget would be exceeded: ${projectedMonthly.toFixed(4)} > ${this._opts.monthlyBudgetUsd} USD`,
+            };
+        }
+        return { ok: true };
+    }
+    /**
+     * Create a scoped router for a specific tenant.
+     *
+     * The scoped router shares the same tier catalog and configuration
+     * but maintains isolated spend history and circuit breaker state.
+     */
+    forTenant(tenantId) {
+        return new EconomyRouter({
+            ...this._opts,
+            _tenantId: tenantId,
+            // Reset history and circuit state for the new tenant scope
+            _now: this._now,
+        });
+    }
+    // ─── Private helpers ───────────────────────────────────────────────────────
+    _defaultTier() {
+        const t = this._tiers.get(this._opts.defaultTier);
+        if (t !== undefined)
+            return t;
+        // Absolute fallback: first tier in catalog
+        const first = this._opts.tiers[0];
+        if (first !== undefined)
+            return first;
+        throw new Error("EconomyRouter: no tiers configured");
+    }
+}
+//# sourceMappingURL=economy-router.js.map

package/dist/economy/economy-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"economy-router.js","sourceRoot":"","sources":["../../src/economy/economy-router.ts"],"names":[],"mappings":"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"}

package/dist/economy/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * economy — Model tier policy + outcome cost tracking.
+ *
+ * Public exports for the economy sub-module.
+ */
+export type { ModelTier, TierPolicy } from "./tier-policy.js";
+export { DefaultTierPolicy, lookupTier } from "./tier-policy.js";
+export type { OutcomeHook, CycleCost } from "./outcome-tracker.js";
+export { OutcomeTracker } from "./outcome-tracker.js";
+export type { EconomyMode, EconomyRouterConfig, RouteDecision, } from "./router.js";
+export { EconomyRouter } from "./router.js";
+export type { CircuitBreakerConfig } from "./circuit-breaker.js";
+export { FleetCircuitBreaker } from "./circuit-breaker.js";
+export type { ProviderTier, EconomyRouterOpts, CostEntry, } from "./economy-router.js";
+export { EconomyRouter as SimpleEconomyRouter } from "./economy-router.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/economy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/economy/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEjE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,YAAY,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,SAAS,GACV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,aAAa,IAAI,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/economy/index.js

@@ -0,0 +1,11 @@
+/**
+ * economy — Model tier policy + outcome cost tracking.
+ *
+ * Public exports for the economy sub-module.
+ */
+export { DefaultTierPolicy, lookupTier } from "./tier-policy.js";
+export { OutcomeTracker } from "./outcome-tracker.js";
+export { EconomyRouter } from "./router.js";
+export { FleetCircuitBreaker } from "./circuit-breaker.js";
+export { EconomyRouter as SimpleEconomyRouter } from "./economy-router.js";
+//# sourceMappingURL=index.js.map

package/dist/economy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/economy/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGjE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAOtD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAO3D,OAAO,EAAE,aAAa,IAAI,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/economy/outcome-tracker.d.ts

@@ -0,0 +1,90 @@
+/**
+ * economy/outcome-tracker — Per-cycle cost accounting, in-memory store.
+ *
+ * Closes the "agent_run.cost_usd always zero" gap (Sprint 0 v1).
+ *
+ * Design principles:
+ *   • No DB dependency — substrate is product-agnostic.
+ *   • Host wires DB persistence via OutcomeHook.
+ *   • Cost computed from TierPolicy pricing; unknown models default to 0.
+ */
+import type { TierPolicy } from "./tier-policy.js";
+export interface OutcomeHook {
+    /**
+     * Called by OutcomeTracker when flush() is invoked for a run.
+     * Consumer is responsible for DB persistence or downstream dispatch.
+     */
+    onCycleEnd(runId: string, cost: CycleCost): Promise<void>;
+}
+export interface CycleCost {
+    runId: string;
+    inputTokens: number;
+    outputTokens: number;
+    /** Computed from TierPolicy pricing. 0 when model pricing is unknown. */
+    costUsd: number;
+    /** Label of the ModelTier used (e.g. "free", "cheap", "mid", "premium"). */
+    modelTier: string;
+    durationMs: number;
+    /** Sprint C: skill that ran (if known). */
+    skillId?: string;
+    /** Sprint C: consumer-supplied outcome delta (business value). */
+    outcomeValue?: number;
+    /** Sprint D: task category for economy router lookups (e.g. "simple"|"standard"|"complex"|"reasoning"). */
+    category?: string;
+}
+/**
+ * OutcomeTracker records token usage per cycle and computes cost_usd
+ * from the injected TierPolicy.
+ *
+ * Usage:
+ *   const tracker = new OutcomeTracker(policy, hook);
+ *   const cost = tracker.record(runId, "litellm/default-fast", 1200, 300, 1800);
+ *   await tracker.flush(runId);
+ */
+export declare class OutcomeTracker {
+    private readonly _policy;
+    private readonly _hook;
+    /** In-memory store: runId → list of CycleCost records. */
+    private readonly _store;
+    constructor(policy: TierPolicy, hook?: OutcomeHook);
+    /**
+     * Record tokens used by one cycle.
+     *
+     * @param runId        - Unique run identifier.
+     * @param model        - "provider/model" string, e.g. "litellm/default-fast" or "groq/llama-3.3-70b-versatile".
+     * @param inputTokens  - Number of input tokens consumed.
+     * @param outputTokens - Number of output tokens produced.
+     * @param durationMs   - Wall-clock duration of the cycle.
+     * @param opts         - Optional: skillId for Sprint C skill attribution.
+     */
+    record(runId: string, model: string, inputTokens: number, outputTokens: number, durationMs: number, opts?: {
+        skillId?: string;
+        outcomeValue?: number;
+        category?: string;
+    }): CycleCost;
+    /**
+     * Flush all recorded cycles for a runId to the consumer hook.
+     * Noop if no hook is configured or no records exist for the runId.
+     */
+    flush(runId: string): Promise<void>;
+    /**
+     * Get all recorded costs, optionally filtered to a trailing time window.
+     *
+     * @param windowMs - If provided, only return records within the last windowMs milliseconds.
+     *                   The tracker uses the current time as the reference point and
+     *                   estimates record time by insertion order (no timestamp stored per record).
+     *                   For window filtering, use totalCostInWindow() which is time-aware.
+     */
+    getCosts(windowMs?: number): CycleCost[];
+    /**
+     * Running total cost (USD) across all recorded cycles within the time window.
+     * Default window: last 1 hour (3_600_000 ms).
+     *
+     * Uses an internal timestamped wrapper to implement accurate windowing.
+     */
+    totalCostInWindow(windowMs?: number): number;
+    /** Timestamped record store for window queries. */
+    private readonly _timestamped;
+    private _push;
+}
+//# sourceMappingURL=outcome-tracker.d.ts.map

package/dist/economy/outcome-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome-tracker.d.ts","sourceRoot":"","sources":["../../src/economy/outcome-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2GAA2G;IAC3G,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAID;;;;;;;;GAQG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;gBAElD,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,WAAW;IAKlD;;;;;;;;;OASG;IACH,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GACpE,SAAS;IA4DZ;;;OAGG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASzC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE;IAUxC;;;;;OAKG;IACH,iBAAiB,CAAC,QAAQ,GAAE,MAAkB,GAAG,MAAM;IAevD,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAGf;IAEd,OAAO,CAAC,KAAK;CAWd"}