tokenmaxxing 1.131.0 → 1.133.0

package/src/entries/supervisor.ts

@@ -1,4 +1,3 @@
-import { once } from "node:events";
 import { existsSync, mkdirSync, rmSync, readdirSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
 import type { FileSink, Subprocess } from "bun";
@@ -6,20 +5,21 @@ import { maxBy, omit } from "es-toolkit";
 import { z } from "zod";
 import { claudePool, paths, storeDirFor } from "../lib/paths.ts";
 import { CLAUDE_BIN, UNMANAGED_ENV, WRAP_DEPTH_ENV, resolveRealBin, wrapDepth } from "../lib/claudebin.ts";
-import { claude, pickSeat } from "../lib/claude.ts";
+import { apiKeyEnv, clearSessionCost, foldSessionCost, loadApiKeys, readApiKey, sendApiKey, usableApiKey, writeSessionCost } from "../lib/apikeys.ts";
+import { claude, pickLaunch, type LaunchTarget } from "../lib/claude.ts";
 import { compactClaudeSession } from "../lib/compact.ts";
-import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { evaluateAndMaybeSwap, moveTarget } from "../lib/decide.ts";
 import { withLock } from "../lib/lock.ts";
 import { thresholdBars, usableAt } from "../lib/picker.ts";
 import { clearPresence } from "../lib/presence.ts";
 import { readLines } from "../lib/proc.ts";
 import { teeObservation } from "../lib/sample.ts";
-import { countdownWait, exitStatus, loopGuardTripped, raceMarkerOrExit, recordPresenceOrStop, runPassthrough, SEAT_POLL_MS, SEAT_RETRY_MS, type Say } from "../lib/supervise.ts";
+import { countdownWait, exitStatus, loopGuardTripped, raceMarkerOrExit, recordPresenceOrStop, relayStdout, runPassthrough, SEAT_POLL_MS, SEAT_RETRY_MS, type Say } from "../lib/supervise.ts";
 import { saveTermios } from "../lib/tty.ts";
 import { liveSessionId, loadSessionFlags, pruneStaleSessions, saveSessionFlags, writeRespawnMarker } from "../lib/sessions.ts";
 import { loadAccounts, loadConfig, readJsonFile, releaseWaitClaim, writeUsage } from "../lib/state.ts";
 import { gatedFamilies, modelFromFlag, parseStreamLine, scrubCredEnv } from "../lib/usage.ts";
-import { JsonTextSchema, RespawnMarkerSchema, type Account, type Config, type ModelInfo, type UsageWindows } from "../lib/types.ts";
+import { CostLineSchema, JsonTextSchema, RespawnMarkerSchema, type Account, type ApiKey, type Config, type ModelInfo, type UsageWindows } from "../lib/types.ts";
 import { errorMessage, log } from "../lib/log.ts";
 
 const SUBCOMMANDS = new Set([
@@ -254,10 +254,11 @@ async function moveExhaustedSeat(seat: Account, sid: string, gate: MarkerGate, m
     const families = gatedFamilies(model, cfg.policy.switchModels);
     const until = seatBlockedUntil(seat.id, now, families, cfg);
     if (until == null || until <= gate.overriddenUntil) return false;
-    const decision = await evaluateAndMaybeSwap(claude, now, true, null, { seatId: seat.id, sessionFamilies: families, waiterId: sid, refused });
-    log("supervisor.seat_exhausted", { seat: seat.id.slice(0, 8), until, reason: decision.reason, account: decision.account?.id.slice(0, 8), waitUntil: decision.waitUntil });
-    if (decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
-      writeRespawnMarker({ session: { sid, launchedAt: gate.launchedAt, live: liveSessionId(sid) }, accountId: decision.account.id, waitUntil: decision.waitUntil ?? now, compact: true, origin: "seatwatch" });
+    const decision = await evaluateAndMaybeSwap(claude, now, true, null, { seatId: seat.id, sessionFamilies: families, waiterId: sid, refused, apiKeys: true });
+    log("supervisor.seat_exhausted", { seat: seat.id.slice(0, 8), until, reason: decision.reason, account: decision.account?.id.slice(0, 8), key: decision.apiKey?.id, waitUntil: decision.waitUntil });
+    const target = moveTarget(decision);
+    if (target) {
+      writeRespawnMarker({ session: { sid, launchedAt: gate.launchedAt, live: liveSessionId(sid) }, ...target, waitUntil: target.waitUntil ?? now, compact: true, origin: "seatwatch" });
     }
   } catch (e) {
     log("supervisor.seat_watch_error", { err: errorMessage(e) });
@@ -265,14 +266,54 @@ async function moveExhaustedSeat(seat: Account, sid: string, gate: MarkerGate, m
   return true;
 }
 
+async function moveKeySession(key: ApiKey, sid: string, gate: MarkerGate, model: ModelInfo | null, refused: string[], resumed: Set<string>): Promise<boolean> {
+  await foldCost(sid, key.id, resumed);
+  try {
+    if (usableApiKey(key.id) != null) return false;
+    const now = Date.now();
+    const cfg = loadConfig();
+    const families = gatedFamilies(model, cfg.policy.switchModels);
+    const decision = await evaluateAndMaybeSwap(claude, now, true, null, { seatId: null, sessionFamilies: families, waiterId: sid, refused, apiKeys: true, apiKeyId: key.id });
+    log("supervisor.key_watch", { key: key.id, reason: decision.reason, account: decision.account?.id.slice(0, 8), next: decision.apiKey?.id, waitUntil: decision.waitUntil });
+    const target = moveTarget(decision);
+    if (target && (target.waitUntil === undefined || target.waitUntil > gate.overriddenUntil)) {
+      writeRespawnMarker({ session: { sid, launchedAt: gate.launchedAt, live: liveSessionId(sid) }, ...target, waitUntil: target.waitUntil ?? now, compact: true, origin: "seatwatch" });
+    }
+  } catch (e) {
+    log("supervisor.key_watch_error", { err: errorMessage(e) });
+  }
+  return true;
+}
+
+function resolveLaunch(wanted: { accountId: string | null; apiKeyId: string | null } | null, now: number, model: ModelInfo | null): LaunchTarget | null {
+  if (wanted?.apiKeyId != null) {
+    const key = usableApiKey(wanted.apiKeyId);
+    if (key) return { account: null, apiKey: key };
+  } else if (wanted?.accountId != null) {
+    const id = wanted.accountId;
+    const account = loadAccounts(claudePool).accounts.find((a) => a.id === id);
+    if (account) return { account, apiKey: null };
+  }
+  return pickLaunch(now, model);
+}
+
+async function foldCost(sid: string, keyId: string | null, resumed: Set<string>): Promise<void> {
+  try {
+    await foldSessionCost(sid, keyId, resumed);
+  } catch (e) {
+    log("supervisor.cost_fold_failed", { err: errorMessage(e) });
+  }
+}
+
 function systemLine(sid: string, text: string): string {
   return `${JSON.stringify({ type: "system", subtype: "informational", content: text, level: "warning", uuid: crypto.randomUUID(), session_id: sid })}\n`;
 }
 
-function resumePrompt(input: { compacted: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"] }): string {
+function resumePrompt(input: { compacted: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"]; onKey: boolean }): string {
+  const where = input.onKey ? "on an Anthropic API key, because every pooled account is at its limit or the previous key ran out" : "on an account with quota headroom";
   const moved = input.compacted
-    ? "tokenmaxxing compacted this conversation and resumed the session on an account with quota headroom."
-    : "tokenmaxxing resumed this session on an account with quota headroom.";
+    ? `tokenmaxxing compacted this conversation and resumed the session ${where}.`
+    : `tokenmaxxing resumed this session ${where}.`;
   if (input.origin === "stop") {
     return `${moved} The previous turn finished before the move. If it waited on the user or completed the task, end this turn without restating it. If it waited on a background Bash task, Monitor, or Workflow run, relaunch that work, because the move ended it.`;
   }
@@ -283,8 +324,6 @@ function userLine(text: string): string {
   return `${JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text }] } })}\n`;
 }
 
-const STDOUT_QUIET_MS = 1000;
-
 const TaskLineSchema = z.discriminatedUnion("subtype", [
   z.looseObject({ type: z.literal("system"), subtype: z.literal("task_started"), task_id: z.string(), description: z.string(), session_id: z.string() }),
   z.looseObject({ type: z.literal("system"), subtype: z.literal("task_notification"), task_id: z.string() }),
@@ -304,11 +343,14 @@ function stoppedTaskLines(open: OpenTasks): string[] {
   return [...open].map(([id, task]) => `${JSON.stringify({ type: "system", subtype: "task_notification", task_id: id, status: "stopped", reason: "worker_restart", output_file: "", summary: `Stopped by a tokenmaxxing restart: ${task.description || id}`, uuid: crypto.randomUUID(), session_id: task.sessionId })}\n`);
 }
 
-function seatTee(seatId: string, model: ModelInfo | null, open: OpenTasks): (line: string) => void {
+function seatTee(seatId: string | null, model: ModelInfo | null, open: OpenTasks, costSid: string | null): (line: string) => void {
   let last: UsageWindows | null = null;
   return (line) => {
     const value = JsonTextSchema.safeParse(line).data;
     trackTask(open, value);
+    const cost = costSid == null ? null : (CostLineSchema.safeParse(value).data ?? null);
+    if (costSid != null && cost != null) writeSessionCost(costSid, cost);
+    if (seatId == null) return;
     const msg = parseStreamLine(value);
     if (msg?.windows) last = msg.windows;
     else if (msg?.type !== "assistant") return;
@@ -316,42 +358,6 @@ function seatTee(seatId: string, model: ModelInfo | null, open: OpenTasks): (lin
   };
 }
 
-function relayStdout(source: ReadableStream<Uint8Array>, onLine: (line: string) => void): () => 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 () => {
-    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 () => {
-    const exitedAt = Date.now();
-    while (!ended && (blocked || Date.now() - Math.max(readAt, exitedAt) < STDOUT_QUIET_MS)) await Bun.sleep(50);
-  };
-}
-
 const REPLAYED_REQUESTS = new Set(["initialize", "set_max_thinking_tokens", "set_model", "set_permission_mode"]);
 
 const RelayLineSchema = z.discriminatedUnion("type", [
@@ -508,7 +514,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
   });
 
   if (!info.manage || process.env[UNMANAGED_ENV]) {
-    const passthroughEnv = omit(childEnv, ["TOKENMAXXING_SUPERVISED", "TOKENMAXXING_SESSION_ID", "TOKENMAXXING_MODEL", "TOKENMAXXING_REFUSED"]);
+    const passthroughEnv = omit(childEnv, ["TOKENMAXXING_SUPERVISED", "TOKENMAXXING_SESSION_ID", "TOKENMAXXING_MODEL", "TOKENMAXXING_REFUSED", "TOKENMAXXING_API_KEY_ID"]);
     return runPassthrough({ real, argv, env: passthroughEnv, onSpawn: (p) => { child = p; } });
   }
 
@@ -536,6 +542,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
   pruneStaleSessions(Date.now());
 
   let launchArgs = resume ? ["--resume", sid, ...base] : ["--session-id", sid, ...base];
+  const resumed = new Set<string>(resume ? [sid] : []);
   let pendingTranscript = resume ? null : transcriptPath(sid);
 
   mkdirSync(paths.respawnDir, { recursive: true });
@@ -557,7 +564,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
   let firstLine: string | null = null;
   let respawns = 0;
   let overriddenUntil = 0;
-  let wanted: string | null = null;
+  let wanted: { accountId: string | null; apiKeyId: string | null } | null = null;
   let refused: string[] = [];
   let drainStdout: (() => Promise<void>) | null = null;
   try {
@@ -567,55 +574,62 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     const gate: MarkerGate = { launchedAt: Date.now(), overriddenUntil };
     const launched = await withLock(claudePool.lockFile, async () => {
       if (terminating) return null;
-      const picked = (wanted == null ? null : (loadAccounts(claudePool).accounts.find((a) => a.id === wanted) ?? null)) ?? pickSeat(gate.launchedAt, model);
-      log("supervisor.launch", { sid, respawns, seat: picked?.id.slice(0, 8) ?? null, args: launchArgs.join(" "), injected: firstLine !== null });
+      const target = resolveLaunch(wanted, gate.launchedAt, model);
+      const picked = target?.account ?? null;
+      const key = target?.apiKey ?? null;
+      log("supervisor.launch", { sid, respawns, seat: picked?.id.slice(0, 8) ?? null, key: key?.id, args: launchArgs.join(" "), injected: firstLine !== null });
       const open: OpenTasks = new Map();
-      const tee = stream && picked ? seatTee(picked.id, model, open) : null;
+      const costSid = existsSync(claudePool.apiKeysJson) ? sid : null;
+      const tee = stream && (picked || costSid != null) ? seatTee(picked?.id ?? null, model, open, costSid) : null;
+      const secret = key ? readApiKey(key) : null;
+      const extra: "pipe"[] = secret == null ? [] : ["pipe"];
+      const scrubbed = scrubCredEnv(childEnv);
       const spawned = Bun.spawn([real, ...launchArgs], {
-        stdin: relay === null ? "inherit" : "pipe",
-        stdout: tee === null ? "inherit" : "pipe",
-        stderr: "inherit",
+        stdio: [relay === null ? "inherit" : "pipe", tee === null ? "inherit" : "pipe", "inherit", ...extra],
         env: {
-          ...(picked ? { ...scrubCredEnv(childEnv), CLAUDE_SECURESTORAGE_CONFIG_DIR: storeDirFor(picked.id) } : childEnv),
+          ...(picked ? { ...scrubbed, CLAUDE_SECURESTORAGE_CONFIG_DIR: storeDirFor(picked.id) } : key ? apiKeyEnv(scrubbed, key) : childEnv),
           TOKENMAXXING_SUPERVISED: "1",
           TOKENMAXXING_SESSION_ID: sid,
           TOKENMAXXING_LAUNCHED_AT: String(gate.launchedAt),
           TOKENMAXXING_MODEL: effective.model ?? "",
           TOKENMAXXING_REFUSED: refused.join(","),
+          TOKENMAXXING_API_KEY_ID: key?.id ?? "",
         },
       });
       child = spawned;
+      if (secret != null) sendApiKey(spawned, secret);
       const drain = tee !== null && spawned.stdout instanceof ReadableStream ? relayStdout(spawned.stdout, tee) : null;
       if (relay !== null) relay.attach(spawned.stdin!, firstLine, pendingTranscript);
       firstLine = null;
-      if (picked) {
+      if (picked || key) {
         await recordPresenceOrStop({
           child: spawned,
           dir: paths.presenceDir,
           id: sid,
-          accountId: picked.id,
+          accountId: picked?.id ?? "",
+          ...(key ? { apiKeyId: key.id } : {}),
           event: "supervisor.presence_failed",
           message: "could not write the session presence file - refusing to run a session whose seat placement cannot see",
           savedTermios,
         });
       }
       releaseClaimLocked(sid);
-      return { child: spawned, seat: picked, drain, open };
+      return { child: spawned, seat: picked, key, drain, open };
     });
     if (launched == null) {
       await releaseClaim();
       return 143;
     }
 
-    const { child: proc, seat, open } = launched;
+    const { child: proc, seat, key, open } = launched;
     drainStdout = launched.drain;
     let seatCheckAt = 0;
     await raceMarkerOrExit({
       child: proc,
       tick: async () => {
         if (existsSync(marker) && (await consumableMarker(marker, gate)) != null) return true;
-        if (seat && !terminating && Date.now() >= seatCheckAt) {
-          const decided = await moveExhaustedSeat(seat, sid, gate, model, refused);
+        if ((seat || key) && !terminating && Date.now() >= seatCheckAt) {
+          const decided = seat ? await moveExhaustedSeat(seat, sid, gate, model, refused) : key ? await moveKeySession(key, sid, gate, model, refused, resumed) : false;
           seatCheckAt = Date.now() + (decided ? SEAT_RETRY_MS : SEAT_POLL_MS);
         }
         return false;
@@ -630,6 +644,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     });
     await drainStdout?.();
     drainStdout = null;
+    await foldCost(sid, key?.id ?? null, resumed);
 
     const m = !terminating && existsSync(marker) ? await consumableMarker(marker, gate) : null;
     if (m) {
@@ -638,7 +653,8 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       noticeSid = m.sessionId;
       for (const line of stoppedTaskLines(open)) process.stdout.write(line);
       const accounts = loadAccounts(claudePool).accounts;
-      const label = accounts.find((a) => a.id === m.accountId)?.label ?? m.accountId.slice(0, 8);
+      const nextKey = m.apiKeyId == null ? null : (loadApiKeys().keys.find((k) => k.id === m.apiKeyId) ?? null);
+      const label = m.apiKeyId != null ? `API key ${nextKey?.label ?? m.apiKeyId}` : (accounts.find((a) => a.id === m.accountId)?.label ?? m.accountId.slice(0, 8));
       const walledUntil = accounts.find((a) => a.id === seat?.id)?.enforcedUntil ?? 0;
       const transcript = findTranscript(m.sessionId);
       const resumable = transcript !== null;
@@ -646,34 +662,50 @@ export async function runSupervisor(argv: string[]): Promise<number> {
         for (const id of relay.replay()) process.stdout.write(controlErrorLine(id));
       }
       let compacted = false;
+      const compactKey = key != null && usableApiKey(key.id) != null ? key : null;
+      const compactOn = seat?.label ?? (compactKey ? `API key ${compactKey.label}` : null);
       if (m.compact && seat && resumable && walledUntil > Date.now()) {
         log("supervisor.compact_skipped", { sid: m.sessionId.slice(0, 8), seat: seat.id.slice(0, 8), until: walledUntil });
-      } else if (m.compact && seat && resumable) {
-        say(`\n\x1b[36m↻ tokenmaxxing: compacting the conversation on ${seat.label} before the move...\x1b[0m\n`, `tokenmaxxing: compacting the conversation on ${seat.label} before the move.`);
-        const compactEnv = { ...omit(scrubCredEnv(childEnv), ["TOKENMAXXING_SUPERVISED", "TOKENMAXXING_SESSION_ID", "TOKENMAXXING_LAUNCHED_AT", "TOKENMAXXING_MODEL", "TOKENMAXXING_REFUSED"]), TOKENMAXXING_PROBE: "1", CLAUDE_SECURESTORAGE_CONFIG_DIR: storeDirFor(seat.id) };
-        const outcome = await compactClaudeSession({ real, sid: m.sessionId, transcript, env: compactEnv, onSpawn: (p) => { child = p; } });
+      } else if (m.compact && compactOn != null && resumable) {
+        say(`\n\x1b[36m↻ tokenmaxxing: compacting the conversation on ${compactOn} before the move...\x1b[0m\n`, `tokenmaxxing: compacting the conversation on ${compactOn} before the move.`);
+        const baseEnv = { ...omit(scrubCredEnv(childEnv), ["TOKENMAXXING_SUPERVISED", "TOKENMAXXING_SESSION_ID", "TOKENMAXXING_LAUNCHED_AT", "TOKENMAXXING_MODEL", "TOKENMAXXING_REFUSED", "TOKENMAXXING_API_KEY_ID"]), TOKENMAXXING_PROBE: "1" };
+        const compactEnv = seat ? { ...baseEnv, CLAUDE_SECURESTORAGE_CONFIG_DIR: storeDirFor(seat.id) } : compactKey ? apiKeyEnv(baseEnv, compactKey) : baseEnv;
+        const compactSecret = seat == null && compactKey ? readApiKey(compactKey) : null;
+        const outcome = await compactClaudeSession({
+          real,
+          sid: m.sessionId,
+          transcript,
+          env: compactEnv,
+          keyPipe: compactSecret != null,
+          onSpawn: (p) => {
+            child = p;
+            if (compactSecret != null) sendApiKey(p, compactSecret);
+          },
+        });
         child = null;
         if (terminating) {
           await releaseClaim();
           return 143;
         }
-        log("supervisor.compact", { sid: m.sessionId.slice(0, 8), seat: seat.id.slice(0, 8), ok: outcome.ok, reason: outcome.ok ? undefined : outcome.reason });
+        log("supervisor.compact", { sid: m.sessionId.slice(0, 8), seat: seat?.id.slice(0, 8), key: compactKey?.id, ok: outcome.ok, reason: outcome.ok ? undefined : outcome.reason });
         if (!outcome.ok) say(`\x1b[33m   compaction did not land (${outcome.reason}) - resuming with the full context\x1b[0m\n`, `tokenmaxxing: compaction did not land; resuming with the full context. (${outcome.reason})`);
         compacted = outcome.ok;
       }
       if (m.waitUntil > Date.now()) {
         if (await countdownWait(label, m.waitUntil, { stream, say })) overriddenUntil = m.waitUntil;
       } else say(`\n\x1b[36m↻ tokenmaxxing: moving to ${label} - resuming...\x1b[0m\n`, `tokenmaxxing: moving to ${label} and resuming.`);
-      wanted = m.accountId;
+      wanted = m.apiKeyId != null ? { accountId: null, apiKeyId: m.apiKeyId } : { accountId: m.accountId, apiKeyId: null };
       refused = m.refused ?? refused;
       saveSessionFlags(m.sessionId, persistable, process.cwd());
-      const prompt = resumable ? resumePrompt({ compacted, origin: m.origin }) : null;
+      const prompt = resumable ? resumePrompt({ compacted, origin: m.origin, onKey: m.apiKeyId != null }) : null;
       firstLine = relay !== null && prompt !== null ? userLine(prompt) : null;
       pendingTranscript = resumable ? null : transcriptPath(m.sessionId);
+      if (resumable) resumed.add(m.sessionId);
       launchArgs = [resumable ? "--resume" : "--session-id", m.sessionId, ...(relay === null && prompt !== null ? [prompt] : []), ...persistable];
       continue;
     }
     clearPresence({ dir: paths.presenceDir, id: sid });
+    clearSessionCost(sid);
     await releaseClaim();
     log("supervisor.exit", { sid, respawns, code: proc.exitCode, signal: proc.signalCode, terminated: terminating || undefined });
     return exitStatus(proc);

package/src/lib/apikeys.ts

@@ -0,0 +1,142 @@
+import { chmodSync, closeSync, existsSync, mkdirSync, readFileSync, rmSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { countBy, isEqual, sortBy } from "es-toolkit";
+import { writeFileAtomic } from "./atomic.ts";
+import { withLock } from "./lock.ts";
+import { claudePool, optionalEnv, paths } from "./paths.ts";
+import { livingPresences } from "./presence.ts";
+import type { ApiKeyPool } from "./provider.ts";
+import { readJsonFile } from "./state.ts";
+import { ApiKeysIndexSchema, SessionCostSchema, type ApiKey, type ApiKeysIndex, type SessionCost } from "./types.ts";
+
+export const API_KEY_ENV = "TOKENMAXXING_API_KEY_ID";
+export const API_KEY_FD = 3;
+
+export function apiKeyEnv(env: Record<string, string | undefined>, key: ApiKey): Record<string, string | undefined> {
+  const header = key.workspaceId == null ? null : `anthropic-workspace-id: ${key.workspaceId}`;
+  const headers = header == null ? env.ANTHROPIC_CUSTOM_HEADERS : env.ANTHROPIC_CUSTOM_HEADERS ? `${env.ANTHROPIC_CUSTOM_HEADERS}\n${header}` : header;
+  return { ...env, CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR: String(API_KEY_FD), ...(headers != null ? { ANTHROPIC_CUSTOM_HEADERS: headers } : {}) };
+}
+
+export function readApiKey(key: ApiKey): string {
+  return `${readFileSync(apiKeySecretFor(key.id), "utf8").trim()}\n`;
+}
+
+export function sendApiKey(child: { stdio: readonly (number | null)[] }, secret: string): void {
+  const fd = child.stdio[API_KEY_FD];
+  if (fd == null) throw new Error(`the child has no descriptor ${API_KEY_FD} to receive the API key`);
+  try {
+    const written = writeSync(fd, secret);
+    if (written !== Buffer.byteLength(secret)) throw new Error(`wrote ${written} of ${Buffer.byteLength(secret)} bytes of the API key to descriptor ${API_KEY_FD}`);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export function apiKeySecretFor(id: string): string {
+  return join(paths.apiKeysDir, id);
+}
+
+export function loadApiKeys(): ApiKeysIndex {
+  if (!existsSync(claudePool.apiKeysJson)) return { version: 1, keys: [], baselines: {} };
+  return readJsonFile(claudePool.apiKeysJson, ApiKeysIndexSchema);
+}
+
+export function saveApiKeys(idx: ApiKeysIndex): void {
+  writeFileAtomic(claudePool.apiKeysJson, JSON.stringify(ApiKeysIndexSchema.parse(idx), null, 2) + "\n");
+}
+
+export function writeApiKeySecret(id: string, secret: string): void {
+  mkdirSync(paths.apiKeysDir, { recursive: true, mode: 0o700 });
+  chmodSync(paths.apiKeysDir, 0o700);
+  writeFileAtomic(apiKeySecretFor(id), secret);
+}
+
+export function removeApiKeySecret(id: string): void {
+  rmSync(apiKeySecretFor(id), { force: true });
+}
+
+export function creditLeft(k: ApiKey): number | null {
+  return k.creditUsd == null ? null : k.creditUsd - k.spentUsd;
+}
+
+export function keyUsable(k: ApiKey): boolean {
+  const left = creditLeft(k);
+  return k.refusedAt == null && (left == null || left > 0);
+}
+
+export function keySessions(): Map<string, number> {
+  const ids = livingPresences(paths.presenceDir).flatMap((p) => (p.apiKeyId == null ? [] : [p.apiKeyId]));
+  return new Map(Object.entries(countBy(ids, (id) => id)));
+}
+
+export function pickApiKey(keys: ApiKey[], sessions: Map<string, number>, exclude: string[]): ApiKey | null {
+  const candidates = keys.filter((k) => keyUsable(k) && !exclude.includes(k.id));
+  return sortBy(candidates, [(k) => (creditLeft(k) == null ? 1 : 0), (k) => -(creditLeft(k) ?? 0), (k) => sessions.get(k.id) ?? 0, (k) => k.addedAt])[0] ?? null;
+}
+
+function availableKeys(): ApiKey[] {
+  return loadApiKeys().keys.filter((k) => existsSync(apiKeySecretFor(k.id)));
+}
+
+export function usableApiKey(id: string): ApiKey | null {
+  const key = availableKeys().find((k) => k.id === id);
+  return key != null && keyUsable(key) ? key : null;
+}
+
+export function launchApiKey(): ApiKey | null {
+  return pickApiKey(availableKeys(), keySessions(), []);
+}
+
+export function liveApiKeyId(env: Record<string, string | undefined> = process.env): string | null {
+  return optionalEnv(API_KEY_ENV, env) ?? null;
+}
+
+export const claudeApiKeys: ApiKeyPool = {
+  liveId: () => liveApiKeyId(),
+  holds: (id) => usableApiKey(id) != null,
+  pick: (exclude) => pickApiKey(availableKeys(), keySessions(), exclude),
+};
+
+export async function refuseApiKey(id: string, now: number): Promise<boolean> {
+  return withLock(claudePool.lockFile, () => {
+    const idx = loadApiKeys();
+    const key = idx.keys.find((k) => k.id === id);
+    if (!key) return false;
+    key.refusedAt = now;
+    saveApiKeys(idx);
+    return true;
+  });
+}
+
+const costFileFor = (sid: string): string => join(paths.costDir, `${sid}.json`);
+
+export function writeSessionCost(sid: string, cost: SessionCost): void {
+  const file = costFileFor(sid);
+  if (existsSync(file) && isEqual(readJsonFile(file, SessionCostSchema), cost)) return;
+  writeFileAtomic(file, JSON.stringify(cost));
+}
+
+export function clearSessionCost(sid: string): void {
+  rmSync(costFileFor(sid), { force: true });
+}
+
+const BASELINE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+export async function foldSessionCost(sid: string, keyId: string | null, resumed: Set<string>): Promise<void> {
+  const file = costFileFor(sid);
+  if (!existsSync(file) || !existsSync(claudePool.apiKeysJson)) return;
+  const seen = readJsonFile(file, SessionCostSchema);
+  await withLock(claudePool.lockFile, () => {
+    const idx = loadApiKeys();
+    const prev = idx.baselines[seen.sessionId];
+    if (prev?.usd === seen.usd) return;
+    const delta = prev != null ? Math.max(0, seen.usd - prev.usd) : resumed.has(seen.sessionId) ? 0 : seen.usd;
+    const key = keyId == null ? undefined : idx.keys.find((k) => k.id === keyId);
+    if (key) key.spentUsd += delta;
+    const now = Date.now();
+    idx.baselines = Object.fromEntries(Object.entries(idx.baselines).filter(([, b]) => now - b.at <= BASELINE_RETENTION_MS));
+    idx.baselines[seen.sessionId] = { usd: seen.usd, at: now };
+    saveApiKeys(idx);
+  });
+}

package/src/lib/claude.ts

@@ -2,6 +2,7 @@ import { mkdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { countBy } from "es-toolkit";
 import { z } from "zod";
+import { claudeApiKeys, launchApiKey } from "./apikeys.ts";
 import { readItem, writeItem, deleteItem, isolatedTarget, readStore, storeTarget, claudeAiOauthOnly } from "./credstore.ts";
 import { CLAUDE_BIN, resolveRealBin, resolveVerifiedClaude } from "./claudebin.ts";
 import { activationHint, CHECK_JOB, ensurePathInRc, HUB_JOB, installSupervisor, managedShellRcSkipLines, shellRcPath } from "./install.ts";
@@ -17,7 +18,7 @@ import { claimSample, foldTee, landRead, readyToSample, runSample, sampleAccount
 import { clearUsageSnapshot, liveWaitClaims, loadAccounts, loadConfig, loadUsageSnapshot, pinBinOverride, readJsonFile, saveAccounts, type Harvest } from "./state.ts";
 import { saveTermios, restoreTermios } from "./tty.ts";
 import { claimResetGrant, fetchUsageDirect, gatedFamilies, mergeWindows, modelFromFlag, scrubCredEnv, windowsOf } from "./usage.ts";
-import { CredentialBlobSchema, JsonTextSchema, OAuthAccountSchema, type Account, type Config, type ModelInfo } from "./types.ts";
+import { CredentialBlobSchema, JsonTextSchema, OAuthAccountSchema, type Account, type ApiKey, type Config, type ModelInfo } from "./types.ts";
 import { c } from "../cli/render.ts";
 
 function liveId(): string | null {
@@ -25,7 +26,7 @@ function liveId(): string | null {
 }
 
 function presence(living = livingPresences(paths.presenceDir)): Map<string, number> {
-  const seats = new Map(living.map((s) => [s.id, s.accountId]));
+  const seats = new Map(living.filter((s) => s.apiKeyId == null).map((s) => [s.id, s.accountId]));
   for (const claim of liveWaitClaims(Date.now())) seats.set(claim.sessionId, claim.accountId);
   return new Map(Object.entries(countBy([...seats.values()], (id) => id)));
 }
@@ -138,7 +139,7 @@ async function storeUsable(a: Account): Promise<boolean> {
   }
 }
 
-export function pickSeat(now: number, model: ModelInfo | null, eligible: (a: Account) => boolean = () => true): Account | null {
+function seatContext(now: number, model: ModelInfo | null, eligible: (a: Account) => boolean): { candidates: Account[]; ctx: PickCtx; fallback: () => Account | null } {
   const cfg = loadConfig();
   const bars = thresholdBars(cfg);
   const idx = loadAccounts(claudePool);
@@ -148,12 +149,28 @@ export function pickSeat(now: number, model: ModelInfo | null, eligible: (a: Acc
   const seats = presence();
   const ctx: PickCtx = { now, thresholds: bars, currentId: null, families: gatedFamilies(model, cfg.policy.switchModels), seats };
   const candidates = idx.accounts.filter(eligible);
-  return (
-    pickBest(candidates, ctx) ??
+  const fallback = () =>
     pickWaitTarget(candidates, ctx, seats, MAX_WAITERS_PER_ACCOUNT, now + cfg.policy.maxWaitMs, now + 2 * cfg.policy.maxWaitMs)?.account ??
     pickEarliestReset(candidates, ctx)?.account ??
-    null
-  );
+    null;
+  return { candidates, ctx, fallback };
+}
+
+export function pickSeat(now: number, model: ModelInfo | null, eligible: (a: Account) => boolean = () => true): Account | null {
+  const { candidates, ctx, fallback } = seatContext(now, model, eligible);
+  return pickBest(candidates, ctx) ?? fallback();
+}
+
+export type LaunchTarget = { account: Account; apiKey: null } | { account: null; apiKey: ApiKey };
+
+export function pickLaunch(now: number, model: ModelInfo | null): LaunchTarget | null {
+  const { candidates, ctx, fallback } = seatContext(now, model, () => true);
+  const best = pickBest(candidates, ctx);
+  if (best) return { account: best, apiKey: null };
+  const key = launchApiKey();
+  if (key) return { account: null, apiKey: key };
+  const account = fallback();
+  return account ? { account, apiKey: null } : null;
 }
 
 export async function borrowClaudeSeat(pid: number): Promise<SeatBorrow> {
@@ -335,6 +352,7 @@ export const claude: Provider = {
   seats: "shared",
   waitsWhenDepleted: true,
   statusOnly: false,
+  apiKeys: claudeApiKeys,
   liveId,
   presence,
   gatedFamilies: (cfg) => {

package/src/lib/compact.ts

@@ -13,13 +13,12 @@ const PIPE_GRACE_MS = 2_000;
 
 const CompactBoundarySchema = z.looseObject({ type: z.literal("system"), subtype: z.literal("compact_boundary") });
 
-export async function compactClaudeSession(input: { real: string; sid: string; transcript: string; env: Record<string, string | undefined>; onSpawn: (child: Subprocess) => void }): Promise<CompactOutcome> {
+export async function compactClaudeSession(input: { real: string; sid: string; transcript: string; env: Record<string, string | undefined>; keyPipe: boolean; onSpawn: (child: Subprocess) => void }): Promise<CompactOutcome> {
   const offset = statSync(input.transcript).size;
+  const extra: "pipe"[] = input.keyPipe ? ["pipe"] : [];
   const p = Bun.spawn([input.real, "-p", "--resume", input.sid, "/compact"], {
     env: input.env,
-    stdin: "ignore",
-    stdout: "pipe",
-    stderr: "pipe",
+    stdio: ["ignore", "pipe", "pipe", ...extra],
     timeout: CLAUDE_COMPACT_KILL_MS,
     killSignal: "SIGKILL",
   });