@claudexor/schema 1.0.0 → 2.0.0

package/dist/budget.js

@@ -1,22 +1,48 @@
 import { z } from "zod";
+import { BillingKnowledge, CostKnowledge } from "./auth.js";
 import { Id, Intent } from "./primitives.js";
-import { SignalQuality } from "./harness.js";
+import { EffortHint, SignalQuality } from "./harness.js";
+export const PaidBudget = z
+    .discriminatedUnion("kind", [
+    z.object({ kind: z.literal("unlimited") }).strict(),
+    z.object({ kind: z.literal("finite"), maxUsd: z.number().nonnegative() }).strict(),
+])
+    .describe("Incremental-cash budget: explicitly unlimited or a finite non-negative USD cap.");
+export const CostEvidence = z
+    .object({
+    knowledge: CostKnowledge,
+    billing: BillingKnowledge,
+    source: z.string().min(1),
+    provenance: z.array(z.string().min(1)).min(1),
+    estimatedUsd: z.number().nonnegative().nullable().default(null),
+})
+    .strict()
+    .describe("Incremental-cash cost knowledge with its source and evidence provenance.");
 export const AuthMode = z
     .enum(["local_session", "api_key", "unknown"])
     .describe("Auth mode a route runs under: a native local session, an API key, or unknown.");
-export const Portfolio = z
-    .enum([
-    "daily-rich",
-    "balanced",
-    "cheapest",
-    "strongest",
-    "burn",
-    "subscription-first",
-    "api-overflow",
-    "conserve-claude",
-    "conserve-codex",
-])
-    .describe("Budget portfolio weighting the harness router's quality/cost/latency and subscription-vs-API preferences (e.g. cheapest minimizes spend, burn maximizes quality, conserve-* deprioritizes one vendor).");
+export const RoutingGoal = z
+    .enum(["auto", "quality", "economy"])
+    .describe("Routing objective: pace expiring quota, choose the highest declared quality tier, or minimize incremental paid spend.");
+export const PaidFallback = z
+    .enum(["never", "when_unavailable", "allowed_within_cap"])
+    .describe("When a route with incremental paid spend may be used.");
+export const QualityTierRoute = z
+    .object({
+    harness: Id,
+    model: z.string().min(1),
+    effort: EffortHint,
+})
+    .strict()
+    .describe("An exact harness, model, and effort route declared by the user.");
+export const QualityTier = z
+    .array(QualityTierRoute)
+    .min(1)
+    .describe("A group of comparable exact routes at one user-declared quality level.");
+export const QualityTierSet = z
+    .record(Intent, z.array(QualityTier))
+    .default({})
+    .describe("Per-intent quality tiers ordered highest to lowest; no provider or benchmark priors are inferred.");
 /** A pre-call reservation. Created before work; settled after. Never post-hoc only. */
 export const BudgetLease = z
     .object({
@@ -25,9 +51,16 @@ export const BudgetLease = z
     attempt_id: Id.optional().describe("Attempt the lease covers, when scoped to one."),
     intent: Intent,
     harness_id: Id.describe("Harness the reservation is for."),
-    model_hint: z.string().nullable().default(null).describe("Requested model for the reserved call; null = harness default."),
-    max_usd: z.number().nullable().default(null).describe("USD cap reserved for the call; null = no cap."),
-    reason: z.array(z.string()).default([]).describe("Human-readable reasons the lease was created."),
+    model_hint: z
+        .string()
+        .nullable()
+        .default(null)
+        .describe("Requested model for the reserved call; null = harness default."),
+    cost: CostEvidence,
+    reason: z
+        .array(z.string())
+        .default([])
+        .describe("Human-readable reasons the lease was created."),
     created_at: z.string().describe("When the lease was created."),
     state: z
         .enum(["reserved", "settled", "cancelled"])
@@ -42,12 +75,22 @@ export const BudgetObservation = z
     ts: z.string().describe("When the signal was observed."),
     quality: SignalQuality,
     kind: z
-        .enum(["spend", "rate_limited", "used_percent", "cooldown", "manual"])
-        .describe("What was observed: spend, a rate-limit hit, a used-percent reading, a cooldown, or a manual entry."),
+        .enum(["spend", "rate_limited", "quota_constraint", "cooldown"])
+        .describe("What was observed: spend, a rate-limit hit, one independent quota constraint, or a cooldown."),
     usd: z.number().optional().describe("Observed spend in USD, for spend observations."),
-    used_percent: z.number().optional().describe("Consumed share of the rate window (0-100), for used_percent observations."),
-    resets_at: z.string().nullable().optional().describe("When the rate window resets, when reported."),
-    cooldown_until: z.string().nullable().optional().describe("Until when the harness is in cooldown, when set."),
+    constraint_id: z.string().optional(),
+    used_ratio: z.number().min(0).max(1).nullable().optional(),
+    window_seconds: z.number().positive().nullable().optional(),
+    resets_at: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("When the rate window resets, when reported."),
+    cooldown_until: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Until when the harness is in cooldown, when set."),
     detail: z.string().optional().describe("Redacted human-readable detail."),
 })
     .describe("An observed quota/usage signal (rate-limit error, used-percent, reset hint) recorded in the budget ledger.");

package/dist/budget.js.map

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