@chatpanel/bridge 0.2.11 → 0.2.13

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@chatpanel/bridge",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "type": "module",
-  "description": "Local bridge that exposes the AI coding agents installed on your machine — Claude Code (Agent SDK), Codex (CLI), and Gemini CLI — to the ChatPanel Chrome extension over a localhost SSE endpoint. Bring your own agent.",
+  "description": "Local bridge that exposes the AI coding agents installed on your machine — Claude Code (CLI), Codex (CLI), and Gemini CLI — to the ChatPanel Chrome extension over a localhost SSE endpoint. Bring your own agent.",
   "keywords": [
     "chatpanel",
     "claude-code",
@@ -36,9 +36,7 @@
     "dev": "node --watch src/server.js",
     "build:bin": "bash scripts/build-binaries.sh"
   },
-  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.1.0"
-  },
+  "dependencies": {},
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"

package/src/engines/claude.js

@@ -1,195 +1,189 @@
-// Claude Code engine — embeds the Claude Agent SDK using your *local* Claude
-// Code login (or ANTHROPIC_API_KEY). It streams text deltas and surfaces tool
-// use so the extension can show what the agent is doing.
+// Claude Code engine — drives the Claude Code CLI (`claude --print`) directly,
+// the SAME way the Codex engine drives `codex exec`. No Agent SDK, no bundled
+// cli.js, no native `sharp` dependency — so it works in any environment that has
+// `claude` on PATH (npm install, native installer, or `npx`), and there's nothing
+// to resolve inside a compiled binary (the old "/$bunfs/root/cli.js" failure).
 //
-// By default the agent can READ your code (Read/Grep/Glob/WebFetch) but cannot
-// write or run shell commands unless the agent's permissionMode is set to
-// 'acceptEdits' or 'bypassPermissions' in ChatPanel Settings. The working
-// directory comes from the agent config (defaults to the bridge's cwd).
+// It uses your *local* Claude Code login. By default the agent can READ your code
+// (Read/Grep/Glob/WebFetch/…) but cannot write or run shell commands unless the
+// agent's permissionMode is 'acceptEdits' or 'bypassPermissions' in ChatPanel
+// Settings. The working directory comes from the agent config.
 
-import path from 'node:path';
+import { spawn } from 'node:child_process';
 import os from 'node:os';
-import { existsSync } from 'node:fs';
-import { findAgentBin, isCompiledBinary } from '../env.js';
-
-let sdkPromise = null;
-function loadSdk() {
-  if (!sdkPromise) sdkPromise = import('@anthropic-ai/claude-agent-sdk').catch(() => null);
-  return sdkPromise;
-}
+import path from 'node:path';
+import { findAgentBin } from '../env.js';
 
-// Where the Claude Code CLI lives. The SDK ships a bundled cli.js, but inside a
-// compiled binary that file is on a virtual FS that child processes can't reach
-// (it fails on Windows as "B:\~BUN\cli.js"). So in a binary we point the SDK at
-// the user's INSTALLED Claude Code instead — preferring the real cli.js next to
-// the npm shim (modern Node won't spawn a .cmd directly).
-function claudeExecutable() {
-  if (process.env.CHATPANEL_CLAUDE_PATH) return process.env.CHATPANEL_CLAUDE_PATH;
-  if (!isCompiledBinary()) return undefined; // under node/bun the bundled cli.js works
-  const bin = findAgentBin('claude');
-  if (!bin) return undefined;
-  const dir = path.dirname(bin);
-  // The npm install ships cli.js; the native installer ships cli-wrapper.cjs
-  // (a JS entry next to a platform binary). Prefer either runnable JS entry over
-  // the native `claude` binary, since the SDK runs it with its own JS runtime.
-  const pkgDirs = [
-    path.join(dir, 'node_modules', '@anthropic-ai', 'claude-code'),
-    path.join(dir, '..', 'lib', 'node_modules', '@anthropic-ai', 'claude-code'),
-    // npm global on macOS/Homebrew symlinks bin/claude → ../lib/node_modules/...,
-    // so dir is already the package's own bin/ in the native install.
-    path.join(dir, '..'),
-  ];
-  for (const p of pkgDirs) {
-    for (const entry of ['cli.js', 'cli-wrapper.cjs']) {
-      const c = path.join(p, entry);
-      if (existsSync(c)) return c;
-    }
-  }
-  return bin;
-}
+const TIMEOUT_MS = Number(process.env.CHATPANEL_CLAUDE_TIMEOUT_MS) || 180_000;
+// Read-only tools allowed without approval in headless mode; writes/shell are
+// gated behind the agent's permission mode.
+const READONLY_TOOLS = ['Read', 'Grep', 'Glob', 'WebFetch', 'WebSearch', 'TodoWrite', 'Task'];
 
+let installed = false;
+let lastProbe = 0;
 export async function available() {
-  const sdk = await loadSdk();
-  if (!sdk) {
-    return { ok: false, reason: 'Agent SDK not installed (npm i in bridge/)' };
-  }
-  // In a compiled binary the bundled CLI is unreachable, so Claude Code must be
-  // installed locally. (Under node/bun the bundled CLI works, so this is skipped.)
-  if (isCompiledBinary() && !process.env.CHATPANEL_CLAUDE_PATH && !findAgentBin('claude')) {
-    return {
-      ok: false,
-      reason: 'Claude Code not found. Install it (npm i -g @anthropic-ai/claude-code), or run the bridge with `npx @chatpanel/bridge`.',
-    };
+  // Availability = "is claude findable on PATH" (mirrors the codex engine), NOT
+  // "does `claude --version` exit 0" (which fails when it just needs login).
+  if (!installed && Date.now() - lastProbe > 4000) {
+    lastProbe = Date.now();
+    try {
+      installed = !!findAgentBin('claude');
+    } catch {
+      installed = false;
+    }
   }
-  return { ok: true };
+  return installed
+    ? { ok: true }
+    : { ok: false, reason: 'Claude Code not found on PATH. Install it (npm i -g @anthropic-ai/claude-code) and run `claude` once to log in.' };
 }
 
-const READONLY_TOOLS = new Set(['Read', 'Grep', 'Glob', 'WebFetch', 'WebSearch', 'TodoWrite', 'Task']);
-
-// Build a single prompt that carries the conversation history. The bridge is
-// stateless, so we replay the chat each turn.
+// The bridge is stateless, so we replay the conversation as a single prompt.
 function buildPrompt(messages) {
   const history = messages.slice(0, -1);
   const last = messages[messages.length - 1];
   let prompt = '';
   if (history.length) {
     prompt += 'Conversation so far:\n';
-    for (const m of history) {
-      prompt += `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}\n\n`;
-    }
+    for (const m of history) prompt += `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}\n\n`;
     prompt += '---\n\n';
   }
   prompt += last ? last.content : '';
   return prompt;
 }
 
-export async function chat({ messages, system, options }, emit) {
-  const sdk = await loadSdk();
-  if (!sdk) throw new Error('Claude Agent SDK not installed. Run `npm install` in bridge/.');
-  const { query } = sdk;
+// Spawn `claude` and stream its stream-json output, forwarding events via `emit`.
+// `extraArgs` lets complete() run a tool-free single shot. Resolves with the final
+// result text once the process closes 0.
+function runClaude({ prompt, args, cwd, emit }) {
+  const bin = findAgentBin('claude') || 'claude';
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(bin, args, { cwd, stdio: ['pipe', 'pipe', 'pipe'], env: process.env });
+    } catch (e) {
+      return reject(new Error(`Failed to start claude: ${e.message}`));
+    }
 
-  const permissionMode = options.permissionMode || 'default';
-  // No project configured → a neutral cwd, so the agent doesn't fixate on
-  // whatever directory the bridge happens to be running in.
-  const cwd = options.workingDir ? path.resolve(options.workingDir) : os.homedir();
-  const writesAllowed = permissionMode === 'acceptEdits' || permissionMode === 'bypassPermissions';
-
-  // Approve read-only tools always; gate writes/shell behind the chosen mode.
-  const canUseTool = async (toolName) => {
-    if (READONLY_TOOLS.has(toolName) || writesAllowed) return { behavior: 'allow', updatedInput: undefined };
-    return { behavior: 'deny', message: `${toolName} blocked — set this agent's permission mode to acceptEdits/bypassPermissions in ChatPanel to enable it.` };
-  };
-
-  let streamedAny = false;
-  let resultText = '';
-
-  const iterator = query({
-    prompt: buildPrompt(messages),
-    options: {
-      cwd,
-      permissionMode,
-      includePartialMessages: true,
-      canUseTool,
-      // Default: load your ~/.claude + project settings so your skills, MCP
-      // servers and CLAUDE.md apply. Turn the agent's "Use my local skills &
-      // config" off to run clean.
-      settingSources: options.useLocalConfig === false ? [] : ['user', 'project'],
-      // Native Claude Code system prompt. Only append the user's OWN system
-      // prompt if they set one — no ChatPanel persona is injected, so the agent
-      // is exactly as capable as it is in the terminal.
-      systemPrompt: system
-        ? { type: 'preset', preset: 'claude_code', append: system }
-        : { type: 'preset', preset: 'claude_code' },
-      ...(options.model ? { model: options.model } : {}),
-      ...(claudeExecutable() ? { pathToClaudeCodeExecutable: claudeExecutable() } : {}),
-      ...(process.env.CHATPANEL_MAX_TURNS ? { maxTurns: Number(process.env.CHATPANEL_MAX_TURNS) } : {}),
-    },
-  });
+    let stdout = '';
+    let stderr = '';
+    let streamedAny = false;
+    let resultText = '';
+
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      reject(new Error(`Claude Code timed out after ${Math.round(TIMEOUT_MS / 1000)}s.`));
+    }, TIMEOUT_MS);
 
-  for await (const message of iterator) {
-    if (message.type === 'stream_event') {
-      const ev = message.event;
-      if (ev?.type === 'content_block_delta') {
-        if (ev.delta?.type === 'text_delta') {
-          streamedAny = true;
-          emit({ type: 'delta', text: ev.delta.text });
-        } else if (ev.delta?.type === 'thinking_delta') {
-          // Extended thinking — stream the reasoning text to the panel.
-          emit({ type: 'reasoning', text: ev.delta.thinking || '' });
+    child.stdout.on('data', (d) => {
+      stdout += d.toString();
+      let nl;
+      while ((nl = stdout.indexOf('\n')) >= 0) {
+        const line = stdout.slice(0, nl).trim();
+        stdout = stdout.slice(nl + 1);
+        if (!line.startsWith('{')) continue;
+        let msg;
+        try {
+          msg = JSON.parse(line);
+        } catch {
+          continue; // not a JSON event line
         }
+        const r = handleMessage(msg, emit, streamedAny);
+        if (r.streamed) streamedAny = true;
+        if (r.result != null) resultText = r.result;
       }
-    } else if (message.type === 'assistant') {
-      for (const block of message.message.content) {
-        if (block.type === 'tool_use') {
-          emit({ type: 'tool', name: block.name, summary: toolSummary(block) });
-        } else if (block.type === 'text' && !streamedAny) {
-          // Partials were unavailable — stream the whole block.
-          streamedAny = true;
-          emit({ type: 'delta', text: block.text });
-        }
+    });
+    child.stderr.on('data', (d) => (stderr += d.toString()));
+    child.on('error', (e) => {
+      clearTimeout(timer);
+      reject(e);
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve({ streamedAny, resultText });
+      else reject(new Error(`Claude Code exited ${code}: ${stderr.trim().split('\n').pop() || 'failed'}`));
+    });
+
+    child.stdin.write(prompt);
+    child.stdin.end();
+  });
+}
+
+// Map one stream-json message to emit() calls. Returns { streamed, result }.
+// The CLI's stream-json mirrors the SDK message shapes.
+function handleMessage(msg, emit, alreadyStreamed) {
+  const out = { streamed: false, result: null };
+  if (msg.type === 'stream_event') {
+    const ev = msg.event;
+    if (ev?.type === 'content_block_delta') {
+      if (ev.delta?.type === 'text_delta') {
+        out.streamed = true;
+        emit({ type: 'delta', text: ev.delta.text });
+      } else if (ev.delta?.type === 'thinking_delta') {
+        emit({ type: 'reasoning', text: ev.delta.thinking || '' });
       }
-    } else if (message.type === 'result') {
-      if (message.subtype === 'success') resultText = message.result || '';
-      else if (message.subtype !== 'success') {
-        emit({ type: 'status', text: `(${message.subtype})` });
+    }
+  } else if (msg.type === 'assistant') {
+    for (const block of msg.message?.content || []) {
+      if (block.type === 'tool_use') {
+        emit({ type: 'tool', name: block.name, summary: toolSummary(block) });
+      } else if (block.type === 'text' && !alreadyStreamed) {
+        out.streamed = true;
+        emit({ type: 'delta', text: block.text });
       }
     }
+  } else if (msg.type === 'result') {
+    if (msg.subtype === 'success') out.result = msg.result || '';
+    else emit({ type: 'status', text: `(${msg.subtype})` });
   }
+  return out;
+}
+
+export async function chat({ messages, system, options }, emit) {
+  const permissionMode = options.permissionMode || 'default';
+  const cwd = options.workingDir ? path.resolve(options.workingDir) : os.homedir();
+
+  const args = ['--print', '--output-format', 'stream-json', '--include-partial-messages', '--verbose'];
+
+  // Gate writes/shell behind the chosen mode; otherwise restrict to read-only
+  // tools so headless runs never block on an approval prompt.
+  if (permissionMode === 'bypassPermissions') args.push('--permission-mode', 'bypassPermissions');
+  else if (permissionMode === 'acceptEdits') args.push('--permission-mode', 'acceptEdits');
+  else args.push('--allowedTools', ...READONLY_TOOLS);
+
+  // Native Claude Code behavior; append the user's own system prompt if they set
+  // one (no ChatPanel persona injected).
+  if (system) args.push('--append-system-prompt', system);
+  if (options.model) args.push('--model', options.model);
+  // Default loads your ~/.claude + project settings (skills, MCP, CLAUDE.md).
+  // "Use my local skills & config" off → run clean.
+  if (options.useLocalConfig === false) args.push('--setting-sources', '');
 
+  const { streamedAny, resultText } = await runClaude({ prompt: buildPrompt(messages), args, cwd, emit });
   emit({ type: 'done', text: streamedAny ? '' : resultText });
 }
 
 // A fast, tool-free single-shot completion — used for prompt autocomplete. No
-// claude_code preset, no tools, no local config: just a quick text continuation
-// from a fast model (Haiku by default). Returns the completion string.
+// tools, no local config: just a quick text continuation from a fast model.
 export async function complete({ prompt, system, model }) {
-  const sdk = await loadSdk();
-  if (!sdk) throw new Error('Claude Agent SDK not installed.');
-  const { query } = sdk;
+  const args = [
+    '--print',
+    '--output-format', 'stream-json',
+    '--verbose',
+    '--disallowedTools', 'Read', 'Grep', 'Glob', 'WebFetch', 'WebSearch', 'Bash', 'Edit', 'Write', 'Task', 'TodoWrite',
+    '--setting-sources', '',
+    '--model', model || 'haiku',
+    '--system-prompt', system || "Continue the user's text briefly. Reply with only the continuation.",
+  ];
   let text = '';
-  const iterator = query({
+  const { resultText } = await runClaude({
     prompt,
-    options: {
-      cwd: os.homedir(),
-      permissionMode: 'default',
-      allowedTools: [], // no tools — pure text completion
-      maxTurns: 1,
-      settingSources: [], // skip CLAUDE.md / MCP for a tiny completion
-      systemPrompt: system || "Continue the user's text briefly. Reply with only the continuation.",
-      model: model || 'haiku',
-      ...(claudeExecutable() ? { pathToClaudeCodeExecutable: claudeExecutable() } : {}),
+    args,
+    cwd: os.homedir(),
+    emit: (e) => {
+      if (e.type === 'delta') text += e.text;
     },
   });
-  for await (const message of iterator) {
-    if (message.type === 'assistant') {
-      for (const block of message.message.content) {
-        if (block.type === 'text') text += block.text;
-      }
-    } else if (message.type === 'result' && message.subtype === 'success' && !text) {
-      text = message.result || '';
-    }
-  }
-  return text.trim();
+  return (text || resultText || '').trim();
 }
 
 function toolSummary(block) {

package/src/server.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 // ChatPanel Bridge — a tiny localhost server that exposes the coding agents
-// running on this machine (Claude Code via the Agent SDK, Codex and Gemini via
-// their CLIs) to the ChatPanel Chrome extension. Zero runtime dependencies
-// beyond the optional Claude Agent SDK.
+// running on this machine (Claude Code, Codex and Gemini, each via its CLI) to
+// the ChatPanel Chrome extension. Zero runtime dependencies.
 //
-//   GET  /health  → { ok, version, agents: [{id,label,available,reason}] }
+//   GET  /health  → { ok, version, agents: [...], update: {current,latest,…} }
+//   POST /update  → self-update to the latest release (compiled binary installs)
 //   POST /chat    → Server-Sent Events stream of { type, ... }:
 //                     {type:'delta', text}    incremental assistant text
 //                     {type:'tool',  name, summary}
@@ -19,10 +19,11 @@ import os from 'node:os';
 import * as claude from './engines/claude.js';
 import * as codex from './engines/codex.js';
 import * as gemini from './engines/gemini.js';
-import { installService, uninstallService, serviceStatus } from './service.js';
+import { installService, uninstallService, serviceStatus, restartService } from './service.js';
 import { enrichPath, findAgentBin } from './env.js';
+import { checkForUpdate, selfUpdate } from './update.js';
 
-const VERSION = '0.2.10';
+const VERSION = '0.2.13';
 const HOST = process.env.CHATPANEL_BRIDGE_HOST || '127.0.0.1';
 const PORT = Number(process.env.CHATPANEL_BRIDGE_PORT) || 4319;
 
@@ -81,7 +82,20 @@ async function handleHealth(res) {
       return { id, label, available: a.ok, reason: a.reason };
     }),
   );
-  json(res, 200, { ok: true, version: VERSION, agents });
+  const update = await checkForUpdate(VERSION).catch(() => ({ current: VERSION, updateAvailable: false }));
+  json(res, 200, { ok: true, version: VERSION, agents, update });
+}
+
+// POST /update — self-update (compiled-binary installs). Swaps the binary, replies,
+// then restarts the service into the new version. npm installs get instructions.
+async function handleUpdate(res) {
+  try {
+    const result = await selfUpdate(VERSION); // throws on npm install / no update / failure
+    json(res, 200, { ok: true, updated: true, from: result.from, to: result.to });
+    res.on('finish', () => setTimeout(() => restartService(), 400));
+  } catch (e) {
+    json(res, 400, { ok: false, error: String(e?.message || e) });
+  }
 }
 
 async function handleChat(req, res) {
@@ -187,6 +201,7 @@ const server = createServer(async (req, res) => {
     }
     if (req.method === 'POST' && url.pathname === '/chat') return handleChat(req, res);
     if (req.method === 'POST' && url.pathname === '/complete') return handleComplete(req, res);
+    if (req.method === 'POST' && url.pathname === '/update') return handleUpdate(res);
     json(res, 404, { error: 'Not found' });
   } catch (e) {
     json(res, 500, { error: e?.message || String(e) });
@@ -218,6 +233,7 @@ Usage:
   chatpanel-bridge --install    run automatically at login, in the background
   chatpanel-bridge --uninstall  remove the login auto-start
   chatpanel-bridge --status     show whether auto-start is set up
+  chatpanel-bridge --update     download & install the latest version, then restart
   chatpanel-bridge --version    print the version
 
 Env: CHATPANEL_BRIDGE_HOST, CHATPANEL_BRIDGE_PORT`);
@@ -269,4 +285,17 @@ function runCli() {
   return false;
 }
 
-if (!runCli()) startServer();
+if (process.argv.includes('--update')) {
+  (async () => {
+    try {
+      const r = await selfUpdate(VERSION);
+      log('info', `Updated v${r.from} → v${r.to}. Restarting the background service…`);
+      restartService();
+    } catch (e) {
+      log('error', 'Update failed: ' + (e?.message || e));
+      process.exitCode = 1;
+    }
+  })();
+} else if (!runCli()) {
+  startServer();
+}

package/src/service.js

@@ -12,7 +12,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 
 const LABEL = 'net.chatpanel.bridge';
 const DISPLAY = 'ChatPanel Bridge';
@@ -157,3 +157,37 @@ export function uninstallService() {
 export function serviceStatus() {
   return byPlatform(macStatus, winStatus, linStatus);
 }
+
+// Restart the installed service into a freshly-swapped binary (used by self-
+// update). Detached so it survives the restart killing the caller — works whether
+// invoked from inside the service (POST /update) or a CLI `--update`.
+//   • macOS  — `launchctl kickstart -k` kills + relaunches the LaunchAgent.
+//   • Linux  — `systemctl --user restart`.
+//   • Windows — kill the running bridge, wait ~2s (port frees), relaunch via the
+//               hidden VBS, then delete the renamed old-*.exe.
+export function restartService() {
+  try {
+    if (process.platform === 'darwin') {
+      const uid = typeof process.getuid === 'function' ? process.getuid() : 0;
+      spawn('launchctl', ['kickstart', '-k', `gui/${uid}/${LABEL}`], { detached: true, stdio: 'ignore' }).unref();
+      return true;
+    }
+    if (process.platform === 'linux') {
+      spawn('systemctl', ['--user', 'restart', 'chatpanel-bridge'], { detached: true, stdio: 'ignore' }).unref();
+      return true;
+    }
+    if (process.platform === 'win32') {
+      const vbs = winVbs();
+      const dir = path.dirname(process.execPath);
+      const cmd =
+        `taskkill /IM chatpanel-bridge.exe /F >nul 2>&1 & ` +
+        `timeout /t 2 >nul & wscript.exe "${vbs}" & ` +
+        `del /q "${path.join(dir, 'chatpanel-bridge.old-*.exe')}" >nul 2>&1`;
+      spawn('cmd', ['/c', cmd], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+      return true;
+    }
+  } catch {
+    /* fall through */
+  }
+  return false;
+}

package/src/update.js

@@ -0,0 +1,154 @@
+// In-app updater for the standalone binary.
+//
+// The bridge is a background service the user never opens, so the EXTENSION
+// surfaces "update available" (from /health) and offers a one-click Update that
+// calls POST /update. The bridge downloads the new binary, swaps it in, and the
+// service relaunches into the new version.
+//
+// Cross-platform swap + relaunch (users come from anywhere):
+//   • macOS  — atomic rename over the running file; KeepAlive relaunches on exit.
+//   • Linux  — atomic rename; `systemctl --user restart` relaunches.
+//   • Windows — can't overwrite a running .exe, so we RENAME the running exe aside
+//               and drop the new one in its place, then a detached helper waits for
+//               this process to exit (freeing the port) and relaunches it.
+//
+// No-ops for npx/node installs — npm owns those; only compiled binaries self-update.
+
+import os from 'node:os';
+import path from 'node:path';
+import { chmod, rename, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { isCompiledBinary } from './env.js';
+
+const REPO = 'chatpanel/chatpanel-bridge';
+const LATEST_API = `https://api.github.com/repos/${REPO}/releases/latest`;
+const CHECK_EVERY_MS = 6 * 60 * 60 * 1000; // 6h
+const CACHE = path.join(os.homedir(), '.chatpanel', 'update-check.json');
+const UA = { 'User-Agent': 'chatpanel-bridge-updater' };
+
+// Release asset name for THIS platform (matches release-binaries.yml outputs).
+// macOS publishes arm64 only; Intel Macs use `npx` (managed → no self-update).
+function assetName() {
+  if (process.platform === 'darwin') return process.arch === 'arm64' ? 'chatpanel-bridge-macos-arm64' : null;
+  if (process.platform === 'linux') return 'chatpanel-bridge-linux-x64';
+  if (process.platform === 'win32') return 'chatpanel-bridge-windows-x64.exe';
+  return null;
+}
+
+function parseVersion(s = '') {
+  const m = /(\d+(?:\.\d+){0,3})/.exec(s || '');
+  return m ? m[1] : null;
+}
+// >0 if a is newer than b.
+function cmp(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+async function readCache() {
+  try {
+    return JSON.parse(await readFile(CACHE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+async function writeCache(obj) {
+  try {
+    await mkdir(path.dirname(CACHE), { recursive: true });
+    await writeFile(CACHE, JSON.stringify(obj));
+  } catch {
+    /* best effort */
+  }
+}
+
+// Returns { current, latest, updateAvailable, mode, canSelfUpdate, assetUrl, npmCommand }.
+//   mode 'binary' → compiled standalone build (macOS/Linux curl install, or the
+//                   optional Windows .exe). POST /update self-replaces in place.
+//   mode 'npm'    → npx/node install (the default on Windows). The bridge can't
+//                   swap its own files; the extension shows `npmCommand` instead.
+// Both report updateAvailable so the user always gets the notice — only the action
+// differs. Throttled to CHECK_EVERY_MS unless `force`.
+export async function checkForUpdate(current, { force = false } = {}) {
+  const mode = isCompiledBinary() ? 'binary' : 'npm';
+  const want = assetName();
+
+  let latest = null;
+  let assetUrl = null;
+  const cache = await readCache();
+  if (!force && cache && Date.now() - cache.checkedAt < CHECK_EVERY_MS) {
+    latest = cache.latest;
+    assetUrl = cache.assetUrl;
+  } else {
+    try {
+      const res = await fetch(LATEST_API, { headers: { Accept: 'application/vnd.github+json', ...UA } });
+      if (res.ok) {
+        const data = await res.json();
+        latest = parseVersion(data.tag_name) || parseVersion(data.name);
+        assetUrl = want ? (data.assets || []).find((a) => a.name === want)?.browser_download_url || null : null;
+        await writeCache({ checkedAt: Date.now(), latest, assetUrl });
+      } else {
+        latest = cache?.latest || null;
+        assetUrl = cache?.assetUrl || null;
+      }
+    } catch {
+      latest = cache?.latest || null;
+      assetUrl = cache?.assetUrl || null;
+    }
+  }
+  const updateAvailable = !!latest && cmp(latest, current) > 0;
+  // One-click in-place update is only possible for a compiled binary with a
+  // matching release asset; npm installs update via the command.
+  const canSelfUpdate = mode === 'binary' && !!assetUrl;
+  return {
+    current,
+    latest,
+    updateAvailable,
+    mode,
+    canSelfUpdate,
+    assetUrl,
+    npmCommand: mode === 'npm' ? 'npm i -g @chatpanel/bridge@latest' : null,
+  };
+}
+
+// Download the latest binary and swap it in. Does NOT restart — the caller sends
+// its HTTP response first, then triggers restartService(). Throws on any failure,
+// leaving the running binary untouched.
+export async function selfUpdate(current) {
+  if (!isCompiledBinary()) {
+    throw new Error('Self-update applies only to the standalone binary. Update the npm/npx version with npm.');
+  }
+  const info = await checkForUpdate(current, { force: true });
+  if (!info.assetUrl) throw new Error('No downloadable build for this platform — use `npx @chatpanel/bridge`.');
+  if (!info.updateAvailable) {
+    throw new Error(info.latest ? `Already on the latest version (v${current}).` : 'Could not reach the update server.');
+  }
+
+  const target = process.execPath; // the running binary's own path
+  const dir = path.dirname(target);
+  const tmp = path.join(dir, `.chatpanel-bridge.new-${Date.now()}`);
+
+  const res = await fetch(info.assetUrl, { headers: UA });
+  if (!res.ok || !res.body) throw new Error(`Download failed (${res.status}).`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  if (buf.length < 1_000_000) throw new Error('Downloaded file looks too small — aborting to avoid a broken bridge.');
+
+  await writeFile(tmp, buf);
+  if (process.platform !== 'win32') await chmod(tmp, 0o755);
+
+  if (process.platform === 'win32') {
+    // A running .exe can't be overwritten, but it CAN be renamed. Move it aside,
+    // drop the new one in place; the old (renamed) file is cleaned up after exit.
+    const aside = path.join(dir, `chatpanel-bridge.old-${Date.now()}.exe`);
+    await rename(target, aside);
+    await rename(tmp, target);
+  } else {
+    // POSIX: atomic rename over the running file. The live process keeps the old
+    // inode; the path now points at the new binary.
+    await rename(tmp, target);
+  }
+  return { ok: true, from: current, to: info.latest };
+}