pennyrouter 0.2.1 → 0.2.4

package/README.md

@@ -22,12 +22,14 @@ npx pennyrouter status
 Installation opens a browser and requires login to the PennyRouter account that should own
 the new machine key. CLI installs no longer create anonymous ghost accounts.
 
-With no `--harness` flag, the interactive installer shows a checkbox list. Tools with
-detected configs start checked; press Enter to accept or type tool IDs to toggle them.
+With no `--harness` flag, the interactive installer shows Claude Code and Codex. Detected
+tools start checked. The additional legacy integrations remain available through an explicit
+`--harness <id>` selection or `--all`.
 
-When Claude Code is selected, the installer also offers an optional Claude Pro/Max
-subscription-auth step. Users can skip it during install and enable it later with
-`@penny auth` or `npx pennyrouter auth anthropic`.
+When Claude Code is selected, the installer offers Claude subscription authorization. If it is
+declined or unavailable, installation requires an Anthropic API key or OpenRouter key. Codex
+uses an existing ChatGPT login; without one, installation requires an OpenAI API key or
+OpenRouter key. PennyRouter-funded provider keys are never an installed-harness fallback.
 
 ## Explicit Penny Commands
 
@@ -59,7 +61,8 @@ does not currently expose equivalent project-independent custom slash commands.
 When Codex is already signed in with ChatGPT, the installer preserves that Codex-managed
 login and configures PennyRouter as an OpenAI-authenticated Responses proxy. Codex continues
 to own and refresh the OpenAI credentials; PennyRouter stores only its existing `pr-` account
-key in the managed provider block. API-key Codex installs continue to use PennyRouter credits.
+key in the managed provider block. API-key Codex installs use the user's encrypted OpenAI or
+OpenRouter key.
 
 To point Codex directly at a PennyRouter gateway running on localhost port 8400:
 
@@ -100,7 +103,7 @@ model you chose. "Penny Custom" is the dynamic option: PennyRouter cost-routes e
 - Penny Fable: pins `anthropic/claude-fable-5`
 - Penny Custom: `pennyrouter/auto` — dynamic routing on the bundle/profile saved in the user's account
 
-## Claude Pro/Max Subscription Auth
+## Claude Subscription Auth
 
 When installing PennyRouter for Claude Code, the interactive installer offers to route
 Anthropic-native Claude turns through the user's own Claude subscription token. To force this
@@ -108,9 +111,12 @@ in non-interactive installs:
 
 ```bash
 npx pennyrouter install --harness claude-code --anthropic-auth --token <token>
+npx pennyrouter install --harness claude-code --anthropic-api-key <key>
+npx pennyrouter install --harness codex --openai-api-key <key>
+npx pennyrouter install --openrouter-api-key <key>
 ```
 
-If Claude Code is already logged in to a Pro/Max subscription, use Claude Code's token setup
+If Claude Code is already logged in to a Claude subscription, use Claude Code's token setup
 flow:
 
 ```bash
@@ -138,6 +144,11 @@ PennyRouter `pr-` bearer in its settings; the gateway retrieves and forwards the
 with the required OAuth beta header and does not deduct PennyRouter credit for successfully
 served Anthropic-subscription calls.
 
+On a transient subscription 429/529, the gateway retries the same subscription once. If it
+still fails, it can fall back only to credentials owned by that user: Anthropic API then
+OpenRouter for Claude, or OpenAI API then OpenRouter for Codex. If no such credential is
+configured, the provider error is returned; PennyRouter never changes the payer to itself.
+
 PennyRouter also sets `disableClaudeAiConnectors: true` while its custom gateway is installed.
 Claude Code cannot load claude.ai organization connectors when gateway authentication takes
 precedence, and otherwise displays a persistent warning about that state. Making the disablement

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pennyrouter",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "description": "Install and manage PennyRouter local coding-agent integrations.",
   "homepage": "https://pennyrouter.com",
   "bugs": {

package/src/cli.js

@@ -24,6 +24,7 @@ import {
   probeClaudeCodeGateway,
   sleep,
   storeAnthropicToken,
+  storeUpstreamCredential,
 } from "./session.js";
 import {
   backupFile,
@@ -59,6 +60,17 @@ const HARNESS_BY_ID = {
 };
 
 const SUPPORTED_HARNESS_IDS = Object.keys(HARNESS_BY_ID).join(",");
+const DEFAULT_INSTALL_HARNESS_IDS = ["claude-code", "codex"];
+const CLAUDE_PROVIDER_OPTIONS = [
+  { id: "subscription", name: "Claude subscription" },
+  { id: "anthropic-api", name: "Anthropic API key" },
+  { id: "openrouter", name: "OpenRouter API key" },
+];
+const CODEX_PROVIDER_OPTIONS = [
+  { id: "subscription", name: "ChatGPT subscription" },
+  { id: "openai-api", name: "OpenAI API key" },
+  { id: "openrouter", name: "OpenRouter API key" },
+];
 
 export async function main(argv = process.argv.slice(2)) {
   const { command, flags } = parseArgs(argv);
@@ -128,6 +140,12 @@ function parseArgs(argv) {
     else if (arg.startsWith("--token=")) flags.token = arg.slice("--token=".length);
     else if (arg === "--token-command") flags.tokenCommand = rest[++i] || "";
     else if (arg.startsWith("--token-command=")) flags.tokenCommand = arg.slice("--token-command=".length);
+    else if (arg === "--anthropic-api-key") flags.anthropicApiKey = rest[++i] || "";
+    else if (arg.startsWith("--anthropic-api-key=")) flags.anthropicApiKey = arg.slice("--anthropic-api-key=".length);
+    else if (arg === "--openai-api-key") flags.openaiApiKey = rest[++i] || "";
+    else if (arg.startsWith("--openai-api-key=")) flags.openaiApiKey = arg.slice("--openai-api-key=".length);
+    else if (arg === "--openrouter-api-key") flags.openrouterApiKey = rest[++i] || "";
+    else if (arg.startsWith("--openrouter-api-key=")) flags.openrouterApiKey = arg.slice("--openrouter-api-key=".length);
     else if (arg === "--harness") flags.harness = rest[++i] || "";
     else if (arg.startsWith("--harness=")) flags.harness = arg.slice("--harness=".length);
     else if (arg === "--app-url") flags.appUrl = rest[++i] || "";
@@ -388,7 +406,7 @@ async function install(flags) {
     }
     if (flags.gatewayBaseUrl) console.log(`Serving gateway: ${flags.gatewayBaseUrl}`);
     if (selected.some((harness) => harness.id === "claude-code")) {
-      console.log("Claude Code subscription auth prompt would be shown unless skipped.");
+      console.log("Claude Code provider picker would be shown unless providers were supplied by flags or environment.");
     }
     console.log("Dry run only. No files changed.");
     return;
@@ -410,17 +428,24 @@ async function install(flags) {
   console.log(`Authorized. Received key ${maskKey(claim.api_key)}.`);
   console.log("");
 
-  const claudeAnthropicAuth = await maybeConfigureClaudeAnthropicAuth(flags, selected);
+  const claudeProviders = await selectClaudeFundingProviders(flags, selected);
+  const codexProviders = await selectCodexFundingProviders(flags, selected);
+  const claudeAnthropicAuth = await maybeConfigureClaudeAnthropicAuth(
+    flags, selected, claudeProviders.has("subscription"));
+  const funding = await configureUserFunding(
+    flags, selected, claudeAnthropicAuth, claudeProviders, codexProviders);
   const gatewayBaseUrl = flags.gatewayBaseUrl || claim.gateway_base_url;
 
+  for (const credential of funding.credentials) {
+    await storeUpstreamCredential({
+      gatewayBaseUrl,
+      apiKey: claim.api_key,
+      provider: credential.provider,
+      token: credential.token,
+    });
+  }
+
   if (selected.some((harness) => harness.id === "claude-code")) {
-    if (claudeAnthropicAuth) {
-      await storeAnthropicToken({
-        gatewayBaseUrl,
-        apiKey: claim.api_key,
-        token: claudeAnthropicAuth.token,
-      });
-    }
     console.log("Verifying modern Claude Code compatibility before changing local settings...");
     await probeClaudeCodeGateway({ gatewayBaseUrl, apiKey: claim.api_key });
     console.log("");
@@ -454,7 +479,7 @@ async function install(flags) {
       }
 
       const codexSubscriptionAuth = harness.id === "codex"
-        ? await detectCodexChatgptAuth()
+        ? funding.codexSubscriptionAuth
         : false;
       const claudeSubscriptionAuth = harness.id === "claude-code"
         && Boolean(claudeAnthropicAuth || existingRecord?.anthropic_token_stored);
@@ -502,6 +527,12 @@ async function install(flags) {
         record.anthropic_token_stored = true;
         record.token_source = claudeAnthropicAuth?.source || existingRecord?.token_source || "stored";
       }
+      if (harness.id === "claude-code" && funding.claudeCredentialProvider) {
+        record.user_funded_provider = funding.claudeCredentialProvider;
+      }
+      if (harness.id === "codex" && funding.codexCredentialProvider) {
+        record.user_funded_provider = funding.codexCredentialProvider;
+      }
       if (harness.id === "codex") record.openai_subscription_auth = codexSubscriptionAuth;
       records.push(record);
       upsertManifestRecord(manifest, record);
@@ -588,8 +619,13 @@ async function chooseDefaultRouting(flags, selected, manifest) {
         }
         console.log("");
         const bare = launchable.map((item) => item.id === "claude-code" ? "claude" : "codex");
-        const label = bare.length === 1 ? bare[0] : `${bare.slice(0, -1).join(", ")} and ${bare.at(-1)}`;
-        newInstallChoice = await confirm(`Also route ${color(label, "bold")} through PennyRouter by default?`);
+        const quoted = bare.map((command) => `'${command}'`);
+        const label = quoted.length === 1
+          ? quoted[0]
+          : `${quoted.slice(0, -1).join(", ")} and ${quoted.at(-1)}`;
+        newInstallChoice = await confirm(
+          `Set ${label} to automatically load PennyRouter with every session?`,
+        );
       }
     }
     out.set(harness.id, newInstallChoice);
@@ -597,9 +633,54 @@ async function chooseDefaultRouting(flags, selected, manifest) {
   return out;
 }
 
-async function maybeConfigureClaudeAnthropicAuth(flags, selected) {
+async function selectClaudeFundingProviders(flags, selected) {
+  if (!selected.some((harness) => harness.id === "claude-code")) return new Set();
+
+  const supplied = new Set();
+  if (!flags.noAnthropicAuth && (flags.anthropicAuth || flags.token || flags.tokenCommand
+      || process.env.ANTHROPIC_AUTH_TOKEN)) supplied.add("subscription");
+  if (flags.anthropicApiKey || process.env.ANTHROPIC_API_KEY) supplied.add("anthropic-api");
+  if (flags.openrouterApiKey || process.env.OPENROUTER_API_KEY) supplied.add("openrouter");
+
+  // Explicit flags are the automation selector. Interactive installs always default to the
+  // subscription alone; environment keys are used if the user checks their provider.
+  const explicit = flags.anthropicAuth || flags.noAnthropicAuth || flags.token
+    || flags.tokenCommand || flags.anthropicApiKey || flags.openrouterApiKey;
+  if (explicit || flags.yes || !input.isTTY || !output.isTTY) return supplied;
+
+  console.log("PennyRouter can use your Claude subscription, an Anthropic API key, or an OpenRouter API key to run Claude Code.");
+  console.log("Choose one or more providers. PennyRouter will try them in order when available.");
+  return promptFundingProviderCheckboxes(
+    CLAUDE_PROVIDER_OPTIONS,
+    "Which providers should PennyRouter use for Claude Code?",
+    new Set(["subscription"]),
+  );
+}
+
+async function selectCodexFundingProviders(flags, selected) {
+  if (!selected.some((harness) => harness.id === "codex")) return new Set();
+
+  const supplied = new Set();
+  if (flags.openaiApiKey || process.env.OPENAI_API_KEY) supplied.add("openai-api");
+  if (flags.openrouterApiKey || process.env.OPENROUTER_API_KEY) supplied.add("openrouter");
+  const hasChatgptLogin = await detectCodexChatgptAuth();
+  if (hasChatgptLogin) supplied.add("subscription");
+
+  const explicit = flags.openaiApiKey || flags.openrouterApiKey;
+  if (explicit || flags.yes || !input.isTTY || !output.isTTY) return supplied;
+
+  console.log("PennyRouter can use your ChatGPT subscription, an OpenAI API key, or an OpenRouter API key to run Codex.");
+  console.log("Choose one or more providers. PennyRouter will try them in order when available.");
+  return promptFundingProviderCheckboxes(
+    CODEX_PROVIDER_OPTIONS,
+    "Which providers should PennyRouter use for Codex?",
+    new Set(["subscription"]),
+  );
+}
+
+async function maybeConfigureClaudeAnthropicAuth(flags, selected, enabled = true) {
   if (!selected.some((harness) => harness.id === "claude-code")) return null;
-  if (flags.noAnthropicAuth) return null;
+  if (!enabled || flags.noAnthropicAuth) return null;
 
   if (flags.token || flags.tokenCommand || process.env.ANTHROPIC_AUTH_TOKEN) {
     const tokenResult = readAnthropicOAuthToken(flags);
@@ -615,19 +696,6 @@ async function maybeConfigureClaudeAnthropicAuth(flags, selected) {
     return null;
   }
 
-  if (!flags.anthropicAuth) {
-    console.log("Claude Code subscription auth");
-    console.log("PennyRouter can use your Claude Pro/Max subscription for Anthropic Claude calls.");
-    console.log("PennyRouter still handles routing, optimization, and @penny commands.");
-    console.log("");
-    const ok = await confirm("Enable Claude Pro/Max subscription auth for Claude Code?");
-    if (!ok) {
-      console.log("Skipped Claude subscription auth. Enable later with `@penny auth` or `pennyrouter auth anthropic`.");
-      console.log("");
-      return null;
-    }
-  }
-
   const tokenResult = readAnthropicOAuthToken({ tokenCommand: flags.tokenCommand });
   if (tokenResult.token) return tokenResult;
 
@@ -658,6 +726,114 @@ async function maybeConfigureClaudeAnthropicAuth(flags, selected) {
   return { token, source: "prompt" };
 }
 
+async function configureUserFunding(flags, selected, claudeAnthropicAuth,
+                                    claudeProviders = new Set(), codexProviders = new Set()) {
+  const wantsClaude = selected.some((harness) => harness.id === "claude-code");
+  const wantsCodex = selected.some((harness) => harness.id === "codex");
+  const interactive = !flags.yes && input.isTTY && output.isTTY;
+  const credentials = [];
+
+  let anthropicApiKey = String(
+    flags.anthropicApiKey || process.env.ANTHROPIC_API_KEY || "",
+  ).trim();
+  let openaiApiKey = String(
+    flags.openaiApiKey || process.env.OPENAI_API_KEY || "",
+  ).trim();
+  let openrouterApiKey = String(
+    flags.openrouterApiKey || process.env.OPENROUTER_API_KEY || "",
+  ).trim();
+  const codexSubscriptionAuth = wantsCodex && codexProviders.has("subscription")
+    ? await detectCodexChatgptAuth()
+    : false;
+
+  if (wantsClaude && claudeProviders.has("anthropic-api") && !anthropicApiKey) {
+    if (!interactive) throw new Error("Anthropic API was selected, but no key was provided.");
+    anthropicApiKey = (await promptSecretish("Anthropic API key: ")).trim();
+  }
+  if (wantsClaude && claudeProviders.has("openrouter") && !openrouterApiKey) {
+    if (!interactive) throw new Error("OpenRouter was selected, but no key was provided.");
+    openrouterApiKey = (await promptSecretish("OpenRouter API key: ")).trim();
+  }
+  if (wantsCodex && codexProviders.has("subscription") && !codexSubscriptionAuth) {
+    throw new Error(
+      "ChatGPT subscription was selected, but Codex is not logged in. Run `codex login`, or select an API-key provider.",
+    );
+  }
+  if (wantsCodex && codexProviders.has("openai-api") && !openaiApiKey) {
+    if (!interactive) throw new Error("OpenAI API was selected, but no key was provided.");
+    openaiApiKey = (await promptSecretish("OpenAI API key: ")).trim();
+  }
+  if (wantsCodex && codexProviders.has("openrouter") && !openrouterApiKey) {
+    if (!interactive) throw new Error("OpenRouter was selected, but no key was provided.");
+    openrouterApiKey = (await promptSecretish("OpenRouter API key: ")).trim();
+  }
+
+  if (wantsClaude && !claudeAnthropicAuth && !anthropicApiKey && !openrouterApiKey) {
+    if (!interactive) {
+      throw new Error(
+        "Claude Code requires a Claude subscription, --anthropic-api-key (or ANTHROPIC_API_KEY), "
+        + "or --openrouter-api-key (or OPENROUTER_API_KEY). Nothing was installed.",
+      );
+    }
+    console.log("Claude Code needs a user-funded provider. PennyRouter will never fall back to its own API keys.");
+    anthropicApiKey = (await promptSecretish(
+      "Anthropic API key (leave blank to use OpenRouter): ",
+    )).trim();
+    if (!anthropicApiKey) {
+      openrouterApiKey = (await promptSecretish("OpenRouter API key: ")).trim();
+    }
+    if (!anthropicApiKey && !openrouterApiKey) {
+      throw new Error("Claude Code installation cancelled: no subscription or API key was provided.");
+    }
+    console.log("");
+  }
+
+  if (wantsCodex && !codexSubscriptionAuth && !openaiApiKey && !openrouterApiKey) {
+    if (!interactive) {
+      throw new Error(
+        "Codex requires ChatGPT login, --openai-api-key (or OPENAI_API_KEY), "
+        + "or --openrouter-api-key (or OPENROUTER_API_KEY). Nothing was installed.",
+      );
+    }
+    console.log("Codex is not logged into ChatGPT and needs a user-funded provider.");
+    console.log("PennyRouter will never fall back to its own API keys.");
+    openaiApiKey = (await promptSecretish(
+      "OpenAI API key (leave blank to use OpenRouter): ",
+    )).trim();
+    if (!openaiApiKey) {
+      openrouterApiKey = (await promptSecretish("OpenRouter API key: ")).trim();
+    }
+    if (!openaiApiKey && !openrouterApiKey) {
+      throw new Error("Codex installation cancelled: no subscription or API key was provided.");
+    }
+    console.log("");
+  }
+
+  if (claudeAnthropicAuth) {
+    credentials.push({ provider: "anthropic_oauth", token: claudeAnthropicAuth.token });
+  }
+  if (wantsClaude && anthropicApiKey) {
+    credentials.push({ provider: "anthropic_api", token: anthropicApiKey });
+  }
+  if (wantsCodex && openaiApiKey) {
+    credentials.push({ provider: "openai_api", token: openaiApiKey });
+  }
+  if ((wantsClaude || wantsCodex) && openrouterApiKey) {
+    credentials.push({ provider: "openrouter", token: openrouterApiKey });
+  }
+
+  return {
+    credentials,
+    codexSubscriptionAuth,
+    claudeCredentialProvider: claudeAnthropicAuth
+      ? "claude-subscription"
+      : anthropicApiKey ? "anthropic-api" : openrouterApiKey ? "openrouter" : null,
+    codexCredentialProvider: codexSubscriptionAuth
+      ? "chatgpt-subscription"
+      : openaiApiKey ? "openai-api" : openrouterApiKey ? "openrouter" : null,
+  };
+}
+
 async function disable(flags) {
   const manifest = await loadManifest();
   if (pruneUnsupportedManifestRecords(manifest).length > 0) await saveManifest(manifest);
@@ -945,15 +1121,16 @@ async function status() {
 
 async function selectHarnesses(flags) {
   const requested = flags.all ? Object.keys(HARNESS_BY_ID) : parseHarnessList(flags.harness);
-  const detected = [];
-  for (const harness of Object.values(HARNESS_BY_ID)) {
-    if (await safeDetect(harness)) detected.push(harness);
-  }
-
   if (requested.length > 0) {
     return requested.map((id) => HARNESS_BY_ID[id]).filter(Boolean);
   }
 
+  const detected = [];
+  for (const id of DEFAULT_INSTALL_HARNESS_IDS) {
+    const harness = HARNESS_BY_ID[id];
+    if (await safeDetect(harness)) detected.push(harness);
+  }
+
   if (flags.yes) return detected;
 
   return promptHarnessCheckboxes(detected);
@@ -1078,8 +1255,74 @@ async function promptHarnessCheckboxesByText(harnesses, selectedIds) {
   }
 }
 
+async function promptFundingProviderCheckboxes(providerOptions, title,
+                                                initialIds = new Set(["subscription"])) {
+  const selectedIds = new Set(initialIds);
+  if (!input.isTTY || !output.isTTY) return selectedIds;
+
+  let cursor = 0;
+  let validation = "";
+  const previousRawMode = input.isRaw;
+  emitKeypressEvents(input);
+  input.setRawMode(true);
+  input.resume();
+  output.write("\x1b[?25l");
+
+  const render = () => {
+    output.write("\x1b[2J\x1b[H");
+    output.write("\n\n");
+    output.write(`${color(title, "bold")}\n\n`);
+    providerOptions.forEach((provider, index) => {
+      const pointer = index === cursor ? color(">", "cyan") : " ";
+      const checked = selectedIds.has(provider.id) ? color("x", "green") : " ";
+      const name = index === cursor ? color(provider.name, "cyan") : provider.name;
+      output.write(` ${pointer} [${checked}] ${name}\n`);
+    });
+    output.write("\nSpace to toggle · Enter to continue.\n");
+    if (validation) output.write(`${validation}\n`);
+  };
+  render();
+
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      input.off("keypress", onKeypress);
+      input.setRawMode(Boolean(previousRawMode));
+      input.pause();
+      output.write("\x1b[?25h\n");
+    };
+    const onKeypress = (_str, key = {}) => {
+      if (key.ctrl && key.name === "c") {
+        cleanup();
+        reject(new Error("Cancelled."));
+      } else if (key.name === "up" || key.name === "k") {
+        cursor = (cursor - 1 + providerOptions.length) % providerOptions.length;
+        validation = "";
+        render();
+      } else if (key.name === "down" || key.name === "j") {
+        cursor = (cursor + 1) % providerOptions.length;
+        validation = "";
+        render();
+      } else if (key.name === "space") {
+        const id = providerOptions[cursor].id;
+        if (selectedIds.has(id)) selectedIds.delete(id); else selectedIds.add(id);
+        validation = "";
+        render();
+      } else if (key.name === "return" || key.name === "enter") {
+        if (!selectedIds.size) {
+          validation = "Select at least one provider.";
+          render();
+          return;
+        }
+        cleanup();
+        resolve(selectedIds);
+      }
+    };
+    input.on("keypress", onKeypress);
+  });
+}
+
 function orderedHarnessesForPrompt(detectedIds) {
-  return Object.values(HARNESS_BY_ID).sort((left, right) => {
+  return DEFAULT_INSTALL_HARNESS_IDS.map((id) => HARNESS_BY_ID[id]).sort((left, right) => {
     const leftDetected = detectedIds.has(left.id);
     const rightDetected = detectedIds.has(right.id);
     if (leftDetected !== rightDetected) return leftDetected ? -1 : 1;
@@ -1316,7 +1559,7 @@ function printHelp() {
   console.log(`PennyRouter CLI
 
 Usage:
-  pennyrouter install [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes] [--dry-run] [--make-default|--penny-only] [--no-path-update] [--anthropic-auth|--no-anthropic-auth] [--local[=URL]] [--allow-running-harnesses]
+  pennyrouter install [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes] [--dry-run] [--make-default|--penny-only] [--no-path-update] [--anthropic-auth|--no-anthropic-auth] [--anthropic-api-key KEY] [--openai-api-key KEY] [--openrouter-api-key KEY] [--local[=URL]] [--allow-running-harnesses]
   pennyrouter auth anthropic [--penny-key pr-...] [--token oauth-token] [--token-command CMD] [--gateway-base-url URL] [--forget]
   pennyrouter disable [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes]
   pennyrouter enable [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes]
@@ -1328,6 +1571,9 @@ Examples:
   npx pennyrouter install --make-default
   npx pennyrouter install --penny-only
   npx pennyrouter install --harness claude-code --anthropic-auth --token <token>
+  npx pennyrouter install --harness claude-code --anthropic-api-key <key>
+  npx pennyrouter install --harness codex --openai-api-key <key>
+  npx pennyrouter install --openrouter-api-key <key>
   npx pennyrouter auth anthropic
   npx pennyrouter install --all
   npx pennyrouter install --harness windsurf,zed,codegpt,aider --yes

package/src/launch.js

@@ -54,7 +54,11 @@ export function codexLaunchProfilePath() {
   return join(codexHome, "pennyrouter.config.toml");
 }
 
-export function claudeUserCommandPath() {
+export function claudeUserSkillPath() {
+  return join(homeDir(), ".claude", "skills", "penny", "SKILL.md");
+}
+
+function legacyClaudeUserCommandPath() {
   return join(homeDir(), ".claude", "commands", "penny.md");
 }
 
@@ -180,8 +184,8 @@ async function writeClaudeLaunchSettings() {
   await privateWrite(claudeLaunchSettingsPath(), `${JSON.stringify(overlay, null, 2)}\n`);
 }
 
-async function writeClaudeUserCommand() {
-  const path = claudeUserCommandPath();
+async function writeClaudeUserSkill() {
+  const path = claudeUserSkillPath();
   const existing = await readText(path, "");
   if (existing.trim() && !existing.includes(CLAUDE_COMMAND_MARKER)) {
     throw new Error(
@@ -191,14 +195,23 @@ async function writeClaudeUserCommand() {
   await mkdir(dirname(path), { recursive: true });
   await atomicWrite(path, [
     "---",
+    "name: penny",
     "description: PennyRouter commands and help.",
     "argument-hint: <command and arguments>",
+    "disable-model-invocation: true",
     "---",
     CLAUDE_COMMAND_MARKER,
     "",
     "@penny $ARGUMENTS",
     "",
   ].join("\n"));
+  const legacyPath = legacyClaudeUserCommandPath();
+  const legacy = await readText(legacyPath, "");
+  if (legacy.includes(CLAUDE_COMMAND_MARKER)) {
+    await unlink(legacyPath).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+  }
 }
 
 async function writeCodexLaunchProfile({ gatewayBaseUrl, subscriptionAuth }) {
@@ -223,7 +236,7 @@ export async function configurePennyHarness(harness, {
   config.api_key = apiKey;
   config.harnesses ||= {};
   if (harness === "claude-code") {
-    await writeClaudeUserCommand();
+    await writeClaudeUserSkill();
     await writeClaudeLaunchSettings();
     config.harnesses.claude = {
       enabled: true,
@@ -258,9 +271,10 @@ export async function removePennyHarness(harness) {
     await unlink(claudeLaunchSettingsPath()).catch((error) => {
       if (error.code !== "ENOENT") throw error;
     });
-    const command = await readText(claudeUserCommandPath(), "");
-    if (command.includes(CLAUDE_COMMAND_MARKER)) {
-      await unlink(claudeUserCommandPath()).catch((error) => {
+    for (const path of [claudeUserSkillPath(), legacyClaudeUserCommandPath()]) {
+      const command = await readText(path, "");
+      if (!command.includes(CLAUDE_COMMAND_MARKER)) continue;
+      await unlink(path).catch((error) => {
         if (error.code !== "ENOENT") throw error;
       });
     }

package/src/launch.test.js

@@ -6,7 +6,7 @@ import path from "node:path";
 import {
   buildPennyInvocation,
   claudeLaunchSettingsPath,
-  claudeUserCommandPath,
+  claudeUserSkillPath,
   codexLaunchProfilePath,
   configurePennyHarness,
   fileMode,
@@ -108,19 +108,20 @@ async function main() {
     assert.throws(() => buildPennyInvocation("claude", ["--settings=x"], config), /manages --settings/);
     assert.throws(() => buildPennyInvocation("codex", ["-p", "other"], config), /manages --profile/);
 
-    const command = fs.readFileSync(claudeUserCommandPath(), "utf8");
+    const command = fs.readFileSync(claudeUserSkillPath(), "utf8");
     assert.ok(command.includes("@penny $ARGUMENTS"));
+    assert.ok(command.includes("name: penny"));
 
     await removePennyHarness("claude-code");
-    assert.ok(!fs.existsSync(claudeUserCommandPath()));
-    fs.mkdirSync(path.dirname(claudeUserCommandPath()), { recursive: true });
-    fs.writeFileSync(claudeUserCommandPath(), "user-owned command\n");
+    assert.ok(!fs.existsSync(claudeUserSkillPath()));
+    fs.mkdirSync(path.dirname(claudeUserSkillPath()), { recursive: true });
+    fs.writeFileSync(claudeUserSkillPath(), "user-owned command\n");
     await assert.rejects(configurePennyHarness("claude-code", {
       apiKey: "pr-super-secret",
       gatewayBaseUrl: "https://gateway.example/",
       models: {},
     }), /not managed by PennyRouter/);
-    assert.equal(fs.readFileSync(claudeUserCommandPath(), "utf8"), "user-owned command\n");
+    assert.equal(fs.readFileSync(claudeUserSkillPath(), "utf8"), "user-owned command\n");
     assert.ok(fs.existsSync(codexLaunchProfilePath()));
     assert.ok(fs.existsSync(pennyShimPath()));
     await removePennyHarness("codex");

package/src/session.js

@@ -46,10 +46,10 @@ export function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-// Encrypt-and-store an Anthropic setup-token against the account server-side, so the
-// pr- key alone unlocks Claude and no token is written to the harness config. The
-// gateway (not the web app) owns this: it holds the pr- key auth and the encryption.
-export async function storeAnthropicToken({ gatewayBaseUrl, apiKey, token }) {
+// Encrypt and store a user-owned upstream credential against the account server-side,
+// so the pr- key alone unlocks the selected harness and the provider secret is never
+// written to harness configuration.
+export async function storeUpstreamCredential({ gatewayBaseUrl, apiKey, provider, token }) {
   const url = `${gatewayBaseUrl.replace(/\/+$/, "")}/v1/upstream-credentials`;
   const response = await fetch(url, {
     method: "POST",
@@ -57,7 +57,7 @@ export async function storeAnthropicToken({ gatewayBaseUrl, apiKey, token }) {
       "content-type": "application/json",
       authorization: `Bearer ${apiKey}`,
     },
-    body: JSON.stringify({ provider: "anthropic", token }),
+    body: JSON.stringify({ provider, token }),
   });
   if (!response.ok) {
     let detail = "";
@@ -66,15 +66,22 @@ export async function storeAnthropicToken({ gatewayBaseUrl, apiKey, token }) {
     } catch {
       // non-JSON body; fall through to status-only message
     }
-    throw new Error(`Storing Claude token failed: HTTP ${response.status}${detail ? ` — ${detail}` : ""}`);
+    throw new Error(`Storing ${provider} credential failed: HTTP ${response.status}${detail ? ` — ${detail}` : ""}`);
   }
   return response.json();
 }
 
+export async function storeAnthropicToken({ gatewayBaseUrl, apiKey, token }) {
+  return storeUpstreamCredential({
+    gatewayBaseUrl, apiKey, provider: "anthropic_oauth", token,
+  });
+}
+
 // Exercise the exact modern Claude Code request feature that has historically broken at
 // proxy boundaries BEFORE changing ~/.claude/settings.json (a user-global redirect). This
-// is intentionally a real, tiny Messages call: a generic /health check cannot prove that
-// Anthropic beta headers survive the gateway's subscription/native relay.
+// is intentionally sent through /v1/messages rather than a generic /health endpoint, so it
+// proves the gateway can parse the modern beta/tool/context-management envelope. The exact
+// one-token install probe is answered locally by compatible gateways and costs nothing.
 export async function probeClaudeCodeGateway({ gatewayBaseUrl, apiKey }) {
   const url = `${gatewayBaseUrl.replace(/\/+$/, "")}/v1/messages?beta=true`;
   const controller = new AbortController();
@@ -91,7 +98,7 @@ export async function probeClaudeCodeGateway({ gatewayBaseUrl, apiKey }) {
       },
       body: JSON.stringify({
         model: "Penny Sonnet",
-        max_tokens: 16,
+        max_tokens: 1,
         stream: false,
         messages: [{ role: "user", content: "Reply OK." }],
         tools: [{

package/src/session.test.js

@@ -28,6 +28,7 @@ try {
   assert.equal(seen.options.headers.authorization, "Bearer pr-test");
   assert.equal(seen.options.headers["anthropic-beta"], "compact-2026-01-12");
   const body = JSON.parse(seen.options.body);
+  assert.equal(body.max_tokens, 1);
   assert.equal(body.context_management.edits[0].type, "compact_20260112");
   assert.equal(body.tools[0].name, "pennyrouter_install_probe");