feat(costs): add billing, quota, and budget control plane

packages/adapter-utils/src/billing.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { inferOpenAiCompatibleBiller } from "./billing.js";
+
+describe("inferOpenAiCompatibleBiller", () => {
+  it("returns openrouter when OPENROUTER_API_KEY is present", () => {
+    expect(
+      inferOpenAiCompatibleBiller({ OPENROUTER_API_KEY: "sk-or-123" } as NodeJS.ProcessEnv, "openai"),
+    ).toBe("openrouter");
+  });
+
+  it("returns openrouter when OPENAI_BASE_URL points at OpenRouter", () => {
+    expect(
+      inferOpenAiCompatibleBiller(
+        { OPENAI_BASE_URL: "https://openrouter.ai/api/v1" } as NodeJS.ProcessEnv,
+        "openai",
+      ),
+    ).toBe("openrouter");
+  });
+
+  it("returns fallback when no OpenRouter markers are present", () => {
+    expect(
+      inferOpenAiCompatibleBiller(
+        { OPENAI_BASE_URL: "https://api.openai.com/v1" } as NodeJS.ProcessEnv,
+        "openai",
+      ),
+    ).toBe("openai");
+  });
+});

packages/adapter-utils/src/billing.ts

@@ -0,0 +1,20 @@
+function readEnv(env: NodeJS.ProcessEnv, key: string): string | null {
+  const value = env[key];
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+export function inferOpenAiCompatibleBiller(
+  env: NodeJS.ProcessEnv,
+  fallback: string | null = "openai",
+): string | null {
+  const explicitOpenRouterKey = readEnv(env, "OPENROUTER_API_KEY");
+  if (explicitOpenRouterKey) return "openrouter";
+
+  const baseUrl =
+    readEnv(env, "OPENAI_BASE_URL") ??
+    readEnv(env, "OPENAI_API_BASE") ??
+    readEnv(env, "OPENAI_API_BASE_URL");
+  if (baseUrl && /openrouter\.ai/i.test(baseUrl)) return "openrouter";
+
+  return fallback;
+}

packages/adapter-utils/src/index.ts

@@ -30,3 +30,4 @@ export {
   redactHomePathUserSegmentsInValue,
   redactTranscriptEntryPaths,
 } from "./log-redaction.js";
+export { inferOpenAiCompatibleBiller } from "./billing.js";

packages/adapter-utils/src/types.ts

@@ -30,7 +30,15 @@ export interface UsageSummary {
   cachedInputTokens?: number;
 }
 
-export type AdapterBillingType = "api" | "subscription" | "unknown";
+export type AdapterBillingType =
+  | "api"
+  | "subscription"
+  | "metered_api"
+  | "subscription_included"
+  | "subscription_overage"
+  | "credits"
+  | "fixed"
+  | "unknown";
 
 export interface AdapterRuntimeServiceReport {
   id?: string | null;
@@ -68,6 +76,7 @@ export interface AdapterExecutionResult {
   sessionParams?: Record<string, unknown> | null;
   sessionDisplayId?: string | null;
   provider?: string | null;
+  biller?: string | null;
   model?: string | null;
   billingType?: AdapterBillingType | null;
   costUsd?: number | null;
@@ -185,12 +194,16 @@ export interface QuotaWindow {
   resetsAt: string | null;
   /** free-form value label for credit-style windows, e.g. "$4.20 remaining" */
   valueLabel: string | null;
+  /** optional supporting text, e.g. reset details or provider-specific notes */
+  detail?: string | null;
 }
 
 /** result for one provider from getQuotaWindows() */
 export interface ProviderQuotaResult {
   /** provider slug, e.g. "anthropic", "openai" */
   provider: string;
+  /** source label when the provider reports where the quota data came from */
+  source?: string | null;
   /** true when the fetch succeeded and windows is populated */
   ok: boolean;
   /** error message when ok is false */