offrouter-core 0.0.0 → 0.2.0

package/src/router.ts

@@ -23,17 +23,18 @@ function candidateId(c: ProviderCandidate): string {
 /**
  * Rank score: higher is better.
  * Order of preference:
- * 1. Healthy subscription (active + healthy health)
- * 2. Local
- * 3. Degraded subscription (active + degraded)
- * 4. API-key
+ * 1. Healthy active subscription (status !== "near-limit")
+ * 2. Healthy near-limit subscription
+ * 3. Local
+ * 4. Degraded subscription (active + degraded)
+ * 5. API-key
  * Within same tier: lower estimatedCostUsd, then providerId, then modelId.
  */
 function rankKey(c: ProviderCandidate): [number, number, string, string] {
   let tierRank: number;
   if (c.authTier === "subscription") {
     if (c.health === "healthy") {
-      tierRank = 400;
+      tierRank = c.subscriptionStatus === "near-limit" ? 350 : 400;
     } else if (c.health === "degraded") {
       tierRank = 200;
     } else {
@@ -298,6 +299,32 @@ export function routeRequest(
     fallbackChain[0] = { ...fallbackChain[0], reason: finalFallback };
   }
 
+  // Compute near-limit warning
+  let nearLimitWarning: string | undefined;
+  if (
+    winner.authTier === "subscription" &&
+    winner.subscriptionStatus === "near-limit"
+  ) {
+    const hasHealthyAlt = sorted.some(
+      (c) =>
+        c !== winner &&
+        c.authTier === "subscription" &&
+        c.health === "healthy" &&
+        c.subscriptionStatus !== "near-limit",
+    );
+    if (!hasHealthyAlt) {
+      const acct = winner.accountId ?? winner.providerId;
+      const pct = winner.subscriptionQuotaPercentRemaining;
+      const pctText =
+        pct !== undefined ? ` (${Math.round(pct)}% remaining)` : "";
+      nearLimitWarning = `Your ${winner.providerId} subscription (${acct}) is near its limit${pctText}. Consider switching or adding another account.`;
+    }
+  }
+
+  if (nearLimitWarning) {
+    finalExplanation = `${finalExplanation} ${nearLimitWarning}`;
+  }
+
   return {
     protocolVersion: ROUTE_PROTOCOL_VERSION,
     decisionId,
@@ -307,6 +334,7 @@ export function routeRequest(
       model: winner.modelId,
       authTier: winner.authTier,
       authScope: winner.authScope,
+      accountId: winner.accountId ?? winner.providerId,
     },
     reason: finalReason,
     explanation: finalExplanation,
@@ -316,6 +344,7 @@ export function routeRequest(
     auditSummary: `route=${winner.providerId}/${winner.modelId} tier=${winner.authTier} profile=${request.harness.profile} digest=${request.task.promptDigest}`,
     blocked: false,
     needsConfiguration: false,
+    nearLimitWarning,
   };
 }
 

package/src/schemas.test.ts

@@ -8,6 +8,7 @@ import {
   ProviderHealthSchema,
   RouteDecisionSchema,
   RouteRequestSchema,
+  SelectedRouteSchema,
   SubscriptionStatusSchema,
 } from "./schemas.js";
 import { ROUTE_PROTOCOL_VERSION } from "./protocol.js";
@@ -28,6 +29,7 @@ describe("routing vocabulary schemas", () => {
   it("accepts all SubscriptionStatus values", () => {
     for (const status of [
       "active",
+      "near-limit",
       "exhausted",
       "rate-limited",
       "expired",
@@ -237,4 +239,53 @@ describe("routing schemas", () => {
       }),
     ).toThrow();
   });
+
+  describe("multi-account schema fields", () => {
+    it("accepts ProviderCandidate with accountId and subscriptionQuotaPercentRemaining", () => {
+      const candidate = ProviderCandidateSchema.parse({
+        providerId: "anthropic",
+        modelId: "sonnet",
+        authTier: "subscription",
+        authScope: "first-party",
+        subscriptionStatus: "active",
+        accountId: "anthropic-1",
+        subscriptionQuotaPercentRemaining: 15,
+        health: "healthy",
+        supportsTools: true,
+        supportsStreaming: true,
+        supportsJson: true,
+        supportsImages: false,
+      });
+      expect(candidate.accountId).toBe("anthropic-1");
+      expect(candidate.subscriptionQuotaPercentRemaining).toBe(15);
+    });
+
+    it("accepts near-limit SubscriptionStatus", () => {
+      expect(SubscriptionStatusSchema.parse("near-limit")).toBe("near-limit");
+    });
+
+    it("accepts RouteDecision with nearLimitWarning", () => {
+      const decision = RouteDecisionSchema.parse({
+        protocolVersion: "offrouter.route.v1",
+        decisionId: "dec_nl",
+        requestId: "req_nl",
+        route: { provider: "anthropic", model: "sonnet", authTier: "subscription" },
+        reason: "subscription_primary",
+        explanation: "Selected near-limit subscription.",
+        nearLimitWarning:
+          "Your anthropic subscription (anthropic-1) is near its limit (15% remaining). Consider switching or adding another account.",
+      });
+      expect(decision.nearLimitWarning).toContain("near its limit");
+    });
+
+    it("accepts SelectedRoute with accountId", () => {
+      const route = {
+        provider: "anthropic",
+        model: "sonnet",
+        authTier: "subscription",
+        accountId: "anthropic-1",
+      };
+      expect(() => SelectedRouteSchema.parse(route)).not.toThrow();
+    });
+  });
 });

package/src/schemas.ts

@@ -15,6 +15,7 @@ export const AuthScopeSchema = z.enum([
 
 export const SubscriptionStatusSchema = z.enum([
   "active",
+  "near-limit",
   "exhausted",
   "rate-limited",
   "expired",
@@ -98,6 +99,8 @@ export const ProviderCandidateSchema = z
     authScope: AuthScopeSchema,
     subscriptionStatus: SubscriptionStatusSchema.optional(),
     health: ProviderHealthSchema,
+    accountId: z.string().min(1).optional(),
+    subscriptionQuotaPercentRemaining: z.number().min(0).max(100).optional(),
     supportsTools: z.boolean(),
     supportsStreaming: z.boolean(),
     supportsJson: z.boolean(),
@@ -166,6 +169,7 @@ export const SelectedRouteSchema = z
     model: z.string().min(1),
     authTier: AuthTierSchema,
     authScope: AuthScopeSchema.optional(),
+    accountId: z.string().min(1).optional(),
   })
   .strict();
 
@@ -192,6 +196,7 @@ export const RouteDecisionSchema = z
     auditSummary: z.string().optional(),
     blocked: z.boolean().optional(),
     needsConfiguration: z.boolean().optional(),
+    nearLimitWarning: z.string().optional(),
   })
   .strict();
 

package/src/types.ts

@@ -9,6 +9,7 @@ export type AuthScope = "first-party" | "third-party" | "unknown";
 
 export type SubscriptionStatus =
   | "active"
+  | "near-limit"
   | "exhausted"
   | "rate-limited"
   | "expired"
@@ -73,6 +74,8 @@ export interface ProviderCandidate {
   authScope: AuthScope;
   subscriptionStatus?: SubscriptionStatus;
   health: ProviderHealth;
+  accountId?: string;
+  subscriptionQuotaPercentRemaining?: number;
   supportsTools: boolean;
   supportsStreaming: boolean;
   supportsJson: boolean;
@@ -129,6 +132,7 @@ export interface SelectedRoute {
   model: string;
   authTier: AuthTier;
   authScope?: AuthScope;
+  accountId?: string;
 }
 
 export interface FallbackChainEntry {
@@ -155,6 +159,8 @@ export interface RouteDecision {
   auditSummary?: string;
   blocked?: boolean;
   needsConfiguration?: boolean;
+  /** Warning when the selected route is a near-limit subscription with no healthy alternative. */
+  nearLimitWarning?: string;
 }
 
 /**

package/src/usage-file.test.ts

@@ -0,0 +1,243 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  DEFAULT_NEAR_LIMIT_THRESHOLD,
+  FileUsageStore,
+  InMemoryUsageStore,
+  type UsageStore,
+} from "./usage-file.js";
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })),
+  );
+},);
+
+async function makeTempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "offrouter-usage-file-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+async function makeFileStore(
+  filePath?: string,
+): Promise<{ dir: string; path: string; store: FileUsageStore }> {
+  const dir = await makeTempDir();
+  const path = filePath ?? join(dir, "state", "usage.json");
+  const store = new FileUsageStore({ filePath: path });
+  return { dir, path, store };
+}
+
+describe("FileUsageStore", () => {
+  it("satisfies the UsageStore interface contract", () => {
+    const store: UsageStore = new FileUsageStore({
+      filePath: "/tmp/offrouter-usage-store-interface.json",
+    });
+    expect(typeof store.recordUsage).toBe("function");
+    expect(typeof store.isNearLimit).toBe("function");
+    expect(typeof store.record).toBe("function");
+  });
+
+  it("persists account usage across store instances sharing the same file", async () => {
+    const { path, store } = await makeFileStore();
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 42,
+      limit: 100,
+    });
+
+    const reloaded = new FileUsageStore({ filePath: path });
+    const snap = await reloaded.getAccountUsage("anthropic", "anthropic-1");
+    expect(snap?.used).toBe(42);
+    expect(snap?.limit).toBe(100);
+    expect(snap?.remaining).toBe(58);
+
+    // A fresh instance also sees near-limit state.
+    expect(await reloaded.isNearLimit("anthropic", "anthropic-1")).toBe(false);
+  });
+
+  it("marks an account near-limit at 85% consumed (threshold 0.2)", async () => {
+    const { store } = await makeFileStore();
+    const snap = await store.recordUsage("anthropic", "anthropic-1", {
+      used: 85,
+      limit: 100,
+    });
+    expect(snap.remaining).toBe(15);
+    expect(snap.percentRemaining).toBe(15);
+    expect(snap.nearLimit).toBe(true);
+    expect(snap.subscriptionStatus).toBe("near-limit");
+    expect(await store.isNearLimit("anthropic", "anthropic-1")).toBe(true);
+  });
+
+  it("does not mark an account near-limit at 50% consumed", async () => {
+    const { store } = await makeFileStore();
+    const snap = await store.recordUsage("anthropic", "anthropic-1", {
+      used: 50,
+      limit: 100,
+    });
+    expect(snap.nearLimit).toBe(false);
+    expect(snap.subscriptionStatus).toBe("active");
+    expect(await store.isNearLimit("anthropic", "anthropic-1")).toBe(false);
+  });
+
+  it("respects a custom near-limit threshold", async () => {
+    const { store } = await makeFileStore();
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 85,
+      limit: 100,
+    });
+    // 15% remaining: near-limit at 0.2 default, not at stricter 0.1.
+    expect(await store.isNearLimit("anthropic", "anthropic-1")).toBe(true);
+    expect(await store.isNearLimit("anthropic", "anthropic-1", 0.1)).toBe(false);
+  });
+
+  it("marks an account exhausted at 100% consumed with dead health", async () => {
+    const { store } = await makeFileStore();
+    const snap = await store.recordUsage("anthropic", "anthropic-1", {
+      used: 100,
+      limit: 100,
+    });
+    expect(snap.subscriptionStatus).toBe("exhausted");
+    expect(snap.nearLimit).toBe(false);
+    expect(snap.health).toBe("dead");
+  });
+
+  it("writes the usage file with mode 0600 on POSIX", async () => {
+    if (process.platform === "win32") {
+      return;
+    }
+    const { path, store } = await makeFileStore();
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 1,
+      limit: 100,
+    });
+
+    const info = await stat(path);
+    expect(info.mode & 0o777).toBe(0o600);
+  });
+
+  it("falls back to an empty state on a corrupt file instead of crashing", async () => {
+    const dir = await makeTempDir();
+    const path = join(dir, "state", "usage.json");
+    await mkdir(join(dir, "state"), { recursive: true });
+    await writeFile(path, "{not valid json at all", "utf8");
+
+    const store = new FileUsageStore({ filePath: path });
+    // Reads do not throw; state is empty.
+    const snap = await store.getAccountUsage("anthropic", "anthropic-1");
+    expect(snap).toBeUndefined();
+    expect(await store.listAccountUsage()).toEqual([]);
+
+    // A subsequent write replaces the corrupt file with a valid document.
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 90,
+      limit: 100,
+    });
+    const raw = JSON.parse(await readFile(path, "utf8")) as {
+      version: number;
+      accounts: Record<string, unknown>;
+    };
+    expect(raw.version).toBe(1);
+    expect(Object.keys(raw.accounts)).toEqual(["anthropic:anthropic-1"]);
+  });
+
+  it("concurrent writes from two stores on the same file do not corrupt it", async () => {
+    const dir = await makeTempDir();
+    const path = join(dir, "state", "usage.json");
+    const s1 = new FileUsageStore({ filePath: path });
+    const s2 = new FileUsageStore({ filePath: path });
+
+    await Promise.all([
+      s1.recordUsage("anthropic", "anthropic-1", { used: 80, limit: 100 }),
+      s2.recordUsage("openai", "openai-1", { used: 90, limit: 100 }),
+    ]);
+
+    // The file is always valid JSON with the expected schema.
+    const raw = JSON.parse(await readFile(path, "utf8")) as {
+      version: number;
+      accounts: Record<string, { providerId: string }>;
+    };
+    expect(raw.version).toBe(1);
+    // Last-writer-wins is acceptable; corruption (invalid JSON) is not.
+    for (const doc of Object.values(raw.accounts)) {
+      expect(typeof doc.providerId).toBe("string");
+    }
+  });
+
+  it("writes on every mutation so a new process sees the latest usage", async () => {
+    const { path, store } = await makeFileStore();
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 10,
+      limit: 100,
+    });
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 88,
+      limit: 100,
+    });
+
+    const reloaded = new FileUsageStore({ filePath: path });
+    const snap = await reloaded.getAccountUsage("anthropic", "anthropic-1");
+    expect(snap?.used).toBe(88);
+    expect(snap?.nearLimit).toBe(true);
+  });
+
+  it("delegates provider health/quota logic to an in-memory store", async () => {
+    const { store } = await makeFileStore();
+    await store.setSubscriptionQuota("claude", {
+      limit: 10,
+      used: 9,
+      status: "active",
+    });
+    const snap = await store.getProvider("claude");
+    expect(snap?.subscriptionQuotaRemaining).toBe(1);
+    expect(snap?.health).toBe("healthy");
+  });
+
+  it("returns near-limit accounts across the persisted set", async () => {
+    const { store } = await makeFileStore();
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 85,
+      limit: 100,
+    });
+    await store.recordUsage("anthropic", "anthropic-2", {
+      used: 10,
+      limit: 100,
+    });
+    const near = await store.getNearLimitAccounts();
+    expect(near).toHaveLength(1);
+    expect(near[0]?.accountId).toBe("anthropic-1");
+  });
+
+  it("toJSON exposes diagnostics without throwing", async () => {
+    const { store } = await makeFileStore();
+    await store.recordUsage("anthropic", "anthropic-1", {
+      used: 85,
+      limit: 100,
+    });
+    const json = store.toJSON();
+    expect(json).toMatchObject({ kind: "file-usage" });
+    expect(JSON.stringify(json)).not.toContain("anthropic-1");
+  });
+
+  it("uses the default near-limit threshold constant", () => {
+    expect(DEFAULT_NEAR_LIMIT_THRESHOLD).toBe(0.2);
+  });
+
+  it("accepts an injected in-memory delegate for provider state", async () => {
+    const dir = await makeTempDir();
+    const path = join(dir, "state", "usage.json");
+    const delegate = new InMemoryUsageStore();
+    const wired = new FileUsageStore({ filePath: path, delegate });
+    await wired.setSubscriptionQuota("claude", {
+      limit: 5,
+      used: 1,
+      status: "active",
+    });
+    // Provider state lives on the injected delegate.
+    const snap = await delegate.getProvider("claude");
+    expect(snap?.subscriptionQuotaRemaining).toBe(4);
+  });
+});