docs: document OpenCode plugin blocking issue (#11)

- Add Known Limitations section to troubleshooting docs explaining that
  OpenCode blocks this plugin by design (skips plugins with
  'opencode-openai-codex-auth' in the name)
- Add prominent warning to README about the issue
- Include OPENCODE_PR_PROPOSAL.md with upstream fix proposal
- Fix: remove debug console.log statements from loader
- Fix: check multiAccount flag before handling auth (coexist with built-in)

Closes #11

Author: ndycode

CHANGELOG.md

@@ -7,6 +7,8 @@ All notable changes to this project are documented here. Dates use the ISO forma
 ### Added
 
 ### Changed
+- Fix Node ESM plugin load by importing tool from `@opencode-ai/plugin/tool` and ensuring runtime dependency is installed.
+- Correct package metadata (repository links, update-check package name) and add troubleshooting guidance for plugin install/load.
 
 ## [4.7.0] - 2026-01-25
 

README.md

@@ -2,11 +2,14 @@
 
 [![npm version](https://img.shields.io/npm/v/opencode-openai-codex-auth-multi.svg)](https://www.npmjs.com/package/opencode-openai-codex-auth-multi)
 [![npm downloads](https://img.shields.io/npm/dw/opencode-openai-codex-auth-multi.svg)](https://www.npmjs.com/package/opencode-openai-codex-auth-multi)
-[![Tests](https://github.com/ndycode/opencode-openai-codex-auth-multi/actions/workflows/ci.yml/badge.svg)](https://github.com/ndycode/opencode-openai-codex-auth-multi/actions)
+[![Tests](https://github.com/ndycode/opencode-chatgpt-multi-auth/actions/workflows/ci.yml/badge.svg)](https://github.com/ndycode/opencode-chatgpt-multi-auth/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 Enable OpenCode to authenticate against **OpenAI's Codex backend** via OAuth so you can use ChatGPT Plus/Pro rate limits and access models like `gpt-5.2`, `gpt-5.2-codex`, and `gpt-5.1-codex-max` with your ChatGPT credentials.
 
+> [!WARNING]
+> **Known Issue:** OpenCode currently blocks this plugin by design. The plugin downloads but never loads because OpenCode's plugin loader skips plugins containing `opencode-openai-codex-auth` in the name (to prevent conflicts with the built-in auth). We're working on an upstream fix. See [Issue #11](https://github.com/ndycode/opencode-chatgpt-multi-auth/issues/11) and [Troubleshooting](docs/troubleshooting.md#known-limitations) for details.
+
 ## What You Get
 
 - **GPT-5.2, GPT-5.2 Codex, GPT-5.1 Codex Max** and all GPT-5.x variants via ChatGPT OAuth
@@ -48,7 +51,7 @@ Enable OpenCode to authenticate against **OpenAI's Codex backend** via OAuth so
 Paste this into any LLM agent (Claude Code, OpenCode, Cursor, etc.):
 
 ```
-Install the opencode-openai-codex-auth-multi plugin and add the OpenAI model definitions to ~/.config/opencode/opencode.json by following: https://raw.githubusercontent.com/ndycode/opencode-openai-codex-auth-multi/main/README.md
+Install the opencode-openai-codex-auth-multi plugin and add the OpenAI model definitions to ~/.config/opencode/opencode.json by following: https://raw.githubusercontent.com/ndycode/opencode-chatgpt-multi-auth/main/README.md
 ```
 
 **Option B: One-command install**

docs/OPENCODE_PR_PROPOSAL.md

@@ -0,0 +1,96 @@
+# OpenCode PR: Merge Auth Methods from Multiple Plugins
+
+## Problem
+
+When multiple plugins register for the same provider (e.g., `openai`), only the first plugin's auth methods are shown. This is because `auth.ts:310` uses `.find()` which returns the first match:
+
+```typescript
+const plugin = await Plugin.list().then((x) => x.find((x) => x.auth?.provider === provider))
+```
+
+Since internal plugins (like `CodexAuthPlugin`) load before external plugins, external plugins can never add auth methods to providers that have internal plugins.
+
+## Use Case
+
+Multi-account authentication plugins need to add their auth methods alongside built-in options. For example:
+- Built-in: "ChatGPT Pro/Plus" 
+- External: "ChatGPT Pro/Plus (Multi-Account)"
+
+Users should see both options when selecting OpenAI provider.
+
+## Proposed Solution
+
+Change `auth.ts` to collect and merge auth methods from ALL plugins that register for the same provider:
+
+### Current Code (auth.ts lines 310-314)
+
+```typescript
+const plugin = await Plugin.list().then((x) => x.find((x) => x.auth?.provider === provider))
+if (plugin && plugin.auth) {
+  const handled = await handlePluginAuth({ auth: plugin.auth }, provider)
+  if (handled) return
+}
+```
+
+### Proposed Code
+
+```typescript
+// Collect auth methods from ALL plugins that register for this provider
+const matchingPlugins = await Plugin.list().then((x) => 
+  x.filter((x) => x.auth?.provider === provider)
+)
+
+if (matchingPlugins.length > 0) {
+  // Merge methods from all matching plugins
+  const mergedMethods = matchingPlugins.flatMap((p) => p.auth?.methods ?? [])
+  
+  // Use the first plugin's loader (internal plugins take precedence)
+  const primaryPlugin = matchingPlugins[0]
+  
+  const handled = await handlePluginAuth(
+    { 
+      auth: {
+        ...primaryPlugin.auth!,
+        methods: mergedMethods,
+      }
+    }, 
+    provider
+  )
+  if (handled) return
+}
+```
+
+### Also update lines 326-330 (custom provider handling)
+
+```typescript
+// Same pattern for custom providers
+const customPlugins = await Plugin.list().then((x) => 
+  x.filter((x) => x.auth?.provider === provider)
+)
+if (customPlugins.length > 0) {
+  const mergedMethods = customPlugins.flatMap((p) => p.auth?.methods ?? [])
+  const primaryPlugin = customPlugins[0]
+  const handled = await handlePluginAuth(
+    { auth: { ...primaryPlugin.auth!, methods: mergedMethods } }, 
+    provider
+  )
+  if (handled) return
+}
+```
+
+## Benefits
+
+1. **Backward Compatible**: Existing behavior unchanged for providers with single plugin
+2. **Extensible**: External plugins can add auth methods to any provider
+3. **Priority Preserved**: Internal plugins' loaders still take precedence
+4. **Minimal Change**: ~10 lines changed, no new dependencies
+
+## Testing
+
+1. Install an external plugin that registers for `openai` provider
+2. Run `opencode auth login` → select "OpenAI"
+3. Verify both internal and external auth methods appear in the list
+
+## Alternative Considered
+
+Have external plugins use different provider IDs (e.g., `openai-multi`), but this requires users to manually type the provider ID via "Other", which is poor UX.

docs/troubleshooting.md

@@ -8,6 +8,73 @@ Common issues and debugging techniques for the OpenCode OpenAI Codex Auth Plugin
 
 ---
 
+## Known Limitations
+
+<details open>
+<summary><b>⚠️ OpenCode blocks this plugin by design</b></summary>
+
+**Status:** This is a known issue affecting all users.
+
+**What's happening:**
+
+OpenCode's plugin loader explicitly skips plugins with `opencode-openai-codex-auth` in the name (see `packages/opencode/src/plugin/index.ts` line ~53):
+
+```typescript
+if (plugin.includes("opencode-openai-codex-auth") || plugin.includes("opencode-copilot-auth")) continue
+```
+
+This is intentional — OpenCode has built-in `CodexAuthPlugin` and `CopilotAuthPlugin` that handle OAuth for these providers. External plugins are blocked to prevent conflicts.
+
+**Impact:**
+- The plugin downloads successfully
+- The plugin is present in `~/.cache/opencode/node_modules/`
+- But it never loads or executes
+- No logs appear in `~/.opencode/logs/codex-plugin/`
+
+**Workarounds:**
+
+1. **Wait for upstream fix** — We've submitted a [PR proposal](OPENCODE_PR_PROPOSAL.md) to allow multiple auth plugins per provider
+2. **Use a patched OpenCode fork** — For advanced users only (requires building from source)
+3. **Use the built-in single-account auth** — Run `opencode auth login` without this plugin
+
+**Tracking:** [Issue #11](https://github.com/ndycode/opencode-chatgpt-multi-auth/issues/11)
+
+</details>
+
+---
+
+## Installation & Loading Issues
+
+<details open>
+<summary><b>Plugin not downloading / no logs</b></summary>
+
+**Symptoms:**
+- Plugin folder missing under `~/.cache/opencode/node_modules/`
+- No files in `~/.opencode/logs/codex-plugin/` even with logging enabled
+
+**Checks:**
+1. **Verify config path and plugin list**:
+   - Global: `~/.config/opencode/opencode.json`
+   - Project: `./.opencode.json`
+   - Entry should include: `"plugin": ["opencode-openai-codex-auth-multi@latest"]`
+2. **Confirm plugin cache location** (npm plugins are cached, not stored in `~/.opencode/plugins/`):
+   ```bash
+   ls ~/.cache/opencode/node_modules/opencode-openai-codex-auth-multi
+   ```
+3. **Remember: request logs only appear after the first OpenAI request**:
+   ```bash
+   ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "test" --model=openai/gpt-5.2
+   ```
+4. **Check registry access**:
+   ```bash
+   npm view opencode-openai-codex-auth-multi version
+   ```
+5. **If the plugin is present but still won’t load**, upgrade to v4.8.1+ (fixes Node ESM load issues with `@opencode-ai/plugin`).
+
+</details>
+
+---
+
 ## Authentication Issues
 
 <details open>

index.ts

@@ -23,7 +23,8 @@
 
  */
 
-import { tool, type Plugin, type PluginInput } from "@opencode-ai/plugin";
+import { tool } from "@opencode-ai/plugin/tool";
+import type { Plugin, PluginInput } from "@opencode-ai/plugin";
 import type { Auth } from "@opencode-ai/sdk";
 import {
         createAuthorizationFlow,
@@ -108,8 +109,8 @@ import {
  * }
  * ```
  */
-export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
-        let cachedAccountManager: AccountManager | null = null;
+export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
+	let cachedAccountManager: AccountManager | null = null;
 
         type TokenSuccess = Extract<TokenResult, { type: "success" }>;
 
@@ -238,9 +239,9 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 						}
 					}
 
-				for (const result of results) {
-						const accountId = extractAccountId(result.access);
-						const accountEmail = sanitizeEmail(extractAccountEmail(result.access));
+			for (const result of results) {
+					const accountId = extractAccountId(result.access);
+					const accountEmail = sanitizeEmail(extractAccountEmail(result.access, result.idToken));
 						const existingByEmail =
 								accountEmail && indexByEmail.has(accountEmail)
 										? indexByEmail.get(accountEmail)
@@ -383,7 +384,7 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
                                         const refreshed = await queuedRefresh(account.refreshToken);
                                         if (refreshed.type !== "success") return;
                                         const id = extractAccountId(refreshed.access);
-                                        const email = sanitizeEmail(extractAccountEmail(refreshed.access));
+                                        const email = sanitizeEmail(extractAccountEmail(refreshed.access, refreshed.idToken));
                                         if (id && id !== account.accountId) {
                                                 account.accountId = id;
                                                 changed = true;
@@ -442,7 +443,14 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 				return `resets in ${formatWaitTime(remaining)}`;
 		};
 
+        // Event handler for session recovery (matches antigravity plugin pattern)
+        const eventHandler = async (_input: { event: { type: string; properties?: unknown } }) => {
+                // Session recovery is handled inside the loader, but we need to expose the event handler
+                // to match the antigravity plugin structure that OpenCode expects
+        };
+
         return {
+                event: eventHandler,
                 auth: {
 			provider: PROVIDER_ID,
 			/**
@@ -459,13 +467,21 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 			 * @param provider - Provider configuration from opencode.json
 			 * @returns SDK configuration object or empty object for non-OAuth auth
 			 */
-			async loader(getAuth: () => Promise<Auth>, provider: unknown) {
-				const auth = await getAuth();
-
-				// Only handle OAuth auth type, skip API key auth
-				if (auth.type !== "oauth") {
-					return {};
-				}
+		async loader(getAuth: () => Promise<Auth>, provider: unknown) {
+			const auth = await getAuth();
+
+			// Only handle OAuth auth type, skip API key auth
+			if (auth.type !== "oauth") {
+				return {};
+			}
+
+			// Only handle multi-account auth (identified by multiAccount flag)
+			// If auth was created by built-in plugin, let built-in handle it
+			const authWithMulti = auth as typeof auth & { multiAccount?: boolean };
+			if (!authWithMulti.multiAccount) {
+				logDebug(`[${PLUGIN_NAME}] Auth is not multi-account, skipping loader`);
+				return {};
+			}
 
                                 const accountManager = await AccountManager.loadFromDisk(
                                         auth as OAuthAuthDetails,
@@ -811,7 +827,8 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 					 * @returns Authorization flow configuration
 					 */
                                         authorize: async (inputs?: Record<string, string>) => {
-                                                if (inputs) {
+                                                console.log(`[DEBUG] authorize called, inputs:`, JSON.stringify(inputs));
+                                                if (inputs && Object.keys(inputs).length > 0) {
                                                         const accounts: TokenSuccess[] = [];
                                                         const noBrowser =
                                                                 inputs.noBrowser === "true" ||
@@ -850,17 +867,17 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 					const forceNewLogin = accounts.length > 0;
 					const result = await runOAuthFlow(useManualMode, forceNewLogin);
 
-					if (result.type === "success") {
-						const email = extractAccountEmail(result.access);
-						const accountId = extractAccountId(result.access);
-						const label = email || accountId || "Unknown account";
-						console.log(`\n✓ Authenticated as: ${label}\n`);
+				if (result.type === "success") {
+					const email = extractAccountEmail(result.access, result.idToken);
+					const accountId = extractAccountId(result.access);
+					const label = email || accountId || "Unknown account";
+					console.log(`\n✓ Authenticated as: ${label}\n`);
 
-						const isDuplicate = accounts.some(
-							(acc) =>
-								(accountId && extractAccountId(acc.access) === accountId) ||
-								(email && extractAccountEmail(acc.access) === email),
-						);
+					const isDuplicate = accounts.some(
+						(acc) =>
+							(accountId && extractAccountId(acc.access) === accountId) ||
+							(email && extractAccountEmail(acc.access, acc.idToken) === email),
+					);
 
 						if (isDuplicate) {
 							console.warn(
@@ -959,6 +976,23 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
                                                         };
                                                 }
 
+                                                let startFresh = true;
+                                                const existingStorage = await hydrateEmails(await loadAccounts());
+                                                if (existingStorage && existingStorage.accounts.length > 0) {
+                                                        const existingAccounts = existingStorage.accounts.map((account, index) => ({
+                                                                accountId: account.accountId,
+                                                                email: account.email,
+                                                                index,
+                                                        }));
+                                                        const loginMode = await promptLoginMode(existingAccounts);
+                                                        startFresh = loginMode === "fresh";
+                                                        if (startFresh) {
+                                                                console.log("\nStarting fresh - existing accounts will be replaced.\n");
+                                                        } else {
+                                                                console.log("\nAdding to existing accounts.\n");
+                                                        }
+                                                }
+
                                                 const { pkce, state, url } = await createAuthorizationFlow();
                                                 let serverInfo: Awaited<ReturnType<typeof startLocalOAuthServer>> | null =
                                                         null;
@@ -974,7 +1008,7 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
                                                 if (!serverInfo || !serverInfo.ready) {
                                                         serverInfo?.close();
                                                         return buildManualOAuthFlow(pkce, url, async (tokens) => {
-                                                                await persistAccountPool([tokens], false);
+                                                                await persistAccountPool([tokens], startFresh);
                                                         });
                                                 }
 
@@ -997,7 +1031,7 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
                                                                 );
 
                                                                 if (tokens?.type === "success") {
-                                                                        await persistAccountPool([tokens], false);
+                                                                        await persistAccountPool([tokens], startFresh);
                                                                 }
 
                                                                 return tokens?.type === "success"
@@ -1268,4 +1302,6 @@ export const OpenAIAuthPlugin: Plugin = async ({ client }: PluginInput) => {
         };
 };
 
-export default OpenAIAuthPlugin;
+export const OpenAIAuthPlugin = OpenAIOAuthPlugin;
+
+export default OpenAIOAuthPlugin;