@elvatis_com/openclaw-cli-bridge-elvatis 0.2.22 → 0.2.23

package/README.md

@@ -2,7 +2,7 @@
 
 > OpenClaw plugin that bridges locally installed AI CLIs (Codex, Gemini, Claude Code) as model providers — with slash commands for instant model switching, restore, health testing, and model listing.
 
-**Current version:** `0.2.22`
+**Current version:** `0.2.23`
 
 ---
 
@@ -287,6 +287,9 @@ npm test            # vitest run (45 tests)
 
 ## Changelog
 
+### v0.2.23
+- **feat:** Proactive OAuth token management (`src/claude-auth.ts`) — the proxy now reads `~/.claude/.credentials.json` at startup, schedules a refresh 30 minutes before expiry, and calls `ensureClaudeToken()` before every `claude` subprocess invocation. On 401 responses, automatically retries once after refreshing. Eliminates the need for manual re-login after token expiry in headless/systemd deployments.
+
 ### v0.2.22
 - **fix:** `runClaude()` now detects expired/invalid OAuth tokens immediately (401 in stderr) and throws a clear actionable error instead of waiting for the 30s proxy timeout. Error message includes the exact re-login command.
 

package/SKILL.md

@@ -53,4 +53,4 @@ Each command runs `openclaw models set <model>` atomically and replies with a co
 
 See `README.md` for full configuration reference and architecture diagram.
 
-**Version:** 0.2.22
+**Version:** 0.2.23

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-cli-bridge-elvatis",
   "name": "OpenClaw CLI Bridge",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "description": "Phase 1: openai-codex auth bridge. Phase 2: local HTTP proxy routing model calls through gemini/claude CLIs (vllm provider).",
   "providers": [
     "openai-codex"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elvatis_com/openclaw-cli-bridge-elvatis",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "description": "Bridges gemini, claude, and codex CLI tools as OpenClaw model providers. Reads existing CLI auth without re-login.",
   "type": "module",
   "openclaw": {

package/src/claude-auth.ts

@@ -0,0 +1,223 @@
+/**
+ * claude-auth.ts
+ *
+ * Proactive OAuth token management for the Claude Code CLI.
+ *
+ * Problem: Claude Code stores its claude.ai OAuth token in
+ * ~/.claude/.credentials.json. The access token expires every ~8-12 hours.
+ * When the gateway runs as a systemd service without a browser, the normal
+ * interactive refresh flow never triggers — the token silently expires and
+ * every CLI call returns 401.
+ *
+ * Solution: This module reads the credentials file, tracks expiry, and
+ * proactively refreshes the token by running `claude -p "ping"` before it
+ * expires. It also retries once on 401 errors.
+ *
+ * Design:
+ *   - scheduleTokenRefresh()  — call once at proxy startup; sets an internal
+ *                               timer that fires 30 min before expiry
+ *   - ensureClaudeToken()     — call before every claude CLI invocation;
+ *                               triggers an immediate refresh if token is
+ *                               expired or expires within the next 5 minutes
+ *   - refreshClaudeToken()    — runs `claude -p "ping"` to force token refresh
+ *                               (Claude Code auto-refreshes on any API call)
+ */
+
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Config
+// ──────────────────────────────────────────────────────────────────────────────
+
+/** Refresh this many ms before the token actually expires. */
+const REFRESH_BEFORE_EXPIRY_MS = 30 * 60 * 1000; // 30 min
+
+/** If token expires within this window, refresh synchronously before the call. */
+const REFRESH_SYNC_WINDOW_MS = 5 * 60 * 1000; // 5 min
+
+/** Max time to wait for a refresh ping. */
+const REFRESH_TIMEOUT_MS = 30_000;
+
+const CREDENTIALS_PATH = join(homedir(), ".claude", ".credentials.json");
+
+// ──────────────────────────────────────────────────────────────────────────────
+// State
+// ──────────────────────────────────────────────────────────────────────────────
+
+let refreshTimer: ReturnType<typeof setTimeout> | null = null;
+let refreshInProgress: Promise<void> | null = null;
+let log: (msg: string) => void = () => {};
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Public API
+// ──────────────────────────────────────────────────────────────────────────────
+
+/** Configure the logger (call once at startup). */
+export function setAuthLogger(logger: (msg: string) => void): void {
+  log = logger;
+}
+
+/**
+ * Read the current token expiry from ~/.claude/.credentials.json.
+ * Returns null if the file doesn't exist or has no OAuth credentials
+ * (e.g. API-key users — they don't need token management).
+ */
+export async function readTokenExpiry(): Promise<number | null> {
+  try {
+    const raw = await readFile(CREDENTIALS_PATH, "utf8");
+    const creds = JSON.parse(raw) as {
+      claudeAiOauth?: { expiresAt?: number };
+    };
+    const expiresAt = creds?.claudeAiOauth?.expiresAt;
+    return typeof expiresAt === "number" ? expiresAt : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Schedule a proactive token refresh 30 minutes before expiry.
+ * Call once at proxy startup. Safe to call multiple times (clears old timer).
+ */
+export async function scheduleTokenRefresh(): Promise<void> {
+  if (refreshTimer) {
+    clearTimeout(refreshTimer);
+    refreshTimer = null;
+  }
+
+  const expiresAt = await readTokenExpiry();
+  if (expiresAt === null) {
+    log("[cli-bridge:auth] No OAuth credentials found — skipping token scheduling (API key auth?)");
+    return;
+  }
+
+  const now = Date.now();
+  const msUntilExpiry = expiresAt - now;
+  const msUntilRefresh = msUntilExpiry - REFRESH_BEFORE_EXPIRY_MS;
+
+  if (msUntilExpiry <= 0) {
+    log("[cli-bridge:auth] Token already expired — refreshing now");
+    await refreshClaudeToken();
+    return;
+  }
+
+  if (msUntilRefresh <= 0) {
+    // Expires within the next 30 min — refresh immediately
+    log(`[cli-bridge:auth] Token expires in ${Math.round(msUntilExpiry / 60000)}min — refreshing now`);
+    await refreshClaudeToken();
+    return;
+  }
+
+  const refreshInMin = Math.round(msUntilRefresh / 60000);
+  log(`[cli-bridge:auth] Token valid for ${Math.round(msUntilExpiry / 60000)}min — refresh scheduled in ${refreshInMin}min`);
+
+  refreshTimer = setTimeout(async () => {
+    log("[cli-bridge:auth] Scheduled token refresh triggered");
+    await refreshClaudeToken();
+    // Re-schedule for the next cycle after refresh
+    await scheduleTokenRefresh();
+  }, msUntilRefresh);
+
+  // Don't block process exit
+  if (refreshTimer.unref) refreshTimer.unref();
+}
+
+/**
+ * Ensure the Claude OAuth token is valid before making a CLI call.
+ * If the token expires within REFRESH_SYNC_WINDOW_MS, refreshes synchronously.
+ * No-op for API-key users (no credentials file).
+ */
+export async function ensureClaudeToken(): Promise<void> {
+  const expiresAt = await readTokenExpiry();
+  if (expiresAt === null) return; // API key user, nothing to do
+
+  const msUntilExpiry = expiresAt - Date.now();
+
+  if (msUntilExpiry > REFRESH_SYNC_WINDOW_MS) return; // still valid, nothing to do
+
+  if (msUntilExpiry <= 0) {
+    log("[cli-bridge:auth] Token expired — refreshing before call");
+  } else {
+    log(`[cli-bridge:auth] Token expires in ${Math.round(msUntilExpiry / 1000)}s — refreshing before call`);
+  }
+
+  await refreshClaudeToken();
+}
+
+/**
+ * Run `claude -p "ping"` to force Claude Code to refresh its OAuth token.
+ * Claude Code automatically refreshes the access token on any API call.
+ * Deduplicates concurrent refresh attempts.
+ */
+export async function refreshClaudeToken(): Promise<void> {
+  // Deduplicate concurrent refresh calls
+  if (refreshInProgress) {
+    await refreshInProgress;
+    return;
+  }
+
+  refreshInProgress = doRefresh();
+  try {
+    await refreshInProgress;
+  } finally {
+    refreshInProgress = null;
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Internal
+// ──────────────────────────────────────────────────────────────────────────────
+
+async function doRefresh(): Promise<void> {
+  log("[cli-bridge:auth] Refreshing Claude OAuth token...");
+
+  const result = await runRefreshPing();
+
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr || "(no output)";
+    if (stderr.includes("401") || stderr.includes("authentication_error") || stderr.includes("Invalid authentication credentials")) {
+      throw new Error(
+        "Claude CLI OAuth token refresh failed (401). " +
+        "Re-login required: run `claude auth logout && claude auth login` in a terminal."
+      );
+    }
+    // Non-auth errors (network blip etc.) — log but don't throw, let the actual call fail naturally
+    log(`[cli-bridge:auth] Token refresh exited ${result.exitCode}: ${stderr.slice(0, 200)}`);
+    return;
+  }
+
+  // Re-read expiry and reschedule timer
+  const newExpiry = await readTokenExpiry();
+  if (newExpiry) {
+    const validForMin = Math.round((newExpiry - Date.now()) / 60000);
+    log(`[cli-bridge:auth] Token refreshed — valid for ${validForMin}min`);
+    // Reschedule the proactive timer for the new expiry
+    void scheduleTokenRefresh();
+  }
+}
+
+function runRefreshPing(): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  return new Promise((resolve) => {
+    const env: Record<string, string> = { NO_COLOR: "1", TERM: "dumb" };
+    for (const key of ["HOME", "PATH", "USER", "XDG_RUNTIME_DIR", "DBUS_SESSION_BUS_ADDRESS", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME"]) {
+      const v = process.env[key];
+      if (v) env[key] = v;
+    }
+
+    const proc = spawn(
+      "claude",
+      ["-p", "ping", "--output-format", "text", "--permission-mode", "plan", "--tools", ""],
+      { timeout: REFRESH_TIMEOUT_MS, env }
+    );
+
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (d: Buffer) => { stdout += d.toString(); });
+    proc.stderr.on("data", (d: Buffer) => { stderr += d.toString(); });
+    proc.on("close", (code) => resolve({ stdout: stdout.trim(), stderr: stderr.trim(), exitCode: code ?? 0 }));
+    proc.on("error", (err) => resolve({ stdout: "", stderr: err.message, exitCode: 1 }));
+  });
+}

package/src/cli-runner.ts

@@ -14,6 +14,7 @@
 
 import { spawn } from "node:child_process";
 import { tmpdir, homedir } from "node:os";
+import { ensureClaudeToken, refreshClaudeToken } from "./claude-auth.js";
 
 /** Max messages to include in the prompt sent to the CLI. */
 const MAX_MESSAGES = 20;
@@ -253,6 +254,10 @@ export async function runClaude(
   modelId: string,
   timeoutMs: number
 ): Promise<string> {
+  // Proactively refresh OAuth token if it's about to expire (< 5 min remaining).
+  // No-op for API-key users.
+  await ensureClaudeToken();
+
   const model = stripPrefix(modelId);
   const args = [
     "-p",
@@ -261,17 +266,27 @@ export async function runClaude(
     "--tools", "",
     "--model", model,
   ];
+
   const result = await runCli("claude", args, prompt, timeoutMs);
 
+  // On 401: attempt one token refresh + retry before giving up.
   if (result.exitCode !== 0 && result.stdout.length === 0) {
     const stderr = result.stderr || "(no output)";
-    // Detect expired/invalid OAuth token early and give a clear actionable message
-    // instead of letting the caller time out after 30s.
     if (stderr.includes("401") || stderr.includes("Invalid authentication credentials") || stderr.includes("authentication_error")) {
-      throw new Error(
-        "Claude CLI OAuth token expired or invalid. " +
-        "Re-login required: run `claude auth logout && claude auth login` in a terminal, then retry."
-      );
+      // Refresh and retry once
+      await refreshClaudeToken();
+      const retry = await runCli("claude", args, prompt, timeoutMs);
+      if (retry.exitCode !== 0 && retry.stdout.length === 0) {
+        const retryStderr = retry.stderr || "(no output)";
+        if (retryStderr.includes("401") || retryStderr.includes("authentication_error") || retryStderr.includes("Invalid authentication credentials")) {
+          throw new Error(
+            "Claude CLI OAuth token refresh failed. " +
+            "Re-login required: run `claude auth logout && claude auth login` in a terminal."
+          );
+        }
+        throw new Error(`claude exited ${retry.exitCode} (after token refresh): ${retryStderr}`);
+      }
+      return retry.stdout;
     }
     throw new Error(`claude exited ${result.exitCode}: ${stderr}`);
   }

package/src/proxy-server.ts

@@ -11,6 +11,7 @@
 import http from "node:http";
 import { randomBytes } from "node:crypto";
 import { type ChatMessage, routeToCliRunner } from "./cli-runner.js";
+import { scheduleTokenRefresh, setAuthLogger } from "./claude-auth.js";
 
 export interface ProxyServerOptions {
   port: number;
@@ -81,6 +82,9 @@ export function startProxyServer(opts: ProxyServerOptions): Promise<http.Server>
       opts.log(
         `[cli-bridge] proxy server listening on http://127.0.0.1:${opts.port}`
       );
+      // Start proactive OAuth token refresh scheduler for Claude Code CLI.
+      setAuthLogger(opts.log);
+      void scheduleTokenRefresh();
       resolve(server);
     });
   });