offrouter-core 0.0.0 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "offrouter-core",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -15,7 +15,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "smol-toml": "^1.7.0",
-    "zod": "^3.23.0"
+    "smol-toml": "0.0.0",
+    "zod": "0.0.0"
   }
 }

package/src/auth/credential-chain.ts

@@ -7,6 +7,7 @@
  */
 
 import type { SecretStore } from "../secrets.js";
+import { accountStorageKey } from "./keychain.js";
 
 // ---------------------------------------------------------------------------
 // Redacted wrapper
@@ -51,7 +52,7 @@ export class Redacted<T extends string = string> {
 export type CredentialSource =
   | { type: "env"; name: string }
   | { type: "config"; key: string }
-  | { type: "keychain"; providerId: string }
+  | { type: "keychain"; providerId: string; accountId?: string }
   | { type: "oauth"; provider: string };
 
 /**
@@ -114,7 +115,7 @@ async function trySource(
       return tryConfig(source.key, opts.config);
     }
     case "keychain": {
-      return tryKeychain(source.providerId, opts.store);
+      return tryKeychain(source.providerId, opts.store, source.accountId);
     }
     case "oauth": {
       // OAuth is never auto-triggered during credential resolution.
@@ -168,9 +169,11 @@ function tryConfig(key: string, config?: Record<string, unknown>): string | null
 async function tryKeychain(
   providerId: string,
   store: SecretStore,
+  accountId?: string,
 ): Promise<string | null> {
   try {
-    const value = await store.get(providerId);
+    const key = accountStorageKey(providerId, accountId);
+    const value = await store.get(key);
     if (typeof value === "string" && value.trim().length > 0) {
       return value.trim();
     }

package/src/auth/keychain.test.ts

@@ -72,4 +72,41 @@ describe("setProviderToken", () => {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+});
+
+describe("multi-account tokens", () => {
+  it("stores and retrieves per-account tokens with backward compatibility", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "offrouter-keychain-test-"));
+    try {
+      const store = new FileSecretStore({ filePath: join(dir, "secrets.json") });
+      await setProviderToken("anthropic", "tok-legacy", store);
+      await setProviderToken("anthropic", "tok-2", store, "anthropic-2");
+
+      const legacy = await getProviderToken("anthropic", store);
+      expect(legacy!.rawValue).toBe("tok-legacy");
+
+      const acct2 = await getProviderToken("anthropic", store, "anthropic-2");
+      expect(acct2!.rawValue).toBe("tok-2");
+
+      // accountId === providerId uses legacy key
+      const explicitDefault = await getProviderToken("anthropic", store, "anthropic");
+      expect(explicitDefault!.rawValue).toBe("tok-legacy");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("setProviderToken with accountId matching providerId overwrites legacy slot", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "offrouter-keychain-test-"));
+    try {
+      const store = new FileSecretStore({ filePath: join(dir, "secrets.json") });
+      await setProviderToken("anthropic", "tok-legacy", store);
+      await setProviderToken("anthropic", "tok-implicit", store, "anthropic");
+
+      const result = await getProviderToken("anthropic", store);
+      expect(result!.rawValue).toBe("tok-implicit");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });

package/src/auth/keychain.ts

@@ -3,10 +3,24 @@
  *
  * Provides getProviderToken/setProviderToken that use the SecretStore
  * abstraction (file or OS keychain). Never scrapes other CLI credential stores.
+ *
+ * Per-account token storage: when accountId is provided and differs from
+ * providerId, the storage key is "${providerId}:${accountId}". Otherwise the
+ * plain providerId is used for backward compatibility with existing tokens.
  */
 import type { SecretStore } from "../secrets.js";
 import { Redacted } from "./credential-chain.js";
 
+/**
+ * Compute the storage key for a provider+account combination.
+ * Backward compatible: when accountId is absent or equals providerId, returns
+ * the plain providerId so existing tokens resolve.
+ */
+export function accountStorageKey(providerId: string, accountId?: string): string {
+  if (!accountId || accountId === providerId) return providerId;
+  return `${providerId}:${accountId}`;
+}
+
 /**
  * Retrieve a provider token from the secret store.
  * Returns undefined if no token is stored or the store is unavailable.
@@ -14,9 +28,11 @@ import { Redacted } from "./credential-chain.js";
 export async function getProviderToken(
   providerId: string,
   store: SecretStore,
+  accountId?: string,
 ): Promise<Redacted<string> | undefined> {
   try {
-    const value = await store.get(providerId);
+    const key = accountStorageKey(providerId, accountId);
+    const value = await store.get(key);
     if (typeof value === "string" && value.length > 0) {
       return new Redacted(value);
     }
@@ -34,6 +50,8 @@ export async function setProviderToken(
   providerId: string,
   token: string,
   store: SecretStore,
+  accountId?: string,
 ): Promise<void> {
-  await store.set(providerId, token);
+  const key = accountStorageKey(providerId, accountId);
+  await store.set(key, token);
 }

package/src/config.test.ts

@@ -157,7 +157,7 @@ enabled = true
     expect(config.policyDefaults.subscriptionFirst).toBe(true);
     expect(config.policyDefaults.allowApiKeyFallback).toBe(true);
     expect(config.providers).toEqual({
-      claude: { id: "claude", enabled: true },
+      claude: { id: "claude", enabled: true, accounts: [{ id: "claude" }] },
     });
 
     const allowed = evaluatePolicy(
@@ -323,7 +323,7 @@ enabled = true
       "project-enabled",
     ]);
     expect(trusted.providers).toEqual({
-      "project-agent": { id: "project-agent", enabled: true },
+      "project-agent": { id: "project-agent", enabled: true, accounts: [{ id: "project-agent" }] },
     });
     expect(trusted.sources).toContain(
       join(project, ".offrouter", "config.toml"),
@@ -412,4 +412,52 @@ weird_flag = 1
     expect(config.sources).toEqual([]);
     expect(config.warnings).toEqual([]);
   });
+
+  describe("multi-account provider config", () => {
+    it("parses TOML with explicit accounts array", async () => {
+      const home = await trackDir(makeHome);
+      await writeFile(
+        join(home, "config.toml"),
+        `
+allowlisted_profiles = ["claude-personal"]
+
+[[providers.anthropic.accounts]]
+id = "anthropic-1"
+label = "Work Account"
+
+[[providers.anthropic.accounts]]
+id = "anthropic-2"
+label = "Personal Account"
+`,
+        "utf8",
+      );
+
+      const config = await loadConfig({ env: { OFFROUTER_HOME: home } });
+      expect(config.providers.anthropic).toBeDefined();
+      expect(config.providers.anthropic.accounts).toEqual([
+        { id: "anthropic-1", label: "Work Account" },
+        { id: "anthropic-2", label: "Personal Account" },
+      ]);
+      expect(config.providers.anthropic.enabled).toBe(true);
+    });
+
+    it("creates implicit account when no accounts array is present", async () => {
+      const home = await trackDir(makeHome);
+      await writeFile(
+        join(home, "config.toml"),
+        `
+allowlisted_profiles = ["codex-personal"]
+
+[providers.openai]
+enabled = true
+`,
+        "utf8",
+      );
+
+      const config = await loadConfig({ env: { OFFROUTER_HOME: home } });
+      expect(config.providers.openai).toBeDefined();
+      expect(config.providers.openai.accounts).toEqual([{ id: "openai" }]);
+      expect(config.providers.openai.enabled).toBe(true);
+    });
+  });
 });

package/src/config.ts

@@ -20,6 +20,7 @@ export interface PolicyDefaults {
 export interface ConfiguredProvider {
   id: string;
   enabled: boolean;
+  accounts: ConfiguredAccount[];
 }
 
 /** Named profile overlay loaded from profiles/*.toml. */
@@ -30,6 +31,12 @@ export interface ConfiguredProfile {
   subscriptionFirst?: boolean;
 }
 
+/** Single configured account within a provider. */
+export interface ConfiguredAccount {
+  id: string;
+  label?: string;
+}
+
 export interface ConfigWarning {
   filePath: string;
   path: string;
@@ -94,6 +101,9 @@ function allowedFromZodShape(shape: z.ZodRawShape): AllowedShape {
 
 const ProviderConfigShape = {
   enabled: z.boolean().optional(),
+  accounts: z
+    .array(z.object({ id: z.string().min(1), label: z.string().optional() }).strict())
+    .optional(),
 } satisfies z.ZodRawShape;
 
 const PolicySectionShape = {
@@ -122,7 +132,10 @@ const ProfileFileShape = {
 const RootConfigSchema = z.object(RootConfigShape).strict();
 const ProfileFileSchema = z.object(ProfileFileShape).strict();
 
-const PROVIDER_ALLOWED: AllowedShape = allowedFromZodShape(ProviderConfigShape);
+const PROVIDER_ALLOWED: AllowedShape = {
+  ...allowedFromZodShape(ProviderConfigShape),
+  accounts: "leaf",
+};
 const ROOT_ALLOWED: AllowedShape = {
   ...allowedFromZodShape(RootConfigShape),
   policy: allowedFromZodShape(PolicySectionShape),
@@ -365,9 +378,13 @@ function mergeRootInto(
 
   if (root.providers) {
     for (const [id, provider] of Object.entries(root.providers)) {
+      const accounts: ConfiguredAccount[] = provider.accounts
+        ? provider.accounts.map((a: { id: string; label?: string }) => ({ id: a.id, label: a.label }))
+        : [{ id }];
       target.providers[id] = {
         id,
         enabled: provider.enabled ?? true,
+        accounts,
       };
     }
   }

package/src/index.ts

@@ -83,6 +83,7 @@ export {
   resolveOffRouterHome,
 } from "./config.js";
 export type {
+  ConfiguredAccount,
   ConfiguredProfile,
   ConfiguredProvider,
   ConfigWarning,
@@ -117,8 +118,9 @@ export type {
   MarkCancelledOptions,
 } from "./audit.js";
 
-export { InMemoryStateStore, InMemoryUsageStore } from "./usage.js";
+export { DEFAULT_NEAR_LIMIT_THRESHOLD, InMemoryStateStore, InMemoryUsageStore } from "./usage.js";
 export type {
+  AccountUsageSnapshot,
   InMemoryUsageStoreOptions,
   PaidFallbackExplanation,
   ProviderUsageSnapshot,

package/src/policy.ts

@@ -25,6 +25,8 @@ export interface PolicyConfig {
   allowThirdPartySubscriptionAdapters?: boolean;
   /** Optional explicit provider deny list by providerId. */
   deniedProviders?: string[];
+  /** Fraction of subscription quota remaining at/under which an account is "near-limit". Default 0.2. */
+  nearLimitThreshold?: number;
 }
 
 const HEALTHY_SUBSCRIPTION_STATUSES: ReadonlySet<SubscriptionStatus> = new Set([

package/src/providers/adapter.ts

@@ -209,6 +209,7 @@ export interface AuthStatus {
   subscriptionStatus?: SubscriptionStatus;
   limitsDiscoverable: boolean;
   health: ProviderHealth;
+  accountId?: string;
   detail?: string;
   /**
    * Which credential source satisfied auth (if any).
@@ -231,6 +232,7 @@ export interface LimitSnapshot {
   limit?: number;
   resetAt?: string;
   unit?: string;
+  accountId?: string;
   metadata?: Record<string, string | number | boolean | null>;
 }
 
@@ -320,5 +322,7 @@ export function capabilityToCandidate(
     contextWindowTokens: capability.contextWindowTokens,
     maxOutputTokens: capability.maxOutputTokens,
     estimatedCostUsd: extras.estimatedCostUsd ?? capability.estimatedCostUsd,
+    accountId: extras.accountId,
+    subscriptionQuotaPercentRemaining: extras.subscriptionQuotaPercentRemaining,
   };
 }

package/src/router.test.ts

@@ -559,4 +559,141 @@ describe("routeRequest", () => {
       expect(decision.auditSummary).not.toContain("raw user text");
     }
   });
+
+  describe("multi-account routing", () => {
+    it("selects first healthy subscription when two accounts have same rank", () => {
+      const decision = routeRequest(
+        baseRequest({
+          constraints: { subscriptionFirst: true, allowApiKeyFallback: false },
+        }),
+        [
+          candidate({
+            providerId: "anthropic",
+            modelId: "sonnet",
+            authTier: "subscription",
+            subscriptionStatus: "active",
+            health: "healthy",
+            accountId: "anthropic-1",
+            estimatedCostUsd: 0,
+          }),
+          candidate({
+            providerId: "anthropic",
+            modelId: "sonnet",
+            authTier: "subscription",
+            subscriptionStatus: "active",
+            health: "healthy",
+            accountId: "anthropic-2",
+            estimatedCostUsd: 0,
+          }),
+        ],
+        personalConfig,
+      );
+
+      expect(decision.blocked).toBeFalsy();
+      // Same rankKey, stable sort by input order: first candidate wins
+      expect(decision.route?.accountId).toBe("anthropic-1");
+    });
+
+    it("skips exhausted account and picks the next healthy one", () => {
+      const decision = routeRequest(
+        baseRequest({
+          constraints: { subscriptionFirst: true, allowApiKeyFallback: true },
+        }),
+        [
+          candidate({
+            providerId: "anthropic",
+            modelId: "sonnet",
+            authTier: "subscription",
+            subscriptionStatus: "exhausted",
+            health: "healthy",
+            accountId: "anthropic-1",
+            estimatedCostUsd: 0,
+          }),
+          candidate({
+            providerId: "anthropic",
+            modelId: "sonnet",
+            authTier: "subscription",
+            subscriptionStatus: "active",
+            health: "healthy",
+            accountId: "anthropic-2",
+            estimatedCostUsd: 0,
+          }),
+        ],
+        personalConfig,
+      );
+
+      expect(decision.blocked).toBeFalsy();
+      expect(decision.route?.accountId).toBe("anthropic-2");
+    });
+
+    it("prefers healthy active account over near-limit account", () => {
+      const decision = routeRequest(
+        baseRequest({
+          constraints: { subscriptionFirst: true, allowApiKeyFallback: false },
+        }),
+        [
+          candidate({
+            providerId: "anthropic",
+            modelId: "sonnet",
+            authTier: "subscription",
+            subscriptionStatus: "near-limit",
+            subscriptionQuotaPercentRemaining: 15,
+            health: "healthy",
+            accountId: "anthropic-1",
+            estimatedCostUsd: 0,
+          }),
+          candidate({
+            providerId: "anthropic",
+            modelId: "sonnet",
+            authTier: "subscription",
+            subscriptionStatus: "active",
+            health: "healthy",
+            accountId: "anthropic-2",
+            estimatedCostUsd: 0,
+          }),
+        ],
+        personalConfig,
+      );
+
+      expect(decision.blocked).toBeFalsy();
+      expect(decision.route?.accountId).toBe("anthropic-2");
+      expect(decision.nearLimitWarning).toBeUndefined();
+    });
+
+    it("selects near-limit subscription when no healthy alternative exists and warns", () => {
+      const decision = routeRequest(
+        baseRequest({
+          constraints: { subscriptionFirst: true, allowApiKeyFallback: true },
+        }),
+        [
+          candidate({
+            providerId: "anthropic",
+            modelId: "sonnet",
+            authTier: "subscription",
+            subscriptionStatus: "near-limit",
+            subscriptionQuotaPercentRemaining: 15,
+            health: "healthy",
+            accountId: "anthropic-1",
+            estimatedCostUsd: 0,
+          }),
+          candidate({
+            providerId: "openrouter",
+            modelId: "fast",
+            authTier: "api-key",
+            authScope: "third-party",
+            estimatedCostUsd: 0.01,
+          }),
+        ],
+        personalConfig,
+      );
+
+      expect(decision.blocked).toBeFalsy();
+      expect(decision.route?.accountId).toBe("anthropic-1");
+      expect(decision.nearLimitWarning).toBeTruthy();
+      expect(decision.nearLimitWarning).toContain("near its limit");
+      expect(decision.explanation).toContain("near its limit");
+      expect(decision.route?.provider).toBe("anthropic");
+      expect(decision.route?.model).toBe("sonnet");
+    });
+  });
 });

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.test.ts

@@ -281,3 +281,55 @@ describe("InMemoryStateStore", () => {
     expect(JSON.stringify(json)).not.toMatch(/sk-/);
   });
 });
+
+describe("near-limit / per-account usage", () => {
+  it("recordUsage returns near-limit snapshot when quota is nearly consumed", async () => {
+    const store = new InMemoryUsageStore();
+    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");
+  });
+
+  it("isNearLimit respects custom threshold", async () => {
+    const store = new InMemoryUsageStore();
+    await store.recordUsage("anthropic", "anthropic-1", { used: 85, limit: 100 });
+    expect(await store.isNearLimit("anthropic", "anthropic-1")).toBe(true);
+    expect(await store.isNearLimit("anthropic", "anthropic-1", 0.1)).toBe(false);
+  });
+
+  it("recordUsage detects exhaustion", async () => {
+    const store = new InMemoryUsageStore();
+    const snap = await store.recordUsage("anthropic", "anthropic-2", { used: 100, limit: 100 });
+    expect(snap.nearLimit).toBe(false);
+    expect(snap.subscriptionStatus).toBe("exhausted");
+  });
+
+  it("getNearLimitAccounts returns only accounts near their limit", async () => {
+    const store = new InMemoryUsageStore();
+    await store.recordUsage("anthropic", "anthropic-1", { used: 85, limit: 100 });
+    await store.recordUsage("anthropic", "anthropic-2", { used: 100, limit: 100 });
+    const nearLimit = await store.getNearLimitAccounts();
+    expect(nearLimit).toHaveLength(1);
+    expect(nearLimit[0]!.accountId).toBe("anthropic-1");
+  });
+
+  it("getAccountUsage returns correct snapshots for different accounts", async () => {
+    const store = new InMemoryUsageStore();
+    await store.recordUsage("anthropic", "anthropic-1", { used: 85, limit: 100 });
+    await store.recordUsage("anthropic", "anthropic-2", { used: 10, limit: 100 });
+    const snap1 = await store.getAccountUsage("anthropic", "anthropic-1");
+    const snap2 = await store.getAccountUsage("anthropic", "anthropic-2");
+    expect(snap1?.used).toBe(85);
+    expect(snap2?.used).toBe(10);
+  });
+
+  it("existing setSubscriptionQuota and record still behave as before", async () => {
+    const store = new InMemoryUsageStore();
+    await store.setSubscriptionQuota("test", { limit: 50, used: 10, status: "active" });
+    const snap = await store.getProvider("test");
+    expect(snap?.subscriptionQuotaLimit).toBe(50);
+    expect(snap?.subscriptionQuotaUsed).toBe(10);
+  });
+});

package/src/usage.ts

@@ -104,6 +104,23 @@ export interface RecordUsageResult {
   previousHealth: ProviderHealth;
 }
 
+export const DEFAULT_NEAR_LIMIT_THRESHOLD = 0.2;
+
+/**
+ * Snapshot of usage for a specific account within a provider.
+ */
+export interface AccountUsageSnapshot {
+  providerId: string;
+  accountId: string;
+  used: number;
+  limit?: number;
+  remaining?: number;
+  percentRemaining?: number;
+  nearLimit: boolean;
+  subscriptionStatus: SubscriptionStatus;
+  updatedAt: string;
+}
+
 /**
  * Why paid API-key capacity was or was not selected given current usage state.
  * Consumed by doctor / status / route explain surfaces.
@@ -154,6 +171,35 @@ export interface UsageStore {
     options?: { hasApiKeyCandidate?: boolean },
   ): Promise<PaidFallbackExplanation>;
 
+  /**
+   * Record usage for a specific account within a provider.
+   */
+  recordUsage(
+    providerId: string,
+    accountId: string,
+    input: { used?: number; limit?: number; at?: Date },
+  ): Promise<AccountUsageSnapshot>;
+
+  /**
+   * Check whether a specific account is near its quota limit.
+   */
+  isNearLimit(providerId: string, accountId: string, threshold?: number): Promise<boolean>;
+
+  /**
+   * Get all accounts whose usage is near their quota limit.
+   */
+  getNearLimitAccounts(threshold?: number): Promise<AccountUsageSnapshot[]>;
+
+  /**
+   * Get the usage snapshot for a specific account.
+   */
+  getAccountUsage(providerId: string, accountId: string): Promise<AccountUsageSnapshot | undefined>;
+
+  /**
+   * List all account usage snapshots.
+   */
+  listAccountUsage(): Promise<AccountUsageSnapshot[]>;
+
   /**
    * JSON-safe diagnostic view. No secrets.
    */
@@ -184,6 +230,14 @@ interface InternalProviderState {
   updatedAt: string;
 }
 
+interface AccountQuotaState {
+  providerId: string;
+  accountId: string;
+  used: number;
+  limit?: number;
+  updatedAt: string;
+}
+
 const DEFAULT_WINDOW_MS = 60_000;
 const DEFAULT_HEALTHY_MAX_ERRORS = 2;
 const DEFAULT_DEAD_MIN_ERRORS = 5;
@@ -200,6 +254,7 @@ const HARD_ERROR_KINDS: ReadonlySet<UsageEventKind> = new Set([
  */
 export class InMemoryUsageStore implements UsageStore {
   readonly #providers = new Map<string, InternalProviderState>();
+  readonly #accounts = new Map<string, AccountQuotaState>();
   readonly #windowMs: number;
   readonly #healthyMaxErrors: number;
   readonly #deadMinErrors: number;
@@ -505,6 +560,78 @@ export class InMemoryUsageStore implements UsageStore {
     };
   }
 
+  async recordUsage(
+    providerId: string,
+    accountId: string,
+    input: { used?: number; limit?: number; at?: Date },
+  ): Promise<AccountUsageSnapshot> {
+    return this.#exclusive(() => {
+      const at = input.at ?? this.#now();
+      const key = `${providerId}:${accountId}`;
+      let state = this.#accounts.get(key);
+      if (!state) {
+        state = { providerId, accountId, used: 0, updatedAt: at.toISOString() };
+        this.#accounts.set(key, state);
+      }
+      if (input.used !== undefined) state.used = input.used;
+      if (input.limit !== undefined) state.limit = input.limit;
+      state.updatedAt = at.toISOString();
+      return toAccountSnapshot(state);
+    });
+  }
+
+  async isNearLimit(
+    providerId: string,
+    accountId: string,
+    threshold?: number,
+  ): Promise<boolean> {
+    return this.#exclusive(() => {
+      const key = `${providerId}:${accountId}`;
+      const state = this.#accounts.get(key);
+      if (!state) return false;
+      return toAccountSnapshot(state, threshold).nearLimit;
+    });
+  }
+
+  async getNearLimitAccounts(threshold?: number): Promise<AccountUsageSnapshot[]> {
+    return this.#exclusive(() => {
+      const out: AccountUsageSnapshot[] = [];
+      for (const state of this.#accounts.values()) {
+        const snap = toAccountSnapshot(state, threshold);
+        if (snap.nearLimit) out.push(snap);
+      }
+      return out.sort((a, b) => {
+        if (a.providerId !== b.providerId) return a.providerId.localeCompare(b.providerId);
+        return a.accountId.localeCompare(b.accountId);
+      });
+    });
+  }
+
+  async getAccountUsage(
+    providerId: string,
+    accountId: string,
+  ): Promise<AccountUsageSnapshot | undefined> {
+    return this.#exclusive(() => {
+      const key = `${providerId}:${accountId}`;
+      const state = this.#accounts.get(key);
+      if (!state) return undefined;
+      return toAccountSnapshot(state);
+    });
+  }
+
+  async listAccountUsage(): Promise<AccountUsageSnapshot[]> {
+    return this.#exclusive(() => {
+      const out: AccountUsageSnapshot[] = [];
+      for (const state of this.#accounts.values()) {
+        out.push(toAccountSnapshot(state));
+      }
+      return out.sort((a, b) => {
+        if (a.providerId !== b.providerId) return a.providerId.localeCompare(b.providerId);
+        return a.accountId.localeCompare(b.accountId);
+      });
+    });
+  }
+
   toJSON(): Record<string, unknown> {
     const providers: Record<string, unknown> = {};
     for (const [id, state] of this.#providers) {
@@ -523,6 +650,7 @@ export class InMemoryUsageStore implements UsageStore {
     return {
       kind: "in-memory-usage",
       providers,
+      accounts: Object.fromEntries(this.#accounts),
     };
   }
 
@@ -635,6 +763,41 @@ function toSnapshot(state: InternalProviderState): ProviderUsageSnapshot {
   };
 }
 
+function toAccountSnapshot(
+  state: AccountQuotaState,
+  threshold?: number,
+): AccountUsageSnapshot {
+  const t = threshold ?? DEFAULT_NEAR_LIMIT_THRESHOLD;
+  const limit = state.limit;
+  const used = state.used;
+  const remaining = limit === undefined ? undefined : Math.max(0, limit - used);
+  let status: SubscriptionStatus;
+  let nearLimit = false;
+  if (limit === undefined) {
+    status = "unknown";
+  } else if (used >= limit) {
+    status = "exhausted";
+  } else if ((limit - used) / limit < t) {
+    status = "near-limit";
+    nearLimit = true;
+  } else {
+    status = "active";
+  }
+  const percentRemaining =
+    limit === undefined ? undefined : Math.round(((limit - used) / limit) * 100);
+  return {
+    providerId: state.providerId,
+    accountId: state.accountId,
+    used,
+    limit,
+    remaining,
+    percentRemaining,
+    nearLimit,
+    subscriptionStatus: status,
+    updatedAt: state.updatedAt,
+  };
+}
+
 /**
  * Composite facade for callers that want one injectable "state" handle.
  * Writes stay on the specialized stores; this is a thin convenience.