tokenmaxxing 0.10.0 → 0.11.0

package/DESIGN.md

@@ -99,6 +99,8 @@ The decision engages at `five_hour >= 50%` (policy.greedySessionFloor): from the
 
 **v2:** projected-threshold pre-emption; a `UserPromptSubmit` guard that respawns *before* a turn starts when already over; Windows.
 
+**Shipped since (0.11.0):** a programmatic SDK surface (`src/sdk.ts`, the package's `exports["."]`) for pairing with the Claude Agent SDK - personal use across the owner's own pooled accounts. The Agent SDK reads credentials per subprocess spawn and has no statusLine, so the surface is boundary-driven: run the shared switch decision before a spawn (`ensureBestAccount`) and at Stop-hook turn boundaries (`stopHookCheck`), and hand the SDK a pinned real-claude path plus a full replacement env scrubbed of credential overrides (`pooledOptions`).
+
 **Later:** Codex as a second pool; tool-agnostic picker.
 
 **Non-goals:** an API/MITM proxy; reimplementing OAuth beyond the single refresh-grant call in the swap.

package/README.md

@@ -75,6 +75,31 @@ The **target** is chosen greedily off each account's cached windows: among usabl
 
 State lives entirely in `~/.config/tokenmaxxing/`. Per-account credentials follow the platform's Claude Code store: the login keychain on macOS (`tokenmaxxing-cred-<uuid8>` items, never plaintext on disk), 0600 files under `~/.config/tokenmaxxing/creds/` on Linux (the same plaintext model claude itself uses for `~/.claude/.credentials.json`).
 
+## Pairing with the Claude Agent SDK
+
+For agents you build on the [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk/overview) against **your own** pooled accounts, `tokenmaxxing` is importable as a library (your agent app must run under Bun: tokenmaxxing ships TypeScript source and uses `bun:ffi`):
+
+```ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { ensureBestAccount, pooledOptions, stopHookCheck } from "tokenmaxxing";
+
+await ensureBestAccount(); // run the switch decision before the spawn (swaps once it engages - see below)
+
+for await (const message of query({
+  prompt: "...",
+  options: {
+    ...pooledOptions(), // pinned real claude + scrubbed env -> the pooled live credential
+    hooks: { Stop: [{ hooks: [stopHookCheck] }] }, // re-decide at every turn boundary
+  },
+})) {
+  // capture the session id from the init message if you want `resume` across swaps
+}
+```
+
+The SDK reads credentials when it spawns the claude subprocess and has no statusLine, so none of the CLI-side supervisor machinery applies; the integration is boundary-driven instead. `ensureBestAccount()` runs the exact greedy decision the CLI hooks and timer run (screening bars, pace-pressure target, post-swap cooldown - all shared code); like them, it deliberately does nothing until the decision engages (the active session past `policy.greedySessionFloor`, or a bar crossed), so a fresh account rides instead of churning. `pooledOptions()` pins `pathToClaudeCodeExecutable` to the real claude binary and supplies a full replacement `env` with every ambient credential override (`ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, ...) scrubbed, so the subprocess resolves the pool's live credential and nothing else. The pooled surface requires the default Claude Code credential store: it fails fast if `CLAUDE_CONFIG_DIR` or `CLAUDE_SECURESTORAGE_CONFIG_DIR` is set in your app's environment, because a swap would write the live credential where those point while the spawned subprocess reads the default store. `stopHookCheck` re-runs the decision at turn boundaries; a swap it lands takes effect on the next subprocess spawn (it never yanks a mid-query token). If your app loads user settings (see the SDK's `settingSources`), the Stop hook `tokenmaxxing init` installed may already fire in SDK sessions too - `stopHookCheck` makes the check explicit and works when settings are restricted.
+
+This is for pooling **your own** subscription accounts in agents you run yourself - the same personal-use posture as the CLI. Anthropic does not allow third-party products to offer claude.ai login or rate limits, including agents built on the Agent SDK; don't ship this surface to third parties.
+
 ## Honest limitations
 
 - **One cold turn.** The first turn after resuming on a new account re-uploads context once (prompt cache is org-scoped).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Automatic Claude Code account switching: pool multiple accounts and hot-swap when quota fills, resuming your session on the fresh account.",
   "type": "module",
   "license": "MIT",
@@ -13,6 +13,10 @@
   "bin": {
     "tokenmaxxing": "./src/main.ts"
   },
+  "exports": {
+    ".": "./src/sdk.ts",
+    "./package.json": "./package.json"
+  },
   "files": [
     "src",
     "README.md",

package/src/lib/usage.ts

@@ -197,7 +197,7 @@ export function parseUsageText(text: string, now = Date.now()): UsageWindows | n
 /** Env-var identity/credential overrides the claude binary honors BEFORE its
  *  keychain lookup (verified 2.1.205). A probe MUST scrub every one of these or
  *  an ambient value silently meters the wrong account. */
-const CRED_ENV_OVERRIDES = [
+export const CRED_ENV_OVERRIDES = [
   "ANTHROPIC_API_KEY",
   "ANTHROPIC_AUTH_TOKEN",
   "CLAUDE_CODE_OAUTH_TOKEN",

package/src/sdk.ts

@@ -0,0 +1,110 @@
+// Programmatic surface for pairing tokenmaxxing with the Claude Code Agent SDK
+// (personal use across your own pooled accounts - user decision 2026-07-16).
+//
+// The Agent SDK spawns a claude CLI subprocess per query() and that subprocess
+// reads credentials at spawn time: no statusLine tee, no supervisor, no
+// mid-query hot-swap. So the integration is boundary-driven - run the switch
+// decision BEFORE a spawn so it lands on the best account, and again at
+// Stop-hook turn boundaries so the NEXT spawn does; a running subprocess keeps
+// its snapshotted token either way, which is exactly the clean-boundary
+// semantics the CLI supervisor enforces with markers.
+//
+// Nothing here imports the Agent SDK: the helpers return plain values that
+// spread structurally into its Options, so tokenmaxxing keeps its exact
+// dependency set (zod, es-toolkit, ky).
+
+import { z } from "zod";
+import { MAX_WRAP_DEPTH, WRAP_DEPTH_ENV, resolveRealClaude } from "./lib/claudebin.ts";
+import { evaluateAndMaybeSwap, type SwapDecision } from "./lib/decide.ts";
+import { CRED_ENV_OVERRIDES } from "./lib/usage.ts";
+import { log } from "./lib/log.ts";
+
+export { evaluateAndMaybeSwap };
+export type { SwapDecision };
+
+/**
+ * Run the same greedy pace-pressure decision the hooks and check timer run
+ * (never anticipatory: there is no supervisor to pause an SDK session, so a
+ * depleted pre-park would yank it onto a known-blocked account for nothing).
+ * Call it right before query() so the subprocess spawns on the best account.
+ */
+export async function ensureBestAccount(now = Date.now()): Promise<SwapDecision> {
+  return evaluateAndMaybeSwap(now, false);
+}
+
+/** The pinned real claude binary, for Options.pathToClaudeCodeExecutable.
+ *  Never the supervisor wrapper: an SDK subprocess is headless print mode, so
+ *  the wrapper's respawn machinery buys nothing and only adds recursion risk. */
+export function claudeExecutablePath(): string {
+  return resolveRealClaude();
+}
+
+/** The pooled surface requires the DEFAULT Claude Code credential store. An
+ *  ambient config-dir override desyncs the two sides of a swap on Linux: the
+ *  swap (running in THIS process) writes the live credential where these vars
+ *  point (credDir() honors them), while the scrubbed subprocess reads the
+ *  default store - so the subprocess silently runs on a stale or absent
+ *  credential. Fail fast on both platforms rather than platform-split the
+ *  behavior (adversarial review catch, 2026-07-16). */
+const AMBIENT_STORE_VARS = ["CLAUDE_SECURESTORAGE_CONFIG_DIR", "CLAUDE_CONFIG_DIR"] as const;
+
+/**
+ * The env an SDK-spawned claude must run under to meter the POOLED live
+ * credential: every ambient credential override is scrubbed (claude honors
+ * them BEFORE its keychain/file lookup, so one inherited ANTHROPIC_API_KEY
+ * silently meters the wrong account), and the wrap depth is preset to the cap
+ * so a poisoned claudeBin pin that leads back into the tokenmaxxing wrapper
+ * aborts on first entry instead of fork-bombing.
+ *
+ * Returns a FULL environment, not a patch: the Agent SDK's Options.env
+ * REPLACES the subprocess env rather than merging over process.env (verified
+ * against the official TS reference 2026-07-16), which is what makes deleting
+ * keys from this copy effective.
+ */
+export function pooledSpawnEnv(): Record<string, string> {
+  for (const k of AMBIENT_STORE_VARS) {
+    if (process.env[k]) {
+      throw new Error(
+        `${k} is set: the pooled SDK surface requires the default Claude Code credential store (a swap writes the live credential where ${k} points, while the spawned subprocess reads the default store). Unset it in the process running tokenmaxxing.`,
+      );
+    }
+  }
+  const env: Record<string, string> = { ...process.env, [WRAP_DEPTH_ENV]: String(MAX_WRAP_DEPTH) };
+  for (const k of CRED_ENV_OVERRIDES) delete env[k];
+  return env;
+}
+
+const PooledOptionsSchema = z.object({
+  pathToClaudeCodeExecutable: z.string(),
+  env: z.record(z.string(), z.string()),
+});
+export type PooledOptions = z.infer<typeof PooledOptionsSchema>;
+
+/** Options fragment to spread into the Agent SDK's Options. */
+export function pooledOptions(): PooledOptions {
+  return PooledOptionsSchema.parse({
+    pathToClaudeCodeExecutable: claudeExecutablePath(),
+    env: pooledSpawnEnv(),
+  });
+}
+
+/**
+ * Agent SDK Stop-hook callback (structurally matches HookCallback; the args
+ * are irrelevant here; `{}` is the documented no-op output). Runs the switch
+ * decision at the turn boundary; a swap landed here takes effect on the next
+ * subprocess spawn. Errors are caught LOUDLY (stderr + log), not rethrown:
+ * the SDK hooks reference states an unhandled exception can interrupt the
+ * agent (verified 2026-07-16), and aborting the caller's turn because a
+ * switch check failed costs more than riding out the current account. Call
+ * ensureBestAccount() directly where a broken pool should throw.
+ */
+export async function stopHookCheck(): Promise<Record<string, never>> {
+  try {
+    await evaluateAndMaybeSwap(Date.now(), false);
+  } catch (e) {
+    const err = String((e as Error).message ?? e);
+    console.error(`tokenmaxxing: switch check failed at turn boundary: ${err}`);
+    log("sdk.stop_error", { err });
+  }
+  return {};
+}