feat: auto-refresh opencode plugin cache

Author: ndycode

README.md

@@ -41,6 +41,8 @@ What the installer does:
 - normalizes the plugin entry to `"oc-codex-multi-auth"`
 - clears the cached plugin copy so OpenCode reinstalls the latest package
 
+After install, the plugin checks npm once per day. When a newer version exists, it clears its OpenCode-managed cached package on exit; restart OpenCode and the latest package is installed automatically. Disable this with `"autoUpdate": false` in `~/.opencode/openai-codex-auth-config.json` or `CODEX_AUTH_AUTO_UPDATE=0`.
+
 By default, the installer writes the compact UI config:
 - model picker entries stay on actual OAuth model families such as `gpt-5.5` and `gpt-5.5-fast`
 - reasoning presets are selected through OpenCode's model variant picker (`none`, `low`, `medium`, `high`, `xhigh`)
@@ -86,6 +88,7 @@ OpenCode users often want the same GPT-5 and Codex model experience they use in
 - Beginner-focused commands such as `codex-setup`, `codex-help`, `codex-doctor`, and `codex-next`
 - Interactive account switching, labeling, tagging, and backup/import commands
 - Stateless request handling with `reasoning.encrypted_content` for multi-turn sessions
+- Daily npm update detection with OpenCode cache refresh on restart
 - Request logging and troubleshooting hooks for debugging OpenCode integration issues
 
 ## Common Workflows

docs/configuration.md

@@ -131,6 +131,7 @@ advanced settings go in `~/.opencode/openai-codex-auth-config.json`:
     "server": 2
   },
   "perProjectAccounts": true,
+  "autoUpdate": true,
   "toastDurationMs": 5000,
   "retryAllAccountsRateLimited": true,
   "retryAllAccountsMaxWaitMs": 0,
@@ -163,6 +164,7 @@ The sample above intentionally sets `"retryAllAccountsMaxRetries": 3` as a bound
 | `retryProfile` | `balanced` | retry budget profile for request classes (`conservative`, `balanced`, `aggressive`) |
 | `retryBudgetOverrides` | `{}` | optional per-class budget overrides (`authRefresh`, `network`, `server`, `rateLimitShort`, `rateLimitGlobal`, `emptyResponse`) |
 | `perProjectAccounts` | `true` | each project gets its own account storage |
+| `autoUpdate` | `true` | check npm daily and clear the OpenCode-managed plugin cache on exit when a newer version is available; restart OpenCode to install it |
 | `toastDurationMs` | `5000` | how long toast notifications stay visible (ms) |
 | `retryAllAccountsRateLimited` | `true` | wait and retry when all accounts hit rate limits |
 | `retryAllAccountsMaxWaitMs` | `0` | max wait time in ms (0 = unlimited) |
@@ -244,6 +246,7 @@ override any config with env vars:
 | `CODEX_AUTH_BEGINNER_SAFE_MODE=1` | enable beginner-safe retry behavior |
 | `CODEX_AUTH_RETRY_PROFILE=aggressive` | override retry profile (`conservative`, `balanced`, `aggressive`) |
 | `CODEX_AUTH_PER_PROJECT_ACCOUNTS=0` | disable per-project accounts |
+| `CODEX_AUTH_AUTO_UPDATE=0` | disable automatic OpenCode plugin cache refresh when npm has a newer plugin version |
 | `CODEX_AUTH_TOAST_DURATION_MS=8000` | set toast duration |
 | `CODEX_AUTH_RETRY_ALL_RATE_LIMITED=0` | disable wait-and-retry |
 | `CODEX_AUTH_RETRY_ALL_MAX_WAIT_MS=30000` | set max wait time |

index.ts

@@ -70,6 +70,7 @@ import {
 	getTokenRefreshSkewMs,
 	getSessionRecovery,
 	getAutoResume,
+	getAutoUpdate,
 	getToastDurationMs,
 	getPerProjectAccounts,
 	getEmptyResponseMaxRetries,
@@ -1545,6 +1546,7 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 
 				const sessionRecoveryEnabled = getSessionRecovery(pluginConfig);
 				const autoResumeEnabled = getAutoResume(pluginConfig);
+				const autoUpdateEnabled = getAutoUpdate(pluginConfig);
 				const emptyResponseMaxRetries = getEmptyResponseMaxRetries(pluginConfig);
 				const emptyResponseRetryDelayMs = getEmptyResponseRetryDelayMs(pluginConfig);
 				const pidOffsetEnabled = getPidOffsetEnabled(pluginConfig);
@@ -1591,7 +1593,7 @@ export const OpenAIOAuthPlugin: Plugin = async ({ client }: PluginInput) => {
 
 			checkAndNotify(async (message, variant) => {
 				await showToast(message, variant);
-			}).catch((err) => {
+			}, { autoUpdate: autoUpdateEnabled }).catch((err) => {
 				logDebug(`Update check failed: ${err instanceof Error ? err.message : String(err)}`);
 			});
 			await runStartupPreflight();

lib/auto-update-checker.ts

@@ -1,15 +1,18 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { createLogger } from "./logger.js";
 
 const log = createLogger("update-checker");
 
 const PACKAGE_NAME = "oc-codex-multi-auth";
+const LEGACY_PACKAGE_NAMES = ["oc-chatgpt-multi-auth"];
 const NPM_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
 const CACHE_DIR = join(homedir(), ".opencode", "cache");
 const CACHE_FILE = join(CACHE_DIR, "update-check-cache.json");
+const OPENCODE_CACHE_DIR = join(homedir(), ".cache", "opencode");
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+let cacheEvictionScheduled = false;
 
 interface UpdateCheckCache {
   lastCheck: number;
@@ -98,6 +101,52 @@ export interface UpdateCheckResult {
   updateCommand: string;
 }
 
+export interface CheckAndNotifyOptions {
+  autoUpdate?: boolean;
+  scheduleCacheClear?: () => boolean;
+}
+
+function getManagedPackageNames(): string[] {
+  return [PACKAGE_NAME, ...LEGACY_PACKAGE_NAMES];
+}
+
+function getManagedCachePaths(): string[] {
+  return getManagedPackageNames().flatMap((name) => [
+    join(OPENCODE_CACHE_DIR, "packages", `${name}@latest`),
+    join(OPENCODE_CACHE_DIR, "node_modules", name),
+  ]);
+}
+
+export function clearManagedOpenCodePluginCache(paths = getManagedCachePaths()): boolean {
+  let cleared = false;
+
+  for (const cachePath of paths) {
+    try {
+      if (!existsSync(cachePath)) continue;
+      rmSync(cachePath, { recursive: true, force: true });
+      cleared = true;
+      log.info("Cleared OpenCode plugin cache for update", { path: cachePath });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      log.warn("Failed to clear OpenCode plugin cache for update", {
+        path: cachePath,
+        error: message,
+      });
+    }
+  }
+
+  return cleared;
+}
+
+export function scheduleOpenCodePluginCacheClearOnExit(): boolean {
+  if (cacheEvictionScheduled) return true;
+  cacheEvictionScheduled = true;
+  process.once("exit", () => {
+    clearManagedOpenCodePluginCache();
+  });
+  return true;
+}
+
 export async function checkForUpdates(force = false): Promise<UpdateCheckResult> {
   const currentVersion = getCurrentVersion();
   const cache = loadCache();
@@ -133,19 +182,24 @@ export async function checkForUpdates(force = false): Promise<UpdateCheckResult>
 
 export async function checkAndNotify(
   showToast?: (message: string, variant: "info" | "warning") => Promise<void>,
+  options: CheckAndNotifyOptions = {},
 ): Promise<void> {
   try {
     const result = await checkForUpdates();
 
     if (result.hasUpdate && result.latestVersion) {
       const message = `Update available: ${PACKAGE_NAME} v${result.latestVersion} (current: v${result.currentVersion})`;
       log.info(message);
+      const autoUpdate = options.autoUpdate ?? true;
+      const scheduled = autoUpdate
+        ? (options.scheduleCacheClear ?? scheduleOpenCodePluginCacheClearOnExit)()
+        : false;
 
       if (showToast) {
-        await showToast(
-          `Plugin update available: v${result.latestVersion}. Run: ${result.updateCommand}`,
-          "info",
-        );
+        const instruction = scheduled
+          ? "Restart OpenCode to install it automatically."
+          : `Run: ${result.updateCommand}`;
+        await showToast(`Plugin update available: v${result.latestVersion}. ${instruction}`, "info");
       }
     }
   } catch (error) {

lib/config.ts

@@ -54,6 +54,7 @@ const DEFAULT_CONFIG: PluginConfig = {
 	perProjectAccounts: true,
 	sessionRecovery: true,
 	autoResume: true,
+	autoUpdate: true,
 	parallelProbing: false,
 	parallelProbingMaxConcurrency: 2,
 	emptyResponseMaxRetries: 2,
@@ -499,6 +500,14 @@ export function getAutoResume(pluginConfig: PluginConfig): boolean {
 	);
 }
 
+export function getAutoUpdate(pluginConfig: PluginConfig): boolean {
+	return resolveBooleanSetting(
+		"CODEX_AUTH_AUTO_UPDATE",
+		pluginConfig.autoUpdate,
+		true,
+	);
+}
+
 export function getToastDurationMs(pluginConfig: PluginConfig): number {
 	return resolveNumberSetting(
 		"CODEX_AUTH_TOAST_DURATION_MS",

lib/schemas.ts

@@ -45,6 +45,7 @@ export const PluginConfigSchema = z.object({
 	perProjectAccounts: z.boolean().optional(),
 	sessionRecovery: z.boolean().optional(),
 	autoResume: z.boolean().optional(),
+	autoUpdate: z.boolean().optional(),
 	parallelProbing: z.boolean().optional(),
 	parallelProbingMaxConcurrency: z.number().min(1).max(5).optional(),
 	emptyResponseMaxRetries: z.number().min(0).optional(),

test/auto-update-checker.test.ts

@@ -5,13 +5,15 @@ vi.mock("node:fs", () => ({
 	writeFileSync: vi.fn(),
 	existsSync: vi.fn(),
 	mkdirSync: vi.fn(),
+	rmSync: vi.fn(),
 }));
 
 describe("auto-update-checker", () => {
 	let fs: typeof import("node:fs");
 	let checkForUpdates: typeof import("../lib/auto-update-checker.js").checkForUpdates;
 	let checkAndNotify: typeof import("../lib/auto-update-checker.js").checkAndNotify;
 	let clearUpdateCache: typeof import("../lib/auto-update-checker.js").clearUpdateCache;
+	let clearManagedOpenCodePluginCache: typeof import("../lib/auto-update-checker.js").clearManagedOpenCodePluginCache;
 
 	const mockPackageJson = { version: "4.12.0" };
 
@@ -21,6 +23,7 @@ describe("auto-update-checker", () => {
 		vi.setSystemTime(new Date("2026-01-30T12:00:00Z"));
 
 		fs = await import("node:fs");
+		vi.clearAllMocks();
 		vi.mocked(fs.readFileSync).mockImplementation((path: unknown) => {
 			if (String(path).includes("package.json")) {
 				return JSON.stringify(mockPackageJson);
@@ -35,6 +38,7 @@ describe("auto-update-checker", () => {
 		checkForUpdates = module.checkForUpdates;
 		checkAndNotify = module.checkAndNotify;
 		clearUpdateCache = module.clearUpdateCache;
+		clearManagedOpenCodePluginCache = module.clearManagedOpenCodePluginCache;
 	});
 
 	afterEach(() => {
@@ -233,19 +237,41 @@ describe("auto-update-checker", () => {
 	});
 
 	describe("checkAndNotify", () => {
-		it("shows toast when update available", async () => {
+		it("shows restart toast and schedules cache clear when update available", async () => {
 			vi.mocked(globalThis.fetch).mockResolvedValue({
 				ok: true,
 				json: async () => ({ version: "5.0.0" }),
 			} as Response);
 			const showToast = vi.fn().mockResolvedValue(undefined);
+			const scheduleCacheClear = vi.fn(() => true);
 
-			await checkAndNotify(showToast);
+			await checkAndNotify(showToast, { scheduleCacheClear });
+
+			expect(showToast).toHaveBeenCalledWith(
+				expect.stringContaining("Restart OpenCode to install it automatically"),
+				"info"
+			);
+			expect(scheduleCacheClear).toHaveBeenCalledOnce();
+		});
+
+		it("keeps manual update command when autoUpdate is disabled", async () => {
+			vi.mocked(globalThis.fetch).mockResolvedValue({
+				ok: true,
+				json: async () => ({ version: "5.0.0" }),
+			} as Response);
+			const showToast = vi.fn().mockResolvedValue(undefined);
+			const scheduleCacheClear = vi.fn(() => true);
+
+			await checkAndNotify(showToast, {
+				autoUpdate: false,
+				scheduleCacheClear,
+			});
 
 			expect(showToast).toHaveBeenCalledWith(
-				expect.stringContaining("v5.0.0"),
+				expect.stringContaining("Run: npm update -g"),
 				"info"
 			);
+			expect(scheduleCacheClear).not.toHaveBeenCalled();
 		});
 
 		it("does not show toast when no update", async () => {
@@ -301,4 +327,36 @@ describe("auto-update-checker", () => {
 			expect(fs.writeFileSync).not.toHaveBeenCalled();
 		});
 	});
+
+	describe("clearManagedOpenCodePluginCache", () => {
+		it("removes managed OpenCode package cache paths", () => {
+			vi.mocked(fs.existsSync).mockReturnValue(true);
+
+			const cleared = clearManagedOpenCodePluginCache([
+				"C:\\cache\\packages\\oc-codex-multi-auth@latest",
+				"C:\\cache\\node_modules\\oc-codex-multi-auth",
+			]);
+
+			expect(cleared).toBe(true);
+			expect(fs.rmSync).toHaveBeenCalledWith(
+				"C:\\cache\\packages\\oc-codex-multi-auth@latest",
+				{ recursive: true, force: true },
+			);
+			expect(fs.rmSync).toHaveBeenCalledWith(
+				"C:\\cache\\node_modules\\oc-codex-multi-auth",
+				{ recursive: true, force: true },
+			);
+		});
+
+		it("returns false when no managed cache paths exist", () => {
+			vi.mocked(fs.existsSync).mockReturnValue(false);
+
+			const cleared = clearManagedOpenCodePluginCache([
+				"C:\\cache\\packages\\oc-codex-multi-auth@latest",
+			]);
+
+			expect(cleared).toBe(false);
+			expect(fs.rmSync).not.toHaveBeenCalled();
+		});
+	});
 });

test/index.test.ts

@@ -125,6 +125,7 @@ vi.mock("../lib/config.js", () => ({
 	getTokenRefreshSkewMs: () => 60000,
 	getSessionRecovery: () => false,
 	getAutoResume: () => false,
+	getAutoUpdate: () => true,
 	getToastDurationMs: () => 5000,
 	getPerProjectAccounts: () => false,
 	getEmptyResponseMaxRetries: () => 2,