@claudexor/budget 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 joi-lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @claudexor/budget
+
+Internal package of [Claudexor](https://github.com/razzant/claudexor) — Budget governor: pre-call lease reservation, loop detection, 3-tier circuit breaker, portfolio routing, observed quota.
+
+Published as part of the Claudexor toolchain; it follows the monorepo's
+lockstep version and has no separate semver contract. Use the `claudexor`
+CLI (or `@claudexor/cli`) as the supported entry point.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./ledger.js";
+export * from "./router.js";
+export * from "./observe.js";
+export { loadHarnessMetrics, recordHarnessMetric, metricsPath, type HarnessMetric, type HarnessMetrics } from "./metrics.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./ledger.js";
+export * from "./router.js";
+export * from "./observe.js";
+export { loadHarnessMetrics, recordHarnessMetric, metricsPath } from "./metrics.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,WAAW,EAA2C,MAAM,cAAc,CAAC"}

package/dist/ledger.d.ts

@@ -0,0 +1,82 @@
+import type { BudgetLease, BudgetObservation, Intent } from "@claudexor/schema";
+export type CircuitTier = "ok" | "soft" | "downgrade" | "hard";
+export interface BudgetLimits {
+    maxUsd?: number | null;
+}
+export interface CircuitThresholds {
+    soft: number;
+    downgrade: number;
+    hard: number;
+}
+export interface ReserveInput {
+    taskId: string;
+    attemptId?: string;
+    intent: Intent;
+    harnessId: string;
+    modelHint?: string | null;
+    maxUsd?: number | null;
+    reason?: string[];
+    /**
+     * Estimated USD the unit may spend, held against the cap until settled. Holds
+     * make concurrent in-flight units visible to `tier()` so a parallel race wave
+     * cannot blow past `max_usd` between settlements.
+     */
+    estimateUsd?: number;
+}
+export interface ReserveResult {
+    granted: boolean;
+    tier: CircuitTier;
+    lease?: BudgetLease;
+    reason?: string;
+    /** Typed denial cause (no string matching on `reason`): `hard_cap` = the
+     * breaker already tripped; `estimate_headroom` = the DD-27 wave guard —
+     * this slot's estimate does not fit, but already-granted work continues. */
+    denied?: "hard_cap" | "estimate_headroom";
+}
+/** Stable fingerprint of a prompt for loop detection. */
+export declare function promptFingerprint(prompt: string): string;
+/**
+ * Dollar-based budget ledger with pre-call reservation, prompt-fingerprint loop
+ * detection, and a 3-tier circuit breaker (soft-warn -> downgrade -> hard-kill).
+ * Sub-ledgers (children) roll their spend up to the parent.
+ */
+export declare class BudgetLedger {
+    private readonly limits;
+    private readonly thresholds;
+    private readonly parent?;
+    private readonly leases;
+    /** Outstanding USD holds for reserved-but-unsettled leases (amount-bearing). */
+    private readonly holds;
+    private readonly observations;
+    private readonly promptCounts;
+    private spendUsd;
+    constructor(limits?: BudgetLimits, thresholds?: CircuitThresholds, parent?: BudgetLedger | undefined);
+    /** Create a child sub-ledger whose spend rolls up to this one. */
+    child(limits?: BudgetLimits): BudgetLedger;
+    private outstandingHolds;
+    tier(): CircuitTier;
+    /** USD still available under the nearest cap in the ledger chain (null = uncapped). */
+    private remainingHeadroomUsd;
+    reserve(input: ReserveInput): ReserveResult;
+    /**
+     * Raise a lease's hold to the cost streamed so far (never lowers it). Call from
+     * the usage-event stream so `tier()` reflects in-flight spend mid-attempt.
+     */
+    updateHold(leaseId: string, streamedUsd: number): void;
+    private setHold;
+    private adjustRollupHold;
+    private clearHold;
+    settle(leaseId: string, actualUsd: number): void;
+    cancel(leaseId: string): void;
+    private addRollupSpend;
+    spend(): number;
+    observe(o: BudgetObservation): void;
+    observationsFor(harnessId: string): BudgetObservation[];
+    /** True if the harness is in an active cooldown (from an observed rate-limit). */
+    cooldownActive(harnessId: string, now?: number): boolean;
+    /** Observed remaining headroom (0..1) for a harness, or 1 if unknown. */
+    headroom(harnessId: string): number;
+    recordPrompt(fingerprint: string): number;
+    isLoop(fingerprint: string, threshold?: number): boolean;
+}
+//# sourceMappingURL=ledger.d.ts.map

package/dist/ledger.d.ts.map

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

package/dist/ledger.js

@@ -0,0 +1,212 @@
+import { BudgetLease as BudgetLeaseSchema } from "@claudexor/schema";
+import { newId, nowIso, sha256 } from "@claudexor/util";
+/** Stable fingerprint of a prompt for loop detection. */
+export function promptFingerprint(prompt) {
+    return sha256(prompt.trim().replace(/\s+/g, " ").toLowerCase());
+}
+/**
+ * Dollar-based budget ledger with pre-call reservation, prompt-fingerprint loop
+ * detection, and a 3-tier circuit breaker (soft-warn -> downgrade -> hard-kill).
+ * Sub-ledgers (children) roll their spend up to the parent.
+ */
+export class BudgetLedger {
+    limits;
+    thresholds;
+    parent;
+    leases = new Map();
+    /** Outstanding USD holds for reserved-but-unsettled leases (amount-bearing). */
+    holds = new Map();
+    observations = [];
+    promptCounts = new Map();
+    spendUsd = 0;
+    constructor(limits = {}, thresholds = { soft: 0.75, downgrade: 0.9, hard: 1.0 }, parent) {
+        this.limits = limits;
+        this.thresholds = thresholds;
+        this.parent = parent;
+    }
+    /** Create a child sub-ledger whose spend rolls up to this one. */
+    child(limits = {}) {
+        return new BudgetLedger(limits, this.thresholds, this);
+    }
+    outstandingHolds() {
+        let sum = 0;
+        for (const v of this.holds.values())
+            sum += v;
+        return sum;
+    }
+    tier() {
+        const cap = this.limits.maxUsd ?? null;
+        const localTier = (() => {
+            if (cap === null || cap <= 0)
+                return "ok";
+            // Settled spend + outstanding in-flight holds: a parallel wave of
+            // streaming candidates counts against the cap BEFORE settlement.
+            const ratio = (this.spendUsd + this.outstandingHolds()) / cap;
+            if (ratio >= this.thresholds.hard)
+                return "hard";
+            if (ratio >= this.thresholds.downgrade)
+                return "downgrade";
+            if (ratio >= this.thresholds.soft)
+                return "soft";
+            return "ok";
+        })();
+        const parentTier = this.parent?.tier() ?? "ok";
+        return mostSevere(localTier, parentTier);
+    }
+    /** USD still available under the nearest cap in the ledger chain (null = uncapped). */
+    remainingHeadroomUsd() {
+        const cap = this.limits.maxUsd ?? null;
+        const local = cap === null || cap <= 0 ? null : cap * this.thresholds.hard - (this.spendUsd + this.outstandingHolds());
+        const parent = this.parent?.remainingHeadroomUsd() ?? null;
+        if (local === null)
+            return parent;
+        if (parent === null)
+            return local;
+        return Math.min(local, parent);
+    }
+    reserve(input) {
+        const tier = this.tier();
+        if (tier === "hard") {
+            return { granted: false, tier, reason: "budget exhausted (hard cap reached)", denied: "hard_cap" };
+        }
+        // DD-27 wave guard: an estimate-bearing reservation must FIT UNDER the
+        // remaining headroom, or it is DENIED without recording the hold — a
+        // denied slot must never poison the tier for candidates that were already
+        // granted. `>=` on purpose: an estimate that exactly consumes headroom
+        // would trip the hard tier the instant its hold lands, cancelling every
+        // in-flight candidate with $0 real spend (the equality case is common —
+        // caps and the floor are both round nickels).
+        if (typeof input.estimateUsd === "number" && input.estimateUsd > 0) {
+            const headroom = this.remainingHeadroomUsd();
+            if (headroom !== null && input.estimateUsd >= headroom) {
+                return {
+                    granted: false,
+                    tier,
+                    reason: `insufficient headroom for estimated cost (${input.estimateUsd.toFixed(2)} USD >= ${Math.max(headroom, 0).toFixed(2)} USD remaining)`,
+                    denied: "estimate_headroom",
+                };
+            }
+        }
+        const lease = BudgetLeaseSchema.parse({
+            lease_id: newId("lease"),
+            task_id: input.taskId,
+            attempt_id: input.attemptId,
+            intent: input.intent,
+            harness_id: input.harnessId,
+            model_hint: input.modelHint ?? null,
+            max_usd: input.maxUsd ?? null,
+            reason: input.reason ?? [],
+            created_at: nowIso(),
+            state: "reserved",
+        });
+        this.leases.set(lease.lease_id, lease);
+        if (typeof input.estimateUsd === "number" && input.estimateUsd > 0) {
+            this.setHold(lease.lease_id, input.estimateUsd);
+        }
+        return { granted: true, tier, lease };
+    }
+    /**
+     * Raise a lease's hold to the cost streamed so far (never lowers it). Call from
+     * the usage-event stream so `tier()` reflects in-flight spend mid-attempt.
+     */
+    updateHold(leaseId, streamedUsd) {
+        if (!this.leases.has(leaseId))
+            return;
+        const current = this.holds.get(leaseId) ?? 0;
+        if (streamedUsd > current)
+            this.setHold(leaseId, streamedUsd);
+    }
+    setHold(leaseId, usd) {
+        const prev = this.holds.get(leaseId) ?? 0;
+        this.holds.set(leaseId, usd);
+        this.parent?.adjustRollupHold(leaseId, usd - prev);
+    }
+    adjustRollupHold(leaseId, deltaUsd) {
+        const key = `child:${leaseId}`;
+        const prev = this.holds.get(key) ?? 0;
+        const next = Math.max(0, prev + deltaUsd);
+        if (next === 0)
+            this.holds.delete(key);
+        else
+            this.holds.set(key, next);
+        this.parent?.adjustRollupHold(leaseId, deltaUsd);
+    }
+    clearHold(leaseId) {
+        const held = this.holds.get(leaseId) ?? 0;
+        this.holds.delete(leaseId);
+        if (held > 0)
+            this.parent?.adjustRollupHold(leaseId, -held);
+    }
+    settle(leaseId, actualUsd) {
+        const lease = this.leases.get(leaseId);
+        // Fail loudly: settling a lease this ledger never granted would attribute
+        // spend to nothing (a bookkeeping bug, not a runtime race).
+        if (!lease)
+            throw new Error(`cannot settle unknown lease: ${leaseId}`);
+        // Idempotent for the spend add: a duplicate settle (success path followed
+        // by a late error handler) must never double-count real spend. DECIDED
+        // TRADEOFF: this no-op can also mask a genuine double-settle bug — spend
+        // correctness wins because the duplicate-settle race is a real runtime
+        // path (terminal handler + error handler), while a masked bug still
+        // surfaces in the rollup totals a test would assert on.
+        if (lease.state !== "reserved")
+            return;
+        lease.state = "settled";
+        this.clearHold(leaseId);
+        this.spendUsd += actualUsd;
+        this.parent?.addRollupSpend(actualUsd);
+    }
+    cancel(leaseId) {
+        const lease = this.leases.get(leaseId);
+        if (lease)
+            lease.state = "cancelled";
+        this.clearHold(leaseId);
+    }
+    addRollupSpend(usd) {
+        this.spendUsd += usd;
+        this.parent?.addRollupSpend(usd);
+    }
+    spend() {
+        return this.spendUsd;
+    }
+    observe(o) {
+        this.observations.push(o);
+    }
+    observationsFor(harnessId) {
+        return this.observations.filter((o) => o.harness_id === harnessId);
+    }
+    /** True if the harness is in an active cooldown (from an observed rate-limit). */
+    cooldownActive(harnessId, now = Date.now()) {
+        return this.observationsFor(harnessId).some((o) => {
+            if (!o.cooldown_until)
+                return false;
+            const t = Date.parse(o.cooldown_until);
+            return Number.isFinite(t) && t > now;
+        });
+    }
+    /** Observed remaining headroom (0..1) for a harness, or 1 if unknown. */
+    headroom(harnessId) {
+        const used = this.observationsFor(harnessId)
+            .map((o) => o.used_percent)
+            .filter((v) => typeof v === "number");
+        if (used.length === 0)
+            return 1;
+        const maxUsed = Math.max(...used);
+        return Math.max(0, 1 - maxUsed / 100);
+    }
+    recordPrompt(fingerprint) {
+        const n = (this.promptCounts.get(fingerprint) ?? 0) + 1;
+        this.promptCounts.set(fingerprint, n);
+        return n;
+    }
+    isLoop(fingerprint, threshold = 3) {
+        return (this.promptCounts.get(fingerprint) ?? 0) >= threshold;
+    }
+}
+function severity(t) {
+    return { ok: 0, soft: 1, downgrade: 2, hard: 3 }[t];
+}
+function mostSevere(a, b) {
+    return severity(a) >= severity(b) ? a : b;
+}
+//# sourceMappingURL=ledger.js.map

package/dist/ledger.js.map

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

package/dist/metrics.d.ts

@@ -0,0 +1,14 @@
+export interface HarnessMetric {
+    avg_cost_usd: number | null;
+    avg_duration_ms: number | null;
+    samples: number;
+}
+export type HarnessMetrics = Record<string, HarnessMetric>;
+export declare function metricsPath(configDir: string): string;
+export declare function loadHarnessMetrics(configDir: string): HarnessMetrics;
+/** Record one settled attempt (EMA update; atomic tmp+rename write). */
+export declare function recordHarnessMetric(configDir: string, harnessId: string, sample: {
+    costUsd?: number | null;
+    durationMs?: number | null;
+}): void;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAM3D,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAiBpE;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC9D,IAAI,CAyBN"}

package/dist/metrics.js

@@ -0,0 +1,67 @@
+/**
+ * Harness routing metrics: per-harness rolling averages of OBSERVED
+ * attempt cost and duration, persisted under the Claudexor config dir. ONE
+ * producer (the orchestrator records after each settled attempt) and ONE
+ * consumer (pool ordering fills RouterCandidate.costPerCall/latencyMs).
+ * Evidence-based inputs only — never pricing guesses; an attempt with no
+ * observed cost records duration alone.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Exponential moving average weight for new samples (recent runs dominate). */
+const EMA_ALPHA = 0.3;
+const MAX_SAMPLES_COUNTED = 1_000_000;
+export function metricsPath(configDir) {
+    return join(configDir, "telemetry", "harness-metrics.json");
+}
+export function loadHarnessMetrics(configDir) {
+    try {
+        const raw = JSON.parse(readFileSync(metricsPath(configDir), "utf8"));
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return {};
+        const out = {};
+        for (const [id, v] of Object.entries(raw)) {
+            const m = v;
+            out[id] = {
+                avg_cost_usd: typeof m.avg_cost_usd === "number" && m.avg_cost_usd >= 0 ? m.avg_cost_usd : null,
+                avg_duration_ms: typeof m.avg_duration_ms === "number" && m.avg_duration_ms >= 0 ? m.avg_duration_ms : null,
+                samples: typeof m.samples === "number" && m.samples > 0 ? Math.min(m.samples, MAX_SAMPLES_COUNTED) : 0,
+            };
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** Record one settled attempt (EMA update; atomic tmp+rename write). */
+export function recordHarnessMetric(configDir, harnessId, sample) {
+    const all = loadHarnessMetrics(configDir);
+    const prev = all[harnessId] ?? { avg_cost_usd: null, avg_duration_ms: null, samples: 0 };
+    const ema = (old, next) => {
+        if (typeof next !== "number" || !Number.isFinite(next) || next < 0)
+            return old;
+        if (old === null)
+            return next;
+        return old * (1 - EMA_ALPHA) + next * EMA_ALPHA;
+    };
+    all[harnessId] = {
+        avg_cost_usd: ema(prev.avg_cost_usd, sample.costUsd),
+        avg_duration_ms: ema(prev.avg_duration_ms, sample.durationMs),
+        samples: Math.min(prev.samples + 1, MAX_SAMPLES_COUNTED),
+    };
+    const path = metricsPath(configDir);
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        // Unique per WRITE, not per process: two attempts settling concurrently in
+        // one daemon collide on a pid-only name (the second rename ENOENTs and
+        // silently drops the sample).
+        const tmp = `${path}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        writeFileSync(tmp, JSON.stringify(all, null, 2) + "\n");
+        renameSync(tmp, path);
+    }
+    catch {
+        /* metrics are advisory routing inputs — never fail a run over them */
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

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

package/dist/observe.d.ts

@@ -0,0 +1,16 @@
+import type { BudgetObservation, HarnessEvent } from "@claudexor/schema";
+/**
+ * Project an observed budget/quota signal from a TYPED harness event. The budget
+ * layer makes NO governance decisions by regex over model/CLI prose: rate-limit
+ * detection lives in the adapter parse layer (where native-output translation is
+ * legitimate) and arrives here as the typed `HarnessEvent.rate_limit` field.
+ * Subscription balancing remains honest "observed best-effort", never exact-claimed.
+ */
+/**
+ * ONE event can carry SEVERAL budget signals (a codex usage event carries
+ * both an estimated cost AND its rollout quota record) — returning a single
+ * observation dropped the quota for exactly the real codex shape. Callers
+ * observe every entry.
+ */
+export declare function observationsFromEvent(harnessId: string, ev: HarnessEvent): BudgetObservation[];
+//# sourceMappingURL=observe.d.ts.map

package/dist/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAKzE;;;;;;GAMG;AACH;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,GAAG,iBAAiB,EAAE,CAuB9F"}

package/dist/observe.js

@@ -0,0 +1,58 @@
+import { nowIso } from "@claudexor/util";
+const DEFAULT_COOLDOWN_MS = 5 * 60 * 1000;
+/**
+ * Project an observed budget/quota signal from a TYPED harness event. The budget
+ * layer makes NO governance decisions by regex over model/CLI prose: rate-limit
+ * detection lives in the adapter parse layer (where native-output translation is
+ * legitimate) and arrives here as the typed `HarnessEvent.rate_limit` field.
+ * Subscription balancing remains honest "observed best-effort", never exact-claimed.
+ */
+/**
+ * ONE event can carry SEVERAL budget signals (a codex usage event carries
+ * both an estimated cost AND its rollout quota record) — returning a single
+ * observation dropped the quota for exactly the real codex shape. Callers
+ * observe every entry.
+ */
+export function observationsFromEvent(harnessId, ev) {
+    const out = [];
+    if (ev.type === "usage" && typeof ev.usage?.cost_usd === "number" && ev.usage.cost_usd > 0) {
+        // Token-derived costs (e.g. codex) are honest estimates -> "observed"; only
+        // natively-reported costs (e.g. claude) are "exact".
+        const quality = ev.usage.estimated ? "observed" : "exact";
+        out.push({ harness_id: harnessId, ts: nowIso(), quality, kind: "spend", usd: ev.usage.cost_usd });
+    }
+    if (ev.quota) {
+        // The CLI's own machine-readable window record (codex rollout
+        // token_count.rate_limits) -> "native" quality used_percent observation.
+        out.push({
+            harness_id: harnessId,
+            ts: nowIso(),
+            quality: "native",
+            kind: "used_percent",
+            used_percent: ev.quota.used_percent,
+            resets_at: ev.quota.resets_at ?? null,
+        });
+    }
+    const single = singleObservationFromEvent(harnessId, ev);
+    if (single)
+        out.push(single);
+    return out;
+}
+function singleObservationFromEvent(harnessId, ev) {
+    if (ev.rate_limit) {
+        const resets = ev.rate_limit.resets_at ?? null;
+        const delay = ev.rate_limit.retry_delay_ms ?? null;
+        const cooldownUntil = resets ?? new Date(Date.now() + (typeof delay === "number" && delay > 0 ? delay : DEFAULT_COOLDOWN_MS)).toISOString();
+        return {
+            harness_id: harnessId,
+            ts: nowIso(),
+            quality: "observed",
+            kind: "rate_limited",
+            resets_at: resets,
+            cooldown_until: cooldownUntil,
+            detail: ev.error ?? undefined,
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=observe.js.map

package/dist/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAE1C;;;;;;GAMG;AACH;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAiB,EAAE,EAAgB;IACvE,MAAM,GAAG,GAAwB,EAAE,CAAC;IACpC,IAAI,EAAE,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,QAAQ,IAAI,EAAE,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QAC3F,4EAA4E;QAC5E,qDAAqD;QACrD,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC;QAC1D,GAAG,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IACpG,CAAC;IACD,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,8DAA8D;QAC9D,yEAAyE;QACzE,GAAG,CAAC,IAAI,CAAC;YACP,UAAU,EAAE,SAAS;YACrB,EAAE,EAAE,MAAM,EAAE;YACZ,OAAO,EAAE,QAAQ;YACjB,IAAI,EAAE,cAAc;YACpB,YAAY,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY;YACnC,SAAS,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,IAAI,IAAI;SACtC,CAAC,CAAC;IACL,CAAC;IACD,MAAM,MAAM,GAAG,0BAA0B,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACzD,IAAI,MAAM;QAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7B,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,0BAA0B,CAAC,SAAiB,EAAE,EAAgB;IACrE,IAAI,EAAE,CAAC,UAAU,EAAE,CAAC;QAClB,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,SAAS,IAAI,IAAI,CAAC;QAC/C,MAAM,KAAK,GAAG,EAAE,CAAC,UAAU,CAAC,cAAc,IAAI,IAAI,CAAC;QACnD,MAAM,aAAa,GACjB,MAAM,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACxH,OAAO;YACL,UAAU,EAAE,SAAS;YACrB,EAAE,EAAE,MAAM,EAAE;YACZ,OAAO,EAAE,UAAU;YACnB,IAAI,EAAE,cAAc;YACpB,SAAS,EAAE,MAAM;YACjB,cAAc,EAAE,aAAa;YAC7B,MAAM,EAAE,EAAE,CAAC,KAAK,IAAI,SAAS;SAC9B,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/router.d.ts

@@ -0,0 +1,22 @@
+import type { Portfolio, ProviderFamily } from "@claudexor/schema";
+import type { BudgetLedger } from "./ledger.js";
+export interface RouterCandidate {
+    harnessId: string;
+    providerFamily: ProviderFamily;
+    available: boolean;
+    authMode?: "local_session" | "api_key" | "unknown";
+    /** 0..1 expected quality for the target intent. */
+    qualityForIntent?: number;
+    costPerCall?: number;
+    latencyMs?: number;
+}
+export interface RouteContext {
+    portfolio: Portfolio;
+    ledger: BudgetLedger;
+    /** Provider families already used (penalized, to encourage cross-family diversity). */
+    diversityAgainst?: ProviderFamily[];
+}
+export declare function routeUtility(c: RouterCandidate, ctx: RouteContext): number;
+/** Choose the highest-utility available harness, or null if none are usable. */
+export declare function selectHarness(candidates: RouterCandidate[], ctx: RouteContext): RouterCandidate | null;
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,cAAc,CAAC;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,eAAe,GAAG,SAAS,GAAG,SAAS,CAAC;IACnD,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,YAAY,CAAC;IACrB,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,cAAc,EAAE,CAAC;CACrC;AA2BD,wBAAgB,YAAY,CAAC,CAAC,EAAE,eAAe,EAAE,GAAG,EAAE,YAAY,GAAG,MAAM,CAkB1E;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,UAAU,EAAE,eAAe,EAAE,EAAE,GAAG,EAAE,YAAY,GAAG,eAAe,GAAG,IAAI,CAWtG"}

package/dist/router.js

@@ -0,0 +1,48 @@
+function weights(p) {
+    switch (p) {
+        case "cheapest":
+            return { quality: 0.5, cost: 2.0, latency: 1.0, preferSubscription: 1, preferApi: 1 };
+        case "strongest":
+            return { quality: 2.0, cost: 0.2, latency: 0.5, preferSubscription: 1, preferApi: 1 };
+        case "burn":
+            return { quality: 2.0, cost: 0.0, latency: 0.2, preferSubscription: 1, preferApi: 1 };
+        case "subscription-first":
+            return { quality: 1.0, cost: 0.5, latency: 0.5, preferSubscription: 1.6, preferApi: 0.6 };
+        case "api-overflow":
+            return { quality: 1.0, cost: 0.8, latency: 0.5, preferSubscription: 0.6, preferApi: 1.6 };
+        default:
+            return { quality: 1.0, cost: 0.7, latency: 0.5, preferSubscription: 1.1, preferApi: 1.0 };
+    }
+}
+export function routeUtility(c, ctx) {
+    if (!c.available || ctx.ledger.cooldownActive(c.harnessId))
+        return 0;
+    const w = weights(ctx.portfolio);
+    const quality = (c.qualityForIntent ?? 0.5) ** w.quality;
+    const headroom = ctx.ledger.headroom(c.harnessId);
+    const diversity = ctx.diversityAgainst?.includes(c.providerFamily) ? 0.5 : 1;
+    const authPref = c.authMode === "local_session" ? w.preferSubscription : c.authMode === "api_key" ? w.preferApi : 1;
+    const conserve = (ctx.portfolio === "conserve-claude" && c.providerFamily === "anthropic") ||
+        (ctx.portfolio === "conserve-codex" && c.providerFamily === "openai")
+        ? 0.4
+        : 1;
+    const cost = Math.max(0.0001, c.costPerCall ?? 0.01);
+    const latency = Math.max(0.1, (c.latencyMs ?? 1000) / 1000);
+    const costFactor = cost ** w.cost;
+    const latencyFactor = latency ** w.latency;
+    return (quality * headroom * diversity * authPref * conserve) / (costFactor * latencyFactor);
+}
+/** Choose the highest-utility available harness, or null if none are usable. */
+export function selectHarness(candidates, ctx) {
+    let best = null;
+    let bestU = 0;
+    for (const c of candidates) {
+        const u = routeUtility(c, ctx);
+        if (u > bestU) {
+            bestU = u;
+            best = c;
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

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

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@claudexor/budget",
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Budget governor: pre-call lease reservation, loop detection, 3-tier circuit breaker, portfolio routing, observed quota.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@claudexor/schema": "1.0.0",
+    "@claudexor/util": "1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/razzant/claudexor.git",
+    "directory": "packages/budget"
+  },
+  "homepage": "https://github.com/razzant/claudexor#readme",
+  "bugs": {
+    "url": "https://github.com/razzant/claudexor/issues"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}