@hieplp/pi-account-switcher 0.2.0

package/USAGE.md

@@ -0,0 +1,446 @@
+# Pi Account Switcher — Install & Usage
+
+This guide explains how to install, run, and use this extension in Pi.
+
+## 1. Install Dependencies
+
+From this repository:
+
+```bash
+npm install
+```
+
+Optional sanity check:
+
+```bash
+npm run typecheck
+```
+
+## 2. Run Temporarily for Testing
+
+The fastest way to test the extension is with Pi's `-e` / `--extension` flag:
+
+```bash
+pi -e ./src/extension.ts
+```
+
+Then, inside Pi, add your first account:
+
+```txt
+/accounts:add
+```
+
+To reload after manually editing the config file, use Pi's built-in:
+
+```txt
+/reload
+```
+
+## 3. Install as a Project-local Pi Extension
+
+To make the extension auto-load for this project, place it under `.pi/extensions/` or configure it as a package.
+
+Recommended project-local setup:
+
+```bash
+mkdir -p .pi/extensions/account-switcher
+cp -R src package.json package-lock.json tsconfig.json .pi/extensions/account-switcher/
+```
+
+Then start Pi from the project directory:
+
+```bash
+pi
+```
+
+If Pi is already running, use:
+
+```txt
+/reload
+```
+
+Pi auto-discovers extensions from:
+
+```txt
+.pi/extensions/*.ts
+.pi/extensions/*/index.ts
+~/.pi/agent/extensions/*.ts
+~/.pi/agent/extensions/*/index.ts
+```
+
+The easiest dev command is:
+
+```bash
+pi -e ./src/extension.ts
+```
+
+## 4. Install Globally for All Pi Projects
+
+To use the extension globally:
+
+```bash
+mkdir -p ~/.pi/agent/extensions/account-switcher
+cp -R src package.json package-lock.json tsconfig.json ~/.pi/agent/extensions/account-switcher/
+```
+
+Then start Pi anywhere:
+
+```bash
+pi
+```
+
+Or reload an existing Pi session:
+
+```txt
+/reload
+```
+
+## 5. OAuth Login Like Pi `/login`
+
+For subscription/OAuth providers, use Pi's built-in login first, then import that login as a named switchable account.
+
+```txt
+/login
+/accounts:oauth
+```
+
+To add another OAuth account for the same provider, run `/login` again with the other browser account, then run `/accounts:oauth` again with a different label.
+
+Switch OAuth accounts with:
+
+```txt
+/accounts:list
+```
+
+OAuth credentials are captured from Pi's auth file:
+
+```txt
+~/.pi/agent/auth.json
+```
+
+When switching OAuth accounts, this extension applies the stored credentials to Pi's live auth storage and clears cached provider sessions when Pi exposes cleanup hooks.
+
+## 6. Configure API-key Accounts from Inside Pi
+
+You can add API-key accounts directly from Pi without hand-writing JSON.
+
+### Add an account
+
+```txt
+/accounts:add
+```
+
+This opens a wizard for provider, label, id, credential env var, and secret source, then optionally activates the new account. If the id already exists, choose replace, enter a new id, or cancel. For custom model providers, choose a default model, then paste an account API key override or leave it blank to use the provider-level `apiKey`. Switching to that account re-registers the provider key and switches Pi to the account model. If you enter a free-text custom provider, Pi can save it as a reusable provider.
+
+The wizard supports secret sources from pasted API key, env var, file, shell command, or 1Password `op://` reference.
+
+Warning: if you choose `Paste API key now`, the key is written as plain text to:
+
+```txt
+~/.pi/account-switcher/accounts.json
+```
+
+Prefer env vars, files with restricted permissions, or 1Password references.
+
+### Manage custom providers
+
+```txt
+/providers:list
+/providers:add
+/providers:edit
+/providers:remove
+```
+
+Custom providers are stored separately from accounts:
+
+```txt
+~/.pi/account-switcher/providers.json
+```
+
+Built-in providers are read-only. Removing a custom provider is blocked while accounts still use it. Provider entries may also include Pi model-provider fields like `baseUrl`, `api`, `apiKey`, `compat`, and `models`; account-switcher registers those providers with Pi.
+
+`apiKey` can be an env var name, shell command (`!op read ...`), or raw key. Raw keys work, but they are stored in plaintext in `providers.json`; prefer env/file/1Password when possible.
+
+Example provider config:
+
+```json
+{
+  "providers": {
+    "acme": {
+      "name": "Acme AI",
+      "baseUrl": "https://api.acme.test/v1",
+      "api": "openai-completions",
+      "apiKey": "ACME_API_KEY",
+      "envKeys": ["ACME_API_KEY"],
+      "aliases": ["acme-ai"],
+      "models": [{ "id": "acme-coder", "name": "Acme Coder" }]
+    }
+  }
+}
+```
+
+## 7. Configure Accounts Manually
+
+Account config lives at:
+
+```txt
+~/.pi/account-switcher/accounts.json
+```
+
+Example config:
+
+```json
+{
+  "switchMode": "env",
+  "accounts": [
+    {
+      "id": "claude-work",
+      "label": "Claude — Work",
+      "provider": "anthropic",
+      "env": {
+        "ANTHROPIC_API_KEY": { "type": "env", "name": "ANTHROPIC_WORK_API_KEY" }
+      }
+    },
+    {
+      "id": "claude-personal",
+      "label": "Claude — Personal",
+      "provider": "anthropic",
+      "env": {
+        "ANTHROPIC_API_KEY": { "type": "file", "path": "~/.keys/claude-personal.txt" }
+      }
+    },
+    {
+      "id": "codex-client-a",
+      "label": "Codex — Client A",
+      "provider": "openai",
+      "env": {
+        "OPENAI_API_KEY": { "type": "op", "reference": "op://AI/CodexClientA/api-key" }
+      }
+    }
+  ]
+}
+```
+
+## 8. Supported Secret Sources
+
+### Literal value
+
+```json
+{
+  "OPENAI_API_KEY": { "type": "literal", "value": "sk-..." }
+}
+```
+
+### Existing environment variable
+
+```json
+{
+  "ANTHROPIC_API_KEY": { "type": "env", "name": "ANTHROPIC_WORK_API_KEY" }
+}
+```
+
+### File
+
+```json
+{
+  "ANTHROPIC_API_KEY": { "type": "file", "path": "~/.keys/claude-work.txt" }
+}
+```
+
+### Shell command
+
+```json
+{
+  "ANTHROPIC_API_KEY": {
+    "type": "command",
+    "command": "op read op://AI/ClaudeWork/api-key"
+  }
+}
+```
+
+### 1Password reference
+
+```json
+{
+  "OPENAI_API_KEY": {
+    "type": "op",
+    "reference": "op://AI/CodexClientA/api-key"
+  }
+}
+```
+
+A plain string is treated as a literal value, except strings beginning with `op://` are resolved using `op read`.
+
+## 9. Commands
+
+### Pick account for current provider
+
+```txt
+/accounts:list
+```
+
+The extension tries to detect the current model provider and shows matching accounts.
+
+### Pick account for a specific provider
+
+```txt
+/accounts:list
+```
+
+Useful if Pi cannot detect the active provider.
+
+### List accounts
+
+```txt
+/accounts:list
+```
+
+### Import current Pi OAuth login
+
+```txt
+/accounts:oauth
+```
+
+Use this after Pi's built-in `/login`.
+
+### Add account interactively
+
+```txt
+/accounts:add
+```
+
+### Login/add account and activate it
+
+```txt
+/accounts:add
+```
+
+### Edit account
+
+```txt
+/accounts:edit
+```
+
+Edit label, provider, id, and env credential source. Blank text input keeps the existing value. Literal secret values are not displayed by default.
+
+### Remove account
+
+```txt
+/accounts:remove
+```
+
+Shows a non-secret summary, asks for confirmation, deletes the account, and clears stale saved selections.
+
+### Manage custom providers
+
+```txt
+/providers:list
+/providers:add
+/providers:edit
+/providers:remove
+```
+
+## 10. Switching Flow
+
+Typical usage:
+
+1. Start Pi:
+
+   ```bash
+   pi -e ./src/extension.ts
+   ```
+
+2. For OAuth/subscription accounts, login with Pi and import it:
+
+   ```txt
+   /login
+   /accounts:oauth
+   ```
+
+   For API-key accounts, add and activate an account:
+
+   ```txt
+   /accounts:add
+   ```
+
+3. Later, switch accounts:
+
+   ```txt
+   /accounts:list
+   ```
+
+Alternative manual config flow: edit `~/.pi/account-switcher/accounts.json` directly, then reload Pi:
+
+6. If needed, reload Pi runtime:
+
+   ```txt
+   /reload
+   ```
+
+## 11. State Persistence
+
+Selected accounts are saved at:
+
+```txt
+~/.pi/account-switcher/state.json
+```
+
+Example:
+
+```json
+{
+  "activeAccountId": "claude-work",
+  "activeModelId": "claude-sonnet-4",
+  "activeModelProvider": "anthropic"
+}
+```
+
+On Pi session start, the extension restores the saved active account and model state.
+
+## 12. Important Note About Credential Caching
+
+The extension updates `process.env`, Pi's live runtime API-key overrides, and Pi's live OAuth auth storage when those hooks are available.
+
+If a provider still keeps old credentials cached, run `/reload` or restart Pi.
+
+## 13. Troubleshooting
+
+### No accounts configured
+
+Run `/accounts:add` to create one interactively, or create `~/.pi/account-switcher/accounts.json` manually.
+
+### No accounts for provider
+
+Run explicitly:
+
+```txt
+/accounts:list
+```
+
+Also check that account `provider` values match supported providers:
+
+- `anthropic` / `claude`
+- `openai`
+- `openai-codex` / `codex`
+- `google` / `gemini`
+- `xai`
+- `openrouter`
+
+### Secret resolves empty
+
+Check the configured secret source:
+
+- env var exists
+- file exists and contains the key
+- command works manually
+- `op` CLI is signed in
+
+### Changes do not apply
+
+Switch the account again. If the provider still keeps old credentials cached, run:
+
+```txt
+/reload
+```
+
+If it still uses the old account, restart Pi.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@hieplp/pi-account-switcher",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Pi extension for quickly switching between multiple accounts/API keys per provider.",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "account-switcher"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hieplp/pi-account-switcher.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hieplp/pi-account-switcher/issues"
+  },
+  "homepage": "https://github.com/hieplp/pi-account-switcher#readme",
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "USAGE.md",
+    "INSTALL_AS_PI_PACKAGE.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@mariozechner/jiti": "^2.6.5",
+    "@mariozechner/pi-tui": "^0.73.1",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-ai": "latest",
+    "@mariozechner/pi-coding-agent": "latest",
+    "@types/node": "latest",
+    "typescript": "latest",
+    "vitest": "latest"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
+  }
+}

package/src/commands/accounts/add.ts

@@ -0,0 +1,63 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { AccountSwitcher } from "@/runtime";
+import type { AccountConfig, AccountSwitcherContext } from "@/types";
+import { COMMANDS } from "@/constants";
+import { errorUtil, providerUtil } from "@/utils";
+import { AccountCommand } from "./shared";
+import { AccountConfigBuilder } from "./shared/prompts";
+
+export const useAddAccountCommand = (pi: ExtensionAPI, runtime: AccountSwitcher) => {
+  new AddAccountCommand(pi, runtime).register();
+};
+
+class AddAccountCommand extends AccountCommand {
+  constructor(pi: ExtensionAPI, runtime: AccountSwitcher) {
+    super(pi, runtime, COMMANDS.accounts.add);
+  }
+
+  async handler(ctx: AccountSwitcherContext): Promise<void> {
+    try {
+      await this.runtime.load();
+      const providers = this.runtime.getProviders();
+
+      const account = await new AccountConfigBuilder(ctx.ui, providers).collect();
+      if (!account) return;
+
+      await this.saveProvider(ctx, account);
+      const saved = await this.saveAccount(ctx, account);
+      if (!saved) return;
+
+      ctx.ui.notify(`Added account ${saved.label}.`, "info");
+
+      const activate = await ctx.ui.confirm(
+        "Activate now?",
+        `Switch ${providerUtil.normalizeProvider(saved.provider)} to ${saved.label} now?`,
+      );
+      if (activate) {
+        const applied = await this.runtime.activateAccount(saved, ctx);
+        const detail = applied ? ` (${applied})` : "";
+        ctx.ui.notify(`Activated ${saved.label}${detail}.`, "info");
+      }
+    } catch (error) {
+      ctx.ui.notify(`Failed to add account: ${errorUtil.format(error)}`, "error");
+    }
+  }
+
+  private async saveProvider(ctx: AccountSwitcherContext, account: AccountConfig): Promise<void> {
+    const providerId = providerUtil.normalizeProvider(account.provider);
+
+    if (providerUtil.isBuiltInProviderId(providerId)) return;
+
+    if (providerUtil.hasProvider(providerId, this.runtime.getProviders())) return;
+
+    const save = await ctx.ui.confirm(
+      "Save custom provider?",
+      `Save ${providerId} as a reusable custom provider for future account setup?`,
+    );
+    if (!save) return;
+
+    const provider = { id: providerId, label: providerId, envKeys: Object.keys(account.env ?? {}) };
+    await this.runtime.addProvider(provider);
+    ctx.ui.notify(`Saved custom provider ${provider.id}.`, "info");
+  }
+}

package/src/commands/accounts/edit.ts

@@ -0,0 +1,31 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { AccountSwitcher } from "@/runtime";
+import type { AccountSwitcherContext } from "@/types";
+import { COMMANDS } from "@/constants";
+import { errorUtil } from "@/utils";
+import { AccountCommand, AccountConfigBuilder } from "./shared";
+
+export const useEditAccountCommand = (pi: ExtensionAPI, runtime: AccountSwitcher) => {
+  new EditAccountCommand(pi, runtime).register();
+};
+
+class EditAccountCommand extends AccountCommand {
+  constructor(pi: ExtensionAPI, runtime: AccountSwitcher) {
+    super(pi, runtime, COMMANDS.accounts.edit);
+  }
+
+  async handler(ctx: AccountSwitcherContext): Promise<void> {
+    try {
+      const original = await this.loadAndSelectAccount(ctx, "Select account to edit");
+      if (!original) return;
+
+      const updated = await new AccountConfigBuilder(ctx.ui, this.runtime.getProviders(), original).collect();
+      if (!updated) return;
+
+      await this.runtime.editAccount(original, updated);
+      ctx.ui.notify(`Account "${updated.label}" updated.`, "info");
+    } catch (e) {
+      ctx.ui.notify(`Failed to edit account: ${errorUtil.format(e)}`, "error");
+    }
+  }
+}

package/src/commands/accounts/index.ts

@@ -0,0 +1,19 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { AccountSwitcher } from "@/runtime";
+import { useAddAccountCommand } from "./add";
+import { useEditAccountCommand } from "./edit";
+import { useListAccountsCommand } from "./list";
+import { useOAuthImportCommand } from "./oauth";
+import { useRemoveAccountCommand } from "./remove";
+import { useSwitchAccountCommand } from "./switch";
+
+const useAccountCommands = (pi: ExtensionAPI, runtime: AccountSwitcher) => {
+  useAddAccountCommand(pi, runtime);
+  useEditAccountCommand(pi, runtime);
+  useListAccountsCommand(pi, runtime);
+  useOAuthImportCommand(pi, runtime);
+  useRemoveAccountCommand(pi, runtime);
+  useSwitchAccountCommand(pi, runtime);
+};
+
+export default useAccountCommands;

package/src/commands/accounts/list.ts

@@ -0,0 +1,31 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { AccountSwitcher } from "@/runtime";
+import type { AccountSwitcherContext } from "@/types";
+import { COMMANDS } from "@/constants";
+import { errorUtil } from "@/utils";
+import { AccountCommand } from "./shared";
+
+export const useListAccountsCommand = (pi: ExtensionAPI, runtime: AccountSwitcher) => {
+  new ListAccountsCommand(pi, runtime).register();
+};
+
+class ListAccountsCommand extends AccountCommand {
+  constructor(pi: ExtensionAPI, runtime: AccountSwitcher) {
+    super(pi, runtime, COMMANDS.accounts.list);
+  }
+
+  async handler(ctx: AccountSwitcherContext): Promise<void> {
+    try {
+      const accounts = await this.loadAccounts(ctx);
+      if (!accounts) return;
+
+      const account = await this.pickGroupedAccount(ctx, accounts, "Pick account to activate");
+      if (!account) return;
+
+      const applied = await this.runtime.activateAccount(account, ctx);
+      ctx.ui.notify(`Switched to ${account.label} (${applied}).`, "info");
+    } catch (error) {
+      ctx.ui.notify(`Failed to list accounts: ${errorUtil.format(error)}`, "error");
+    }
+  }
+}

package/src/commands/accounts/oauth.ts

@@ -0,0 +1,59 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { AccountSwitcher } from "@/runtime";
+import type { AccountConfig, AccountSwitcherContext } from "@/types";
+import { COMMANDS, OAUTH_PROVIDER_IDS, PI_AUTH_PATH } from "@/constants";
+import { commonUtil, errorUtil } from "@/utils";
+import { AccountCommand } from "./shared";
+
+export const useOAuthImportCommand = (pi: ExtensionAPI, runtime: AccountSwitcher) => {
+  new OAuthImportCommand(pi, runtime).register();
+};
+
+class OAuthImportCommand extends AccountCommand {
+  constructor(pi: ExtensionAPI, runtime: AccountSwitcher) {
+    super(pi, runtime, COMMANDS.accounts.oauth);
+  }
+
+  async handler(ctx: AccountSwitcherContext): Promise<void> {
+    try {
+      await this.runtime.load();
+
+      const providerChoice = await ctx.ui.select("Provider logged in with Pi /login", [...OAUTH_PROVIDER_IDS]);
+      if (!providerChoice) return;
+
+      const provider =
+        providerChoice === "custom"
+          ? (await ctx.ui.input("Pi auth provider id", "provider-id"))?.trim()
+          : providerChoice;
+      if (!provider) return;
+
+      const entry = await this.runtime.getPiAuthEntry(provider);
+      if (!entry) {
+        ctx.ui.notify(`No Pi auth entry for "${provider}". Run /login ${provider} first, then try again.`, "error");
+        return;
+      }
+
+      if (!this.runtime.isOAuthEntry(entry)) {
+        const ok = await ctx.ui.confirm(
+          "Import non-OAuth auth entry?",
+          `"${provider}" exists in ${PI_AUTH_PATH} but is not marked as OAuth. Import anyway?`,
+        );
+        if (!ok) return;
+      }
+
+      const label = (await ctx.ui.input("Account label", `${provider} — Work`))?.trim();
+      if (!label) return;
+
+      const suggested = commonUtil.slugify(label);
+      const id = (await ctx.ui.input("Account id", suggested))?.trim() || suggested;
+
+      const account: AccountConfig = { id, label, provider, piAuth: { provider, entry } };
+      const saved = await this.saveAccount(ctx, account);
+      if (!saved) return;
+
+      ctx.ui.notify(`Imported OAuth account "${saved.label}".`, "info");
+    } catch (error) {
+      ctx.ui.notify(`Failed to import OAuth account: ${errorUtil.format(error)}`, "error");
+    }
+  }
+}