tokenmaxxing 1.131.0 → 1.133.0

package/src/lib/decide.ts

@@ -6,9 +6,9 @@ import { MAX_WAITERS_PER_ACCOUNT, isExhausted, landWindows, limitWindows, liveUs
 import { familyTokens } from "./usage.ts";
 import { errorMessage, log } from "./log.ts";
 import type { Observation, Provider, ResetClaim } from "./provider.ts";
-import type { Account, Bars, Config, EnforcedLimit } from "./types.ts";
+import type { Account, ApiKey, Bars, Config, EnforcedLimit } from "./types.ts";
 
-export type SwapDecision = { swapped: boolean; account: Account | null; reason: string; waitUntil?: number };
+export type SwapDecision = { swapped: boolean; account: Account | null; apiKey?: ApiKey; reason: string; waitUntil?: number };
 
 export type EvalOpts = {
   seatId?: string | null;
@@ -16,8 +16,18 @@ export type EvalOpts = {
   waiterId?: string;
   exclude?: string[];
   refused?: string[];
+  apiKeys?: boolean;
+  apiKeyId?: string;
 };
 
+export type MoveTarget = { accountId: string; apiKeyId?: string; waitUntil: number | undefined };
+
+export function moveTarget(d: SwapDecision): MoveTarget | null {
+  if (d.apiKey) return { accountId: "", apiKeyId: d.apiKey.id, waitUntil: undefined };
+  if (d.account && (d.swapped || d.waitUntil !== undefined)) return { accountId: d.account.id, waitUntil: d.waitUntil };
+  return null;
+}
+
 const MOVE_CLAIM_MS = 2 * CLAUDE_COMPACT_KILL_MS;
 
 const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
@@ -106,6 +116,8 @@ export async function useBankedResets(p: Provider, cfg: Config, now: number): Pr
 
 export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRespawn = false, enforced: EnforcedLimit | null = null, opts: EvalOpts = {}): Promise<SwapDecision> {
   const activeId = opts.seatId === undefined ? p.liveId() : opts.seatId;
+  const keys = opts.apiKeys === true ? p.apiKeys : undefined;
+  const keyId = activeId == null && keys ? (opts.apiKeyId ?? keys.liveId()) : null;
   const waiterId = canRespawn ? opts.waiterId : undefined;
   const cfg = loadConfig();
   const bars = thresholdBars(cfg);
@@ -116,7 +128,7 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
   const observed = stored0 ? await p.observeLive(stored0, cfg, now, { probe: enforced == null && !walled0, perModel: gated == null || gated.length > 0 }) : null;
   const stored = loadAccounts(p.pool).accounts.find((a) => a.id === activeId);
 
-  if (!enforced && !isOver(stored, observed, { now, thresholds: bars, currentId: activeId, families: gated, seats: null })) {
+  if (!enforced && keyId == null && !isOver(stored, observed, { now, thresholds: bars, currentId: activeId, families: gated, seats: null })) {
     if (waiterId != null && liveWaitClaims(now).some((c) => c.sessionId === waiterId)) {
       await withLock(p.pool.lockFile, () => {
         releaseWaitClaim(waiterId);
@@ -168,7 +180,7 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
     const seats = p.seats === "shared" ? present : null;
 
     const seatExhausted = active != null && isExhausted(active, { now, thresholds: bars, currentId: id2, families: switchFamilies, seats });
-    if (!enforced2 && !isOver(active, obs2, { now, thresholds: bars, currentId: id2, families, seats }) && !(enforced && seatExhausted)) {
+    if (keyId == null && !enforced2 && !isOver(active, obs2, { now, thresholds: bars, currentId: id2, families, seats }) && !(enforced && seatExhausted)) {
       return { swapped: false, account: null, reason: "raced-already-swapped" };
     }
     if (p.seats === "shared" && !canRespawn) {
@@ -189,9 +201,9 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
       const seat = seatOf(cur);
       const ctx: PickCtx = { now, thresholds: bars, currentId: seat?.id ?? null, families: switchFamilies, seats };
       const credited = !enforced2 && seat != null && !seat.needsReauth && !isExhausted(seat, ctx) && onCredits(seat, ctx);
-      const best = pickBest(usable(cur.accounts).filter((a) => !(credited && opts.refused?.includes(a.id))), ctx);
+      const best = pickBest(usable(cur.accounts).filter((a) => !((credited || keyId != null) && opts.refused?.includes(a.id))), ctx);
       if (credited && (best == null || onCredits(best, ctx))) return { swapped: false, account: null, reason: "no-plan-headroom" };
-      if (!best) break;
+      if (!best || (keyId != null && onCredits(best, ctx))) break;
       try {
         await p.swap(best);
       } catch (e) {
@@ -203,6 +215,15 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
       return { swapped: true, account: best, reason: "swapped" };
     }
 
+    if (keys) {
+      if (keyId != null && keys.holds(keyId)) return { swapped: false, account: null, reason: "api-key-holds" };
+      const key = keys.pick(keyId == null ? [] : [keyId]);
+      if (key) {
+        log("decide.api_key", { key: key.id, from: keyId ?? id2?.slice(0, 8) });
+        return { swapped: true, account: null, apiKey: key, reason: "api-key" };
+      }
+    }
+
     if (!p.waitsWhenDepleted) {
       log("decide.depleted", { waitUntil: 0 });
       return { swapped: false, account: null, reason: "all-depleted" };

package/src/lib/paths.ts

@@ -28,6 +28,8 @@ export const paths = {
   onboardDir: join(TM_HOME, "onboard"),
   storesDir: join(TM_HOME, "stores"),
   hubKeyFile: join(TM_HOME, "hub-key"),
+  apiKeysDir: join(TM_HOME, "api-keys"),
+  costDir: join(TM_HOME, "cost"),
 
   claudeSettings: env(
     "TOKENMAXXING_CLAUDE_SETTINGS",
@@ -43,6 +45,7 @@ export const claudePool = {
   accountsJson: join(TM_HOME, "accounts.json"),
   lockFile: join(TM_HOME, "lock"),
   waitQueueJson: join(TM_HOME, "wait-queue.json"),
+  apiKeysJson: join(TM_HOME, "api-keys.json"),
 } as const;
 
 export const codexPool = {

package/src/lib/pi.ts

@@ -98,6 +98,7 @@ export async function piLogin(pool: PiPool): Promise<PiLogin | null> {
 function piMover(base: Provider, pool: PiPool): Provider {
   return {
     ...base,
+    apiKeys: undefined,
     swap: async (target) => {
       if (!piStoreUsable(pool, target.id)) {
         throw new StoreUnusableError(`${target.label} has no pi login - run \`tokenmaxxing auth --pi${base.flag} ${target.label}\``);

package/src/lib/presence.ts

@@ -13,12 +13,13 @@ const PresenceSchema = z.object({
   accountId: z.string(),
   pid: z.number(),
   startedAt: z.string(),
+  apiKeyId: z.string().optional(),
 });
 
-export function writePresence(input: { dir: string; id: string; accountId: string; pid: number }): void {
+export function writePresence(input: { dir: string; id: string; accountId: string; pid: number; apiKeyId?: string }): void {
   const startedAt = pidStartTimes([input.pid]).get(input.pid);
   if (startedAt == null) throw new Error(`could not read pid ${input.pid}'s start time (ps lstart) - refusing to write an unverifiable presence file`);
-  writeFileAtomic(join(input.dir, input.id), JSON.stringify(PresenceSchema.parse({ accountId: input.accountId, pid: input.pid, startedAt })));
+  writeFileAtomic(join(input.dir, input.id), JSON.stringify(PresenceSchema.parse({ accountId: input.accountId, pid: input.pid, startedAt, ...(input.apiKeyId != null ? { apiKeyId: input.apiKeyId } : {}) })));
 }
 
 export function presencePid(input: { dir: string; id: string }): number | null {
@@ -34,7 +35,7 @@ export function clearPresence(input: { dir: string; id: string }): void {
   rmSync(join(input.dir, input.id), { force: true });
 }
 
-export type LivingPresence = { id: string; accountId: string };
+export type LivingPresence = { id: string; accountId: string; apiKeyId?: string };
 
 export function livingPresences(dir: string): LivingPresence[] {
   if (!existsSync(dir)) return [];
@@ -65,11 +66,11 @@ export function livingPresences(dir: string): LivingPresence[] {
       rmSync(file, { force: true });
       continue;
     }
-    living.push({ id: name, accountId: record.accountId });
+    living.push({ id: name, accountId: record.accountId, ...(record.apiKeyId != null ? { apiKeyId: record.apiKeyId } : {}) });
   }
   return living;
 }
 
 export function seatCounts(dir: string): Map<string, number> {
-  return new Map(Object.entries(countBy(livingPresences(dir), (p) => p.accountId)));
+  return new Map(Object.entries(countBy(livingPresences(dir).filter((p) => p.apiKeyId == null), (p) => p.accountId)));
 }

package/src/lib/provider.ts

@@ -1,6 +1,12 @@
 import type { PoolPaths } from "./paths.ts";
 import type { Harvest } from "./state.ts";
-import type { Account, Config, Window } from "./types.ts";
+import type { Account, ApiKey, Config, Window } from "./types.ts";
+
+export type ApiKeyPool = {
+  liveId(): string | null;
+  holds(id: string): boolean;
+  pick(exclude: string[]): ApiKey | null;
+};
 
 export type Observation = { windows: Window[]; at: number };
 
@@ -26,6 +32,7 @@ export type Provider = {
   seats: "shared" | "live";
   waitsWhenDepleted: boolean;
   statusOnly: boolean;
+  apiKeys?: ApiKeyPool;
   liveId(): string | null;
   presence(): Map<string, number>;
   gatedFamilies(cfg: Config): string[] | null;

package/src/lib/sessions.ts

@@ -60,7 +60,7 @@ function listDir(dir: string, root: string): Dirent[] {
 }
 
 function tmpSweepDirs(root: string): string[] {
-  const dirs = [paths.home, paths.usageDir, paths.presenceDir, paths.respawnDir, sessionsDir(), paths.binDir, codexPaths.presenceDir, codexPaths.respawnDir, codexPaths.onboardDir];
+  const dirs = [paths.home, paths.usageDir, paths.presenceDir, paths.respawnDir, sessionsDir(), paths.binDir, paths.apiKeysDir, paths.costDir, codexPaths.presenceDir, codexPaths.respawnDir, codexPaths.onboardDir];
   for (const parent of STORE_PARENTS) {
     for (const child of listDir(parent, root)) {
       if (child.isDirectory()) dirs.push(join(parent, child.name));
@@ -113,6 +113,10 @@ export function supervisedSession(env: Record<string, string | undefined> = proc
   return { sid, launchedAt: LaunchedAtSchema.parse(env.TOKENMAXXING_LAUNCHED_AT) ?? null, live: liveSessionId(sid) };
 }
 
+export function keyMovesSupported(env: Record<string, string | undefined> = process.env): boolean {
+  return env.TOKENMAXXING_API_KEY_ID !== undefined;
+}
+
 export function refusedAccounts(env: Record<string, string | undefined> = process.env): string[] {
   return RefusedSchema.parse(env.TOKENMAXXING_REFUSED);
 }
@@ -129,9 +133,10 @@ export function adoptLiveSession(session: SupervisedSession, stdinSid: string |
   return { ...session, live: stdinSid };
 }
 
-export function writeRespawnMarker(input: { session: SupervisedSession; accountId: string; waitUntil: number; compact: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"]; refused?: string[] }): void {
+export function writeRespawnMarker(input: { session: SupervisedSession; accountId: string; apiKeyId?: string; waitUntil: number; compact: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"]; refused?: string[] }): void {
   const payload: z.infer<typeof RespawnMarkerSchema> = {
     accountId: input.accountId,
+    ...(input.apiKeyId != null ? { apiKeyId: input.apiKeyId } : {}),
     ts: Date.now(),
     waitUntil: input.waitUntil,
     sessionId: input.session.live,

package/src/lib/supervise.ts

@@ -1,7 +1,10 @@
+import { once } from "node:events";
+import { isatty } from "node:tty";
 import type { Subprocess } from "bun";
 import { LOOP_DIAGNOSIS, MAX_WRAP_DEPTH, WRAP_RATE_WINDOW_MS, wrapDepth, wrapperChainTripped } from "./claudebin.ts";
 import { errorMessage, log } from "./log.ts";
 import { paths } from "./paths.ts";
+import { readLines } from "./proc.ts";
 import { writePresence } from "./presence.ts";
 import { restoreTermios } from "./tty.ts";
 
@@ -75,17 +78,64 @@ export function loopGuardTripped(product: WrappedProduct): boolean {
   return false;
 }
 
+const STDOUT_QUIET_MS = 1000;
+
+export function childStdout(): "inherit" | "pipe" {
+  return isatty(1) ? "inherit" : "pipe";
+}
+
+export function relayStdout(source: ReadableStream<Uint8Array>, onLine?: (line: string) => void): (abandoned?: () => boolean) => Promise<void> {
+  let ended = false;
+  let blocked = false;
+  let readAt = Date.now();
+  const forwarded = source.pipeThrough(
+    new TransformStream<Uint8Array, Uint8Array>({
+      async transform(chunk, controller) {
+        readAt = Date.now();
+        if (!process.stdout.write(chunk)) {
+          blocked = true;
+          await once(process.stdout, "drain");
+          blocked = false;
+        }
+        controller.enqueue(chunk);
+      },
+    }),
+  );
+  void (async () => {
+    if (onLine == null) return forwarded.pipeTo(new WritableStream());
+    for await (const line of readLines(forwarded)) {
+      try {
+        onLine(line);
+      } catch (e) {
+        log("supervisor.tee_failed", { err: errorMessage(e) });
+      }
+    }
+  })()
+    .catch((e: unknown) => log("supervisor.stdout_relay_failed", { err: errorMessage(e) }))
+    .finally(() => {
+      ended = true;
+    });
+  return async (abandoned = () => false) => {
+    const exitedAt = Date.now();
+    while (!ended && (blocked ? !abandoned() : Date.now() - Math.max(readAt, exitedAt) < STDOUT_QUIET_MS)) await Bun.sleep(50);
+  };
+}
+
 export async function runPassthrough(input: { real: string; argv: string[]; env: Record<string, string | undefined>; onSpawn?: (child: Subprocess) => void | Promise<void> }): Promise<number> {
-  const p = Bun.spawn([input.real, ...input.argv], { stdin: "inherit", stdout: "inherit", stderr: "inherit", env: input.env });
+  let terminated = false;
+  process.on("SIGTERM", () => { terminated = true; });
+  const p = Bun.spawn([input.real, ...input.argv], { stdin: "inherit", stdout: childStdout(), stderr: "inherit", env: input.env });
+  const drain = p.stdout instanceof ReadableStream ? relayStdout(p.stdout) : null;
   await input.onSpawn?.(p);
   await p.exited;
+  await drain?.(() => terminated);
   return exitStatus(p);
 }
 
-export async function recordPresenceOrStop(input: { child: ChildHandle; dir: string; id: string; accountId: string; event: string; message: string; savedTermios: string | null }): Promise<void> {
+export async function recordPresenceOrStop(input: { child: ChildHandle; dir: string; id: string; accountId: string; apiKeyId?: string; event: string; message: string; savedTermios: string | null }): Promise<void> {
   for (let attempt = 0; ; attempt++) {
     try {
-      writePresence({ dir: input.dir, id: input.id, accountId: input.accountId, pid: input.child.pid });
+      writePresence({ dir: input.dir, id: input.id, accountId: input.accountId, pid: input.child.pid, ...(input.apiKeyId != null ? { apiKeyId: input.apiKeyId } : {}) });
       return;
     } catch (e) {
       if (input.child.exitCode !== null || input.child.signalCode !== null) return;

package/src/lib/types.ts

@@ -169,8 +169,38 @@ export const RespawnMarkerSchema = z.object({
   origin: z.enum(["stop", "sessionstart", "stopfailure", "seatwatch"]),
   launchedAt: z.number().optional(),
   refused: z.array(z.string()).optional(),
+  apiKeyId: z.string().optional(),
 });
 
+export const ApiKeySchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  workspaceId: z.string().optional(),
+  creditUsd: z.number().optional(),
+  spentUsd: z.number(),
+  creditSetAt: z.number(),
+  refusedAt: z.number().optional(),
+  addedAt: z.number(),
+});
+export type ApiKey = z.infer<typeof ApiKeySchema>;
+
+export const ApiKeysIndexSchema = z.object({
+  version: z.literal(1),
+  keys: z.array(ApiKeySchema).default([]),
+  baselines: z.record(z.string(), z.object({ usd: z.number(), at: z.number() })).default({}),
+});
+export type ApiKeysIndex = z.infer<typeof ApiKeysIndexSchema>;
+
+export const SessionCostSchema = z.object({ sessionId: z.string(), usd: z.number() });
+export type SessionCost = z.infer<typeof SessionCostSchema>;
+
+export const CostLineSchema = z
+  .looseObject({ session_id: z.string(), total_cost_usd: z.number().optional(), cost: z.looseObject({ total_cost_usd: z.number() }).nullable().optional() })
+  .transform((line): SessionCost | null => {
+    const usd = line.total_cost_usd ?? line.cost?.total_cost_usd;
+    return usd == null ? null : { sessionId: line.session_id, usd };
+  });
+
 export const EpochSecondsSchema = z.number().transform((seconds) => seconds * 1000);
 
 export const InstantSchema = z.iso.datetime({ offset: true }).transform((iso) => Date.parse(iso));

package/src/lib/usage.ts

@@ -105,7 +105,7 @@ export function transcriptRowText(row: TranscriptRow): string {
   return blocks.data.filter((b) => b.type === "text").map((b) => b.text ?? "").join("\n").trim();
 }
 
-export const ENFORCED_ERRORS = ["rate_limit", "oauth_org_not_allowed"];
+export const ENFORCED_ERRORS = ["rate_limit", "oauth_org_not_allowed", "billing_error"];
 
 export function findEnforcedRow(input: { rows: TranscriptRow[]; error: string; lastAssistantMessage: string | undefined }): TranscriptRow | null {
   const { rows, error, lastAssistantMessage } = input;

package/src/main.ts

@@ -20,6 +20,7 @@ import { cmdStatus } from "./cli/status.ts";
 import { cmdDoctor } from "./cli/doctor.ts";
 import { cmdRm } from "./cli/rm.ts";
 import { cmdRename } from "./cli/rename.ts";
+import { cmdKey } from "./cli/key.ts";
 import { cmdCheck } from "./cli/check.ts";
 import { cmdConfig } from "./cli/config.ts";
 import { cmdSeat } from "./cli/seat.ts";
@@ -38,7 +39,7 @@ const PI_FLAG = "--pi";
 const JSON_COMMANDS = new Set(["status", "config", "check"]);
 const CODEX_COMMANDS = new Set(["init", "add", "auth", "rm", "rename", "seat"]);
 const STATUS_ONLY_COMMANDS = new Set(["init", "add", "auth", "rm", "rename"]);
-const MAX_OPERANDS = new Map([["init", 0], ["add", 0], ["rm", 1], ["rename", 2]]);
+const MAX_OPERANDS = new Map([["init", 0], ["add", 0], ["rm", 1], ["rename", 2], ["key", 4]]);
 
 function printHelp(): void {
   console.log(`${c.bold("tokenmaxxing")} - automatic Claude Code account switching
@@ -58,6 +59,9 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing doctor")}     verify the install is intact
   ${c.cyan("tokenmaxxing rename")} [--codex | --grok] <sel> <label>
   ${c.cyan("tokenmaxxing rm")} [--codex | --grok] <sel>
+  ${c.cyan("tokenmaxxing key add")} <label> [credit-usd] [workspace-id]  store an Anthropic API key read from stdin; Claude sessions run on it only while every pooled Claude account is at its limit (workspace-id: for a key that spans several workspaces)
+  ${c.cyan("tokenmaxxing key credit")} <label> <usd>  set the key's balance as the Console shows it and restart its spend count
+  ${c.cyan("tokenmaxxing key rm")} <label>  delete the key and its stored secret (refused while a session runs on it)
   ${c.cyan("tokenmaxxing seat")} <pid>  lend one pooled Claude account to an unattended consumer until <pid> exits: prints the store directory to set as CLAUDE_SECURESTORAGE_CONFIG_DIR (the directory itself, as its owner, never a copy of its credential); host sessions and other borrowers share the account; exit 1 = none usable
   ${c.cyan("tokenmaxxing seat --codex")} <pid>  borrow one pooled codex account for an unattended consumer (plugin, script): prints the CODEX_HOME to set, lent to <pid> until it exits; codex sessions and other borrowers share the account, and a refresh race between them can sign it out until auth --codex runs again; exit 1 = none usable, fall back to the ambient login
   ${c.cyan("tokenmaxxing serve")}      serve the CLIProxyAPI-compatible usage API on http://localhost:<hub.port> (default 8317) so a dashboard such as T3 Code's "Add a CLIProxyAPI hub" shows every pooled Claude and Codex account's quota; the management key is the contents of hub-key in the state directory
@@ -173,6 +177,7 @@ async function main(): Promise<number> {
     case "doctor": return cmdDoctor();
     case "rm": return cmdRm(provider, args[1]);
     case "rename": return cmdRename(provider, args.slice(1));
+    case "key": return cmdKey(args.slice(1));
     case "seat": return cmdSeat(provider === codex ? "codex" : "claude", args[1], args.slice(2));
     case "serve": return cmdServe(args.slice(1));
     case "uninstall": {
@@ -198,7 +203,7 @@ async function main(): Promise<number> {
       if (out.timer === "still-loaded") console.log(c.yellow(`⚠ the check job may still be loaded - run: ${deactivationHint(CHECK_JOB)}`));
       if (out.hub === "still-loaded") console.log(c.yellow(`⚠ the usage hub job may still be loaded - run: ${deactivationHint(HUB_JOB)}`));
       if (!out.pathLineRemoved) console.log(c.dim("(no tokenmaxxing PATH line found in the shell rc)"));
-      console.log(`kept: accounts.json, config.json, and every account credential store (claude: stores/ and its keychain items on macOS; codex: codex-stores/; pi: pi-stores/; grok: grok-stores/) - remove accounts with \`xx rm\` to delete their credentials`);
+      console.log(`kept: accounts.json, config.json, and every account credential store (claude: stores/ and its keychain items on macOS; codex: codex-stores/; pi: pi-stores/; grok: grok-stores/), plus api-keys.json and the API keys in api-keys/ - remove accounts with \`xx rm\` and keys with \`xx key rm\` to delete their credentials`);
       return 0;
     }
     case "help":