tokenmaxxing 1.6.0 → 1.8.0

package/agent-plugin/skills/sdk-pairing/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: sdk-pairing
+description: Pair tokenmaxxing with the Claude Agent SDK (ensureBestAccount, pooledOptions, stopHookCheck). Use when building or debugging Bun agents that spawn Claude through the pooled credential store.
+---
+
+# SDK pairing
+
+Import from the package root (`tokenmaxxing` → `src/sdk.ts`). Bun only.
+
+```ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { ensureBestAccount, pooledOptions, stopHookCheck } from "tokenmaxxing";
+
+await ensureBestAccount();
+for await (const message of query({
+  prompt: "...",
+  options: {
+    ...pooledOptions(),
+    hooks: { Stop: [{ hooks: [stopHookCheck] }] },
+  },
+})) {
+  // capture session id from init for resume across swaps
+}
+```
+
+## Rules
+
+- Call `ensureBestAccount()` before each `query()` spawn (no mid-query hot-swap).
+- `pooledOptions()` pins the real claude binary and a full replacement env with credential overrides scrubbed. It throws if `CLAUDE_CONFIG_DIR` or `CLAUDE_SECURESTORAGE_CONFIG_DIR` is set.
+- `stopHookCheck` re-decides at turn boundaries; errors are swallowed so a broken check does not abort the turn.
+- Own-accounts only (see terms docs). Offering pooled subscription logins to third parties is a ToS problem.
+
+See [references/sdk.md](references/sdk.md).

package/agent-plugin/skills/sdk-pairing/references/sdk.md

@@ -0,0 +1,6 @@
+# SDK references
+
+- `src/sdk.ts` (self-documenting header)
+- `docs/content/docs/sdk.mdx`
+- `docs/content/docs/terms.mdx`
+- `.memory/agent-sdk-auth-surface.md`

package/agent-plugin/skills/switching-policy/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: switching-policy
+description: Explain and apply tokenmaxxing switch policy (greedy vs hard path, pace pressure, Layer 2 wall squeeze Claude-only, model-family matching). Use before pool_switch, pool_check, or when changing thresholds.
+---
+
+# Switching policy
+
+## Vocabulary
+
+- **Engaged**: session used >= `policy.greedySessionFloor` (default 50) or any hard/screening bar crossed.
+- **GREEDY path**: engaged but under every bar. Rank all accounts by pace pressure; keep seat on best-or-tie (`currentWins`); else swap to strictly better. Never depleted-waits or pre-parks.
+- **HARD path**: a screening bar crossed. Swap to best usable target; if none, Layer 2 wall logic (Claude only).
+- **Pace pressure**: remaining weekly percent / time to weekly reset (highest first). Not most-remaining.
+- **Effective bars**: `effectiveBars(cfg)` = thresholds minus `policy.projectionMargin`. Trigger and screening must share these bars or swaps ping-pong.
+
+## Layer 2 (Claude only)
+
+When the hard path finds no usable target, judge against the wall (`hardThresholds` minus margin). Under-wall seat HOLDS; walled seat swaps to best under-wall sibling. Codex has no Layer 2 last-drop swap (cannot hot-adopt).
+
+## Model matching
+
+Match model families by exact token after splitting id/display on spaces, dots, and hyphens (`familyTokens` / `matchedFamily` in `src/lib/usage.ts`). Never exact full display strings (names drift: "Fable" / "Fable 5"). Unmeasured usage is unknown and ranks last, never 0 / first. Per-model weekly caps: Sonnet and Fable exist; only Fable gates a switch by default (`policy.switchModels`).
+
+## Agent actions
+
+- Explain with this skill; mutate only via MCP `pool_switch` / `pool_check` with user approval, `confirm=true`, and `TOKENMAXXING_AGENT_MUTATIONS=1`.
+- Do not reintroduce Stop-hook text-sniffing limit failsafes.
+
+See [references/policy.md](references/policy.md).

package/agent-plugin/skills/switching-policy/references/policy.md

@@ -0,0 +1,7 @@
+# Policy sources
+
+- `docs/content/docs/switching.mdx`
+- `src/lib/decide.ts`, `src/lib/picker.ts` (inline rationale)
+- `.memory/switch-policy-pace-pressure.md`
+
+Default screening bars: session 95, weekly 98. Wall defaults 100. Cooldown 45s on the automatic path after a swap.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.6.0",
+  "version": "1.8.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",
@@ -19,6 +19,7 @@
   },
   "files": [
     "src",
+    "agent-plugin",
     "README.md",
     "DESIGN.md"
   ],
@@ -41,10 +42,7 @@
     "typescript": "^5.6.0"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.214",
-    "@chat-adapter/slack": "^4.34.0",
-    "@chat-adapter/state-memory": "^4.34.0",
-    "chat": "^4.34.0",
+    "@modelcontextprotocol/sdk": "1.29.0",
     "es-toolkit": "^1.49.0",
     "ky": "^2.0.2",
     "zod": "^4.4.3"

package/src/cli/codexinit.ts

@@ -11,7 +11,7 @@ import { codexIdentityOf, readLiveCodexAuth, writeParkedCodexAuth } from "../lib
 import { CodexUsageReadError, fetchCodexUsage } from "../lib/codexusage.ts";
 import { loadCodexAccounts, saveCodexAccounts } from "../lib/codexstate.ts";
 import { loadConfig, pinBinOverride } from "../lib/state.ts";
-import { installCodexSupervisor, codexSupervisorLink, ensurePathInRc, shellRcPath } from "../lib/install.ts";
+import { installCodexSupervisor, codexSupervisorLink, ensurePathInRc, managedShellRcSkipLines, shellRcPath } from "../lib/install.ts";
 import { withLock } from "../lib/lock.ts";
 import { presentCodexAccountIds } from "../lib/codexpresence.ts";
 import { codexCredItemFor, codexPaths } from "../lib/paths.ts";
@@ -137,7 +137,16 @@ export async function cmdCodexInit(): Promise<number> {
 
   installCodexSupervisor();
   const rc = shellRcPath();
-  if (rc) ensurePathInRc(rc);
+  if (rc) {
+    const pathOutcome = ensurePathInRc(rc);
+    if (pathOutcome === "skipped") {
+      const hint = managedShellRcSkipLines();
+      console.log();
+      console.log(c.yellow(`⚠ ${hint.headline}`));
+      console.log(c.yellow(`  ${hint.detail}`));
+      console.log(c.yellow(`  ${hint.exportLine}`));
+    }
+  }
 
   console.log();
   console.log(`${c.green("✓")} imported codex account ${c.bold(account.label)} (${account.planType ?? "?"})`);

package/src/cli/init.ts

@@ -8,14 +8,15 @@ import { refreshCredential, isAccessTokenExpiring, fetchTokenOrg } from "../lib/
 import { withClaudeRefreshLock } from "../lib/claudelock.ts";
 import { loadAccounts, saveAccounts, loadConfig, pinBinOverride } from "../lib/state.ts";
 import { withLock } from "../lib/lock.ts";
-import { installSupervisor, shellRcPath, ensurePathInRc, timerActivationHint, type InstallOutcome } from "../lib/install.ts";
+import { installSupervisor, shellRcPath, ensurePathInRc, managedShellRcSkipLines, timerActivationHint, type InstallOutcome } from "../lib/install.ts";
 import { resolveVerifiedClaude } from "../lib/claudebin.ts";
 import { credItemFor, paths } from "../lib/paths.ts";
 import { CredentialBlobSchema, type Account } from "../lib/types.ts";
 import { c, claudeTierLabel } from "./render.ts";
 
 /** Put the supervisor bin dir on PATH via the user's shell rc (idempotent).
- *  Falls back to the manual instruction when the shell is unknown. */
+ *  Falls back to the manual instruction when the shell is unknown or the rc
+ *  target is immutable (Home Manager / nix-store). */
 function ensurePathAhead(): void {
   const rc = shellRcPath();
   if (!rc) {
@@ -24,7 +25,12 @@ function ensurePathAhead(): void {
   }
   const outcome = ensurePathInRc(rc);
   if (outcome === "added") console.log(`${c.green("✓")} added ${paths.binDir} to PATH in ${rc} - restart your shell (or \`source ${rc}\`)`);
-  else console.log(c.yellow(`⚠ PATH line already in ${rc} - restart your shell to pick it up`));
+  else if (outcome === "skipped") {
+    const hint = managedShellRcSkipLines();
+    console.log(c.yellow(`⚠ ${hint.headline}`));
+    console.log(c.yellow(`  ${hint.detail}`));
+    console.log(c.yellow(`  ${hint.exportLine}`));
+  } else console.log(c.yellow(`⚠ PATH line already in ${rc} - restart your shell to pick it up`));
 }
 
 function reportTimer(out: InstallOutcome): void {

package/src/cli/relay.ts

@@ -0,0 +1,323 @@
+// `tokenmaxxing relay` - host-agnostic durable tmux relay companion.
+
+import { cwd } from "node:process";
+import { z } from "zod";
+import { c } from "./render.ts";
+import {
+  DEFAULT_RELAY_CONFIG,
+  loadRelayConfig,
+  mergeRelayConfigFile,
+  writeRelayConfig,
+  type RelayConfigFile,
+} from "../lib/relay/config.ts";
+import { runDecide } from "../lib/relay/decide.ts";
+import { destroySession, gcSessions, statusRows } from "../lib/relay/gc.ts";
+import { installRelayHosts, type InstallTarget } from "../lib/relay/install.ts";
+import { parsePermissionMode, tryParsePermissionMode } from "../lib/relay/modes.ts";
+import { runTurn } from "../lib/relay/turn.ts";
+import { setLivePermissionMode } from "../lib/relay/worker.ts";
+import { existsSync, readFileSync } from "node:fs";
+import { paths } from "../lib/paths.ts";
+
+function printHelp(): void {
+  console.log(`${c.bold("tokenmaxxing relay")} - durable tmux workers for host agents
+
+  ${c.cyan("relay turn")} [--worker claude|codex] [--session <uuid>] [--cwd <dir>]
+              [--permission-mode <mode>] [prompt...]
+              Ensure session, send prompt (argv or stdin), wait for turn-done or permission-needed
+  ${c.cyan("relay decide")} --session <uuid> [--request <id>] --approve|--deny [--no-wait]
+              Approve or deny a pending permission ping; by default wait for the next marker
+  ${c.cyan("relay set-permission-mode")} --session <uuid> --permission-mode <mode>
+              Change the live worker permission mode
+  ${c.cyan("relay status")} [--session <uuid>]
+              Inspect relay sessions
+  ${c.cyan("relay destroy")} --session <uuid>
+              Tear down one session (exact tmux name)
+  ${c.cyan("relay gc")}
+              Reap dead or idle sessions (idleTtlMs)
+  ${c.cyan("relay install")} [--target cursor|claude|all]
+              Write agent templates and merge tokenmaxxing-owned hook keys
+  ${c.cyan("relay config")} [get|set|show]
+              Inspect or edit $TOKENMAXXING_HOME/relay.json
+
+  Permission modes (Claude worker): default|acceptEdits|plan|auto|dontAsk|bypassPermissions
+  Alias: manual → default. Default in relay.json: auto.
+  Codex maps those names onto --sandbox / --ask-for-approval.`);
+}
+
+type FlagMap = {
+  worker?: "claude" | "codex";
+  session?: string;
+  cwd?: string;
+  permissionMode?: string;
+  request?: string;
+  approve?: boolean;
+  deny?: boolean;
+  noWait?: boolean;
+  target?: string;
+  positionals: string[];
+};
+
+function parseFlags(args: string[]): FlagMap {
+  const out: FlagMap = { positionals: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--worker") {
+      const v = z.enum(["claude", "codex"]).parse(args[++i]);
+      out.worker = v;
+    } else if (a.startsWith("--worker=")) {
+      out.worker = z.enum(["claude", "codex"]).parse(a.slice("--worker=".length));
+    } else if (a === "--session") {
+      out.session = z.string().min(1).parse(args[++i]);
+    } else if (a.startsWith("--session=")) {
+      out.session = a.slice("--session=".length);
+    } else if (a === "--cwd") {
+      out.cwd = z.string().min(1).parse(args[++i]);
+    } else if (a.startsWith("--cwd=")) {
+      out.cwd = a.slice("--cwd=".length);
+    } else if (a === "--permission-mode") {
+      out.permissionMode = z.string().min(1).parse(args[++i]);
+    } else if (a.startsWith("--permission-mode=")) {
+      out.permissionMode = a.slice("--permission-mode=".length);
+    } else if (a === "--request") {
+      out.request = z.string().min(1).parse(args[++i]);
+    } else if (a.startsWith("--request=")) {
+      out.request = a.slice("--request=".length);
+    } else if (a === "--approve") {
+      out.approve = true;
+    } else if (a === "--deny") {
+      out.deny = true;
+    } else if (a === "--no-wait") {
+      out.noWait = true;
+    } else if (a === "--target") {
+      out.target = z.string().min(1).parse(args[++i]);
+    } else if (a.startsWith("--target=")) {
+      out.target = a.slice("--target=".length);
+    } else if (a === "--help" || a === "-h") {
+      out.positionals.push(a);
+    } else if (a.startsWith("-")) {
+      throw new Error(`unknown flag: ${a}`);
+    } else {
+      out.positionals.push(a);
+    }
+  }
+  return out;
+}
+
+async function readPrompt(flags: FlagMap): Promise<string> {
+  if (flags.positionals.length > 0) return flags.positionals.join(" ");
+  if (process.stdin.isTTY) return "";
+  const chunks: Uint8Array[] = [];
+  for await (const chunk of Bun.stdin.stream()) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function cmdTurn(args: string[]): Promise<number> {
+  const flags = parseFlags(args);
+  if (flags.positionals.includes("--help") || flags.positionals.includes("-h")) {
+    printHelp();
+    return 0;
+  }
+  const mode = flags.permissionMode != null
+    ? parsePermissionMode({ raw: flags.permissionMode })
+    : undefined;
+  const prompt = await readPrompt(flags);
+  const result = await runTurn({
+    sessionId: flags.session,
+    worker: flags.worker,
+    permissionMode: mode,
+    cwd: flags.cwd ?? cwd(),
+    prompt,
+  });
+  process.stdout.write(result.stdout);
+  return result.exitCode;
+}
+
+async function cmdDecide(args: string[]): Promise<number> {
+  const flags = parseFlags(args);
+  if (flags.session == null) {
+    console.error(c.red("relay decide requires --session <uuid>"));
+    return 1;
+  }
+  if (flags.approve === true && flags.deny === true) {
+    console.error(c.red("pass only one of --approve or --deny"));
+    return 1;
+  }
+  if (flags.approve !== true && flags.deny !== true) {
+    console.error(c.red("relay decide requires --approve or --deny"));
+    return 1;
+  }
+  const result = await runDecide({
+    sessionId: flags.session,
+    requestId: flags.request,
+    approve: flags.approve === true,
+    wait: flags.noWait !== true,
+    cwd: flags.cwd ?? cwd(),
+  });
+  if (result.turn != null) {
+    process.stdout.write(result.turn.stdout);
+    return result.turn.exitCode;
+  }
+  console.log(`decision written: ${result.requestId} (${flags.approve ? "approve" : "deny"})`);
+  return 0;
+}
+
+async function cmdSetPermissionMode(args: string[]): Promise<number> {
+  const flags = parseFlags(args);
+  if (flags.session == null || flags.permissionMode == null) {
+    console.error(c.red("relay set-permission-mode requires --session and --permission-mode"));
+    return 1;
+  }
+  const mode = parsePermissionMode({ raw: flags.permissionMode });
+  const entry = await setLivePermissionMode({ sessionId: flags.session, permissionMode: mode });
+  console.log(`session: ${entry.sessionId}`);
+  console.log(`permission-mode: ${entry.permissionMode}`);
+  return 0;
+}
+
+function cmdStatus(args: string[]): number {
+  const flags = parseFlags(args);
+  const rows = statusRows();
+  const filtered = flags.session != null
+    ? rows.filter((r) => r.sessionId === flags.session)
+    : rows;
+  if (filtered.length === 0) {
+    console.log(c.dim("(no relay sessions)"));
+    return 0;
+  }
+  for (const row of filtered) {
+    const alive = row.tmuxAlive ? c.green("up") : c.red("down");
+    console.log(
+      `${row.sessionId}  ${row.worker}  ${row.permissionMode}  ${row.state}  tmux=${alive}  ${row.tmuxName}`,
+    );
+  }
+  return 0;
+}
+
+async function cmdDestroy(args: string[]): Promise<number> {
+  const flags = parseFlags(args);
+  if (flags.session == null) {
+    console.error(c.red("relay destroy requires --session <uuid>"));
+    return 1;
+  }
+  const ok = await destroySession({ sessionId: flags.session });
+  if (!ok) {
+    console.error(c.red(`relay session not found: ${flags.session}`));
+    return 1;
+  }
+  console.log(`destroyed ${flags.session}`);
+  return 0;
+}
+
+async function cmdGc(): Promise<number> {
+  const result = await gcSessions();
+  console.log(`reaped ${result.reaped.length}; kept ${result.kept.length}`);
+  for (const id of result.reaped) console.log(`  reaped ${id}`);
+  return 0;
+}
+
+function cmdInstall(args: string[]): number {
+  const flags = parseFlags(args);
+  const target = z.enum(["cursor", "claude", "all"]).catch("all").parse(flags.target ?? "all") as InstallTarget;
+  const result = installRelayHosts({ target });
+  console.log(`agents: ${result.agentsWritten.length}`);
+  for (const p of result.agentsWritten) console.log(`  ${p}`);
+  console.log(`skill: ${result.skillWritten ? "written" : "skipped"}`);
+  console.log(`hooks: ${result.hooksMerged.length}`);
+  for (const p of result.hooksMerged) console.log(`  ${p}`);
+  return 0;
+}
+
+function cmdConfig(args: string[]): number {
+  const sub = args[0] ?? "show";
+  if (sub === "show" || sub === "get" && args[1] == null) {
+    const cfg = loadRelayConfig();
+    console.log(c.dim(`relay.json: ${paths.relayJson}`));
+    console.log(JSON.stringify(cfg, null, 2));
+    return 0;
+  }
+  if (sub === "get") {
+    const key = args[1];
+    if (key == null) {
+      console.error(c.red("relay config get <key>"));
+      return 1;
+    }
+    const cfg = loadRelayConfig() as Record<string, unknown>;
+    if (!(key in cfg)) {
+      console.error(c.red(`unknown key: ${key}`));
+      return 1;
+    }
+    console.log(JSON.stringify(cfg[key]));
+    return 0;
+  }
+  if (sub === "set") {
+    const key = args[1];
+    const valueText = args[2];
+    if (key == null || valueText == null) {
+      console.error(c.red("relay config set <key> <value>"));
+      return 1;
+    }
+    let value: unknown;
+    try {
+      value = JSON.parse(valueText);
+    } catch {
+      value = valueText;
+    }
+    if (key === "defaultPermissionMode") {
+      const mode = tryParsePermissionMode({ raw: String(value) });
+      if (mode == null) {
+        console.error(c.red(`invalid permission mode: ${value}`));
+        return 1;
+      }
+      value = mode;
+    }
+    const patch = { [key]: value } as RelayConfigFile;
+    const next = mergeRelayConfigFile({ patch });
+    console.log(`${key}: ${JSON.stringify((next as Record<string, unknown>)[key])}`);
+    return 0;
+  }
+  if (sub === "init") {
+    if (!existsSync(paths.relayJson)) {
+      writeRelayConfig({ file: {} });
+      console.log(`wrote defaults-capable ${paths.relayJson}`);
+    } else {
+      console.log(`already exists: ${paths.relayJson}`);
+      console.log(readFileSync(paths.relayJson, "utf8"));
+    }
+    console.log(c.dim(`effective defaultPermissionMode=${DEFAULT_RELAY_CONFIG.defaultPermissionMode}`));
+    return 0;
+  }
+  console.error(c.red(`unknown relay config subcommand: ${sub}`));
+  return 1;
+}
+
+export async function cmdRelay(args: string[]): Promise<number> {
+  const sub = args[0];
+  if (sub == null || sub === "--help" || sub === "-h" || sub === "help") {
+    printHelp();
+    return 0;
+  }
+  const rest = args.slice(1);
+  switch (sub) {
+    case "turn":
+      return cmdTurn(rest);
+    case "decide":
+      return cmdDecide(rest);
+    case "set-permission-mode":
+      return cmdSetPermissionMode(rest);
+    case "status":
+      return cmdStatus(rest);
+    case "destroy":
+      return cmdDestroy(rest);
+    case "gc":
+      return cmdGc();
+    case "install":
+      return cmdInstall(rest);
+    case "config":
+      return cmdConfig(rest);
+    default:
+      console.error(c.red(`unknown relay command: ${sub}`));
+      printHelp();
+      return 2;
+  }
+}

package/src/entries/codexstophook.ts

@@ -25,6 +25,9 @@ import { loadConfig } from "../lib/state.ts";
 import { effectiveBars } from "../lib/picker.ts";
 import { CODEX_SUPERVISOR_ID_ENV } from "./codexsupervisor.ts";
 import { CodexReconcileMarkerSchema, CodexRespawnMarkerSchema, CodexStopStdinSchema, type CodexAccount } from "../lib/types.ts";
+import { writeTurnDoneMarker } from "../lib/relay/markers.ts";
+import { registryHas } from "../lib/relay/registry.ts";
+import { RELAY_SESSION_ENV } from "../lib/relay/worker.ts";
 import { log } from "../lib/log.ts";
 
 const SupervisorIdSchema = z.string().min(1).optional().catch(undefined);
@@ -138,6 +141,13 @@ export async function handleCodexStop(input: { rawStdin: string }): Promise<void
   const sessionId = parsed.success ? (parsed.data.session_id ?? null) : null;
 
   try {
+    // Additive relay turn-done marker (never writes into respawn/).
+    const relaySid = process.env[RELAY_SESSION_ENV];
+    if (relaySid != null && registryHas({ sessionId: relaySid })) {
+      writeTurnDoneMarker({ sessionId: relaySid, source: "codex-stop" });
+      log("codexstop.relay_turn_done", { session: relaySid.slice(0, 8) });
+    }
+
     // No supervisor = no decision AT ALL, checked before evaluate can swap:
     // hooks.json is global, so this hook also fires in sessions launched
     // around the PATH shim (IDE extension, absolute path), and a swap with