tokenmaxxing 1.6.0 → 1.7.0

package/src/entries/mcp.ts

@@ -0,0 +1,288 @@
+// Stdio MCP entry for the portable Agent Plugin (agent-plugin/).
+// Tools wrap existing CLI commands. stdout is reserved for MCP JSON-RPC, so
+// every CLI call captures console.log / console.error and returns the text.
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { cmdLs } from "../cli/ls.ts";
+import { cmdStatus } from "../cli/status.ts";
+import { cmdDoctor } from "../cli/doctor.ts";
+import { cmdConfig } from "../cli/config.ts";
+import { cmdSwitch } from "../cli/switch.ts";
+import { cmdCodexSwitch } from "../cli/codexswitch.ts";
+import { cmdCheck } from "../cli/check.ts";
+
+const MUTATIONS_ENV = "TOKENMAXXING_AGENT_MUTATIONS";
+const PACKAGE_ROOT = join(import.meta.dir, "../..");
+
+function packageVersion(): string {
+  try {
+    const raw = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")) as { version?: string };
+    return raw.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+/** Refuse ambient Claude store overrides the same way the CLI and SDK do. */
+export function refuseAmbientStoreEnv(): string | null {
+  const nonEmpty = (v: string | undefined) => (v != null && v !== "" ? v : null);
+  return nonEmpty(process.env.CLAUDE_SECURESTORAGE_CONFIG_DIR) ?? nonEmpty(process.env.CLAUDE_CONFIG_DIR);
+}
+
+/** Redact token-shaped spans so tool results never echo credentials. */
+export function scrubSecrets(text: string): string {
+  return text
+    .replace(/\b(Bearer\s+)[A-Za-z0-9._\-+/=]+/gi, "$1[redacted]")
+    .replace(/\b(sk-ant-[A-Za-z0-9_-]+)\b/g, "[redacted]")
+    .replace(/\b(accessToken|refreshToken|claudeAiOauth)\b\s*[:=]\s*["']?[^"'}\s,]+/gi, "$1=[redacted]");
+}
+
+type CaptureResult = { code: number; stdout: string; stderr: string };
+
+/** Serialize captureCli: console.log/error are process-global, so concurrent
+ *  tool calls would interleave stdout into each other and corrupt JSON-RPC. */
+let captureChain: Promise<unknown> = Promise.resolve();
+
+/** Run a CLI cmd while keeping stdout clean for the MCP transport. */
+export async function captureCli(run: () => number | Promise<number>): Promise<CaptureResult> {
+  const job = async (): Promise<CaptureResult> => {
+    const out: string[] = [];
+    const err: string[] = [];
+    const joinArgs = (args: unknown[]) => args.map((a) => (typeof a === "string" ? a : String(a))).join(" ");
+    const log = console.log;
+    const error = console.error;
+    console.log = (...args: unknown[]) => { out.push(joinArgs(args)); };
+    console.error = (...args: unknown[]) => { err.push(joinArgs(args)); };
+    try {
+      const code = await run();
+      return { code, stdout: out.join("\n"), stderr: err.join("\n") };
+    } finally {
+      console.log = log;
+      console.error = error;
+    }
+  };
+  const next = captureChain.then(job, job);
+  captureChain = next.then(
+    () => undefined,
+    () => undefined,
+  );
+  return next;
+}
+
+function textResult(input: { text: string; isError?: boolean }) {
+  return {
+    content: [{ type: "text" as const, text: scrubSecrets(input.text) }],
+    ...(input.isError ? { isError: true } : {}),
+  };
+}
+
+function formatCapture(cap: CaptureResult): string {
+  const parts: string[] = [];
+  if (cap.stdout) parts.push(cap.stdout);
+  if (cap.stderr) parts.push(cap.stderr);
+  parts.push(`exit ${cap.code}`);
+  return parts.join("\n").trimEnd();
+}
+
+export function mutationsEnabled(): boolean {
+  return process.env[MUTATIONS_ENV] === "1";
+}
+
+function mutationDenied(confirm: boolean): string | null {
+  if (!confirm) {
+    return `Mutating tools require confirm=true. Also set ${MUTATIONS_ENV}=1 in the MCP server environment after the user approves.`;
+  }
+  if (!mutationsEnabled()) {
+    return `Mutations are disabled. Set ${MUTATIONS_ENV}=1 in the MCP server environment only after the user explicitly approves a pool mutation.`;
+  }
+  return null;
+}
+
+const HELP_TEXT = `tokenmaxxing agent MCP
+
+Read tools (always available):
+  pool_ls       list pooled Claude and Codex accounts (labels/status only)
+  pool_status   sample usage bars (free /usage path; never --force)
+  doctor        verify install health (labels/status only)
+  config_get    read effective config, or one key when provided
+  help          this catalog
+
+Mutating tools (confirm=true AND ${MUTATIONS_ENV}=1):
+  pool_switch   Claude greedy/forced switch, or Codex when codex=true
+  pool_check    one evaluate-and-maybe-swap pass
+  config_set    write a config.json override
+  config_unset  remove a config.json override
+
+Hard deny (no tools):
+  status --force / metered pings
+  init / add / auth / rm / uninstall
+  credential blobs or token values
+  killing sessions or supervisors
+
+Prefer these tools over raw shell for pool ops. Honor TOKENMAXXING_HOME for hermetic use.
+`;
+
+export function createTokenmaxxingMcpServer(): McpServer {
+  const server = new McpServer({
+    name: "tokenmaxxing",
+    version: packageVersion(),
+  });
+
+  server.registerTool(
+    "help",
+    {
+      description: "Catalog of tokenmaxxing MCP tools and hard safety rules. Use when deciding which pool tool to call.",
+      inputSchema: {},
+    },
+    async () => textResult({ text: HELP_TEXT }),
+  );
+
+  server.registerTool(
+    "pool_ls",
+    {
+      description: "List pooled Claude and Codex accounts with active and needs-reauth flags. Labels and status only; never credential material.",
+      inputSchema: {},
+    },
+    async () => {
+      const cap = await captureCli(() => cmdLs());
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  server.registerTool(
+    "pool_status",
+    {
+      description: "Show pool usage bars via the free /usage path. Never opens 5h windows. Do not request --force; that tool does not exist.",
+      inputSchema: {},
+    },
+    async () => {
+      const cap = await captureCli(() => cmdStatus(false));
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  server.registerTool(
+    "doctor",
+    {
+      description: "Verify supervisor, hooks, timer, and credential identity health. Reports labels and pass/fail only; never returns credential blobs.",
+      inputSchema: {},
+    },
+    async () => {
+      const cap = await captureCli(() => cmdDoctor());
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  server.registerTool(
+    "config_get",
+    {
+      description: "Read effective config with sources, or one dotted key when key is set (e.g. thresholds.session).",
+      inputSchema: {
+        key: z.string().optional().describe("Optional dotted config key; omit for the full effective table"),
+      },
+    },
+    async ({ key }) => {
+      const args = key ? ["get", key] : [];
+      const cap = await captureCli(() => cmdConfig(args));
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  server.registerTool(
+    "pool_switch",
+    {
+      description: "Switch the Claude pool (or Codex when codex=true). Requires confirm=true and TOKENMAXXING_AGENT_MUTATIONS=1. Hot-swaps live Claude; Codex takes effect on next start.",
+      inputSchema: {
+        confirm: z.boolean().describe("Must be true after the user approves the mutation"),
+        selector: z.string().optional().describe("Optional account selector; omit for greedy best"),
+        codex: z.boolean().optional().describe("When true, run the Codex pool switch instead"),
+      },
+    },
+    async ({ confirm, selector, codex }) => {
+      const denied = mutationDenied(confirm);
+      if (denied) return textResult({ text: denied, isError: true });
+      const cap = await captureCli(() => (codex ? cmdCodexSwitch(selector) : cmdSwitch(selector)));
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  server.registerTool(
+    "pool_check",
+    {
+      description: "Run one evaluate-and-maybe-swap pass (the periodic timer path). Requires confirm=true and TOKENMAXXING_AGENT_MUTATIONS=1.",
+      inputSchema: {
+        confirm: z.boolean().describe("Must be true after the user approves the mutation"),
+      },
+    },
+    async ({ confirm }) => {
+      const denied = mutationDenied(confirm);
+      if (denied) return textResult({ text: denied, isError: true });
+      const cap = await captureCli(() => cmdCheck());
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  server.registerTool(
+    "config_set",
+    {
+      description: "Write a config.json override. Requires confirm=true and TOKENMAXXING_AGENT_MUTATIONS=1.",
+      inputSchema: {
+        confirm: z.boolean().describe("Must be true after the user approves the mutation"),
+        key: z.string().describe("Dotted config key"),
+        value: z.string().describe("JSON or literal string value"),
+      },
+    },
+    async ({ confirm, key, value }) => {
+      const denied = mutationDenied(confirm);
+      if (denied) return textResult({ text: denied, isError: true });
+      const cap = await captureCli(() => cmdConfig(["set", key, value]));
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  server.registerTool(
+    "config_unset",
+    {
+      description: "Remove a config.json override. Requires confirm=true and TOKENMAXXING_AGENT_MUTATIONS=1.",
+      inputSchema: {
+        confirm: z.boolean().describe("Must be true after the user approves the mutation"),
+        key: z.string().describe("Dotted config key"),
+      },
+    },
+    async ({ confirm, key }) => {
+      const denied = mutationDenied(confirm);
+      if (denied) return textResult({ text: denied, isError: true });
+      const cap = await captureCli(() => cmdConfig(["unset", key]));
+      return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
+    },
+  );
+
+  return server;
+}
+
+/** Entrypoint for the Agent Plugin launcher (`agent-plugin/bin/tokenmaxxing-mcp`).
+ *  Exported because that bin imports this module (so `import.meta.main` is false here). */
+export async function main(): Promise<void> {
+  const ambient = refuseAmbientStoreEnv();
+  if (ambient != null) {
+    console.error(
+      `CLAUDE_CONFIG_DIR / CLAUDE_SECURESTORAGE_CONFIG_DIR is set (${ambient}): the pooled MCP surface requires the default Claude Code credential store. Unset it and retry.`,
+    );
+    process.exit(1);
+  }
+  const server = createTokenmaxxingMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("tokenmaxxing MCP server running on stdio");
+}
+
+if (import.meta.main) {
+  main().catch((e) => {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  });
+}

package/src/lib/decide.ts

@@ -42,8 +42,7 @@ const SwapDecisionSchema = z.object({
   reason: z.string(),
   /** set when every account is depleted and the soonest recovery is known:
    *  epoch ms that account recovers. The wait target on depleted-wait;
-   *  informational on a bare all-depleted (callers like `xx serve` park on
-   *  it - nothing here waits). */
+   *  informational on a bare all-depleted (nothing here waits). */
   waitUntil: z.number().optional(),
 });
 export type SwapDecision = z.infer<typeof SwapDecisionSchema>;
@@ -318,8 +317,7 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
     // truly walled do we fall through to the depleted-wait park below. The wall
     // reading is the statusLine's authoritative rate_limits tee (the same data
     // /rate-limit-options renders); a single-turn overshoot is caught one
-    // boundary later by the check timer or the next Stop hook, and the serve/SDK
-    // path additionally stamps observed limits on errored results.
+    // boundary later by the check timer or the next Stop hook.
     const hardCtx = { now, thresholds: hardBars(cfg), currentAccountUuid: null, switchFamilies };
     const seat = seatOf(loadAccounts());
     if (seat && !seat.needsReauth && !isExhausted(seat, hardCtx)) {

package/src/lib/lock.ts

@@ -4,13 +4,9 @@
 // process exit).
 //
 // The acquire is NON-BLOCKING (LOCK_EX|LOCK_NB) with an async retry loop: a
-// blocking LOCK_EX from this runtime freezes the whole event loop, and in
-// `xx serve` (many actors, one process) a second actor's blocking acquire
-// would stop the holder from ever resuming to release - a true single-process
-// deadlock; a cross-process holder would freeze the daemon for its whole
-// critical section (adversarial review catch, 2026-07-19). EWOULDBLOCK is
-// told apart from real failures via errno, so a bad fd still fails fast
-// instead of spinning.
+// blocking LOCK_EX from this runtime freezes the whole event loop.
+// EWOULDBLOCK is told apart from real failures via errno, so a bad fd still
+// fails fast instead of spinning.
 
 import { closeSync, mkdirSync, openSync } from "node:fs";
 import { dirname } from "node:path";

package/src/lib/log.ts

@@ -18,10 +18,9 @@ function redact(s: string): string {
 
 let echo: ((input: { event: string; parts: string }) => void) | null = null;
 
-/** Tee every subsequent log() line to a terminal printer. Only the serve
- *  daemon opts in: hooks and the statusline own their stdout protocol, so the
- *  echo stays off by default. The printer receives the same redacted parts the
- *  file line gets. */
+/** Tee every subsequent log() line to a terminal printer. Off by default
+ *  (hooks and the statusline own their stdout protocol). The printer receives
+ *  the same redacted parts the file line gets. */
 export function setLogEcho(input: { printer: (input: { event: string; parts: string }) => void }): void {
   echo = input.printer;
 }
@@ -36,10 +35,9 @@ export function log(event: string, fields: Record<string, unknown> = {}): void {
       })
       .join(" ");
     mkdirSync(dirname(paths.logFile), { recursive: true });
-    // Rotation cap: the check timer logs every 180s and the serve daemon
-    // echoes every event, so an uncapped append-only file grows forever on a
-    // live install (closing-review critic gap). One .old generation bounds
-    // total disk at ~2x the cap; older history is disposable diagnostics.
+    // Rotation cap: the check timer logs every 180s, so an uncapped
+    // append-only file grows forever on a live install. One .old generation
+    // bounds total disk at ~2x the cap; older history is disposable diagnostics.
     if (existsSync(paths.logFile) && statSync(paths.logFile).size > LOG_MAX_BYTES) {
       renameSync(paths.logFile, `${paths.logFile}.old`);
     }
@@ -47,11 +45,10 @@ export function log(event: string, fields: Record<string, unknown> = {}): void {
   } catch {
     // logging must never throw into a hook / supervisor path
   }
-  // separate from the file sink: an unwritable log file must not also silence
-  // the terminal echo (that is exactly when the daemon needs to stay visible).
+  // separate from the file sink: an unwritable log file must not also silence the echo.
   try {
     echo?.({ event, parts: line });
   } catch {
-    // the echo printer must never throw into the daemon either
+    // the echo printer must never throw into a caller path
   }
 }

package/src/lib/paths.ts

@@ -37,15 +37,6 @@ export const paths = {
   /** linux only: parked credential .json files (0700 dir, 0600 files). */
   credsDir: join(TM_HOME, "creds"),
 
-  /** `xx serve` slack bridge: tokens + channel->repo links (0600: holds the
-   *  xoxb-/xapp- tokens), per-thread claude session records, and the
-   *  single-instance flock (a new daemon generation blocks on it until the
-   *  previous one - possibly still draining an in-flight turn - fully exits,
-   *  so two generations never act on the same thread records or cwd). */
-  slackJson: join(TM_HOME, "slack.json"),
-  slackThreadsDir: join(TM_HOME, "slack-threads"),
-  serveLockFile: join(TM_HOME, "serve-lock"),
-
   /** ~/.claude.json - holds the active `oauthAccount` identity object. */
   claudeJson: env("TOKENMAXXING_CLAUDE_JSON", join(HOME, ".claude.json")),
   /** ~/.claude/settings.json - user-owned; we merge four entries into it. */

package/src/lib/usage.ts

@@ -199,11 +199,12 @@ export function parseUsageLimitEpoch(input: { text: string }): number | null {
 
 /**
  * Persist a limit observed in a turn RESULT into usage.json so the next
- * decision sees the depleted account immediately. A headless serve/SDK process
- * has no statusLine tee and `loadFreshSnapshots` skips re-probing inside the
- * poll TTL (and `/usage` is fail-silent against the just-limited active token
- * anyway), so without this write a post-limit retry re-decides off the stale
- * pre-limit snapshot and respawns the same depleted account. The session
+ * decision sees the depleted account immediately. Callers without a statusLine
+ * tee (headless Agent SDK integrations) should invoke this on errored limit
+ * results: `loadFreshSnapshots` skips re-probing inside the poll TTL and
+ * `/usage` is fail-silent against the just-limited active token, so without
+ * this write a post-limit retry re-decides off the stale pre-limit snapshot
+ * and respawns the same depleted account. The session
  * window is stamped 100% with the announced reset: whichever window actually
  * tripped, the account is unusable until then, and the hard path swaps away.
  * `org` is the identity captured AT THE SPAWN BOUNDARY of the turn that

package/src/main.ts

@@ -3,9 +3,7 @@
 // `claude` (or `__supervise`), routes hook/statusLine subcommands, and otherwise
 // dispatches the `tokenmaxxing` CLI.
 
-import { existsSync } from "node:fs";
 import { basename } from "node:path";
-import { paths } from "./lib/paths.ts";
 import { runSupervisor } from "./entries/supervisor.ts";
 import { runStatusline } from "./entries/statusline.ts";
 import { runSubagentStatusline } from "./entries/subagentstatusline.ts";
@@ -29,7 +27,6 @@ import { cmdRename } from "./cli/rename.ts";
 import { cmdSwitch } from "./cli/switch.ts";
 import { cmdCheck } from "./cli/check.ts";
 import { cmdConfig } from "./cli/config.ts";
-import { cmdServe } from "./cli/serve.ts";
 import { timerDeactivationHint, uninstallSupervisor } from "./lib/install.ts";
 import { c } from "./cli/render.ts";
 
@@ -50,7 +47,6 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing status --force")}  ping every account (one tiny haiku request each) so all 5h session timers start now, then sample fresh; ${c.cyan("xx --force")} works too
   ${c.cyan("tokenmaxxing watch")} [seconds]  live status: re-render every N seconds (default 120, never pings)
   ${c.cyan("tokenmaxxing config")} [get|set|unset|tidy]  inspect and edit config.json (bare = effective config with sources)
-  ${c.cyan("tokenmaxxing serve")} [setup|link|unlink|links]  Slack bridge daemon: mention the bot in a linked channel to open a claude session per thread in the repo checkout
   ${c.cyan("tokenmaxxing doctor")}     verify the install is intact
   ${c.cyan("tokenmaxxing rename")} [--codex] <sel> <label>
   ${c.cyan("tokenmaxxing rm")} [--codex] <sel>
@@ -115,7 +111,6 @@ async function main(): Promise<number> {
     }
     case "check": return cmdCheck();
     case "config": return cmdConfig(args.slice(1));
-    case "serve": return cmdServe(args.slice(1));
     case "init": return args.includes("--codex") ? cmdCodexInit() : cmdInit();
     case "add": return args.includes("--codex") ? cmdCodexAdd() : cmdAdd();
     case "auth": return cmdAuth(args.slice(1));
@@ -145,7 +140,7 @@ async function main(): Promise<number> {
       console.log(`removed ${removed.join(", ")}`);
       if (!out.timerDeactivated) console.log(c.yellow(`⚠ the check job may still be loaded - run: ${timerDeactivationHint()}`));
       if (!out.pathLineRemoved) console.log(c.dim("(no tokenmaxxing PATH line found in the shell rc)"));
-      console.log(`kept: accounts.json, config.json${existsSync(paths.slackJson) ? ", slack.json (Slack tokens)" : ""}, and every parked credential (claude - macOS: keychain items, Linux: creds/; codex: codex-creds/) - remove accounts with \`xx rm\` to delete their credentials`);
+      console.log(`kept: accounts.json, config.json, and every parked credential (claude - macOS: keychain items, Linux: creds/; codex: codex-creds/) - remove accounts with \`xx rm\` to delete their credentials`);
       return 0;
     }
     case "help":