@chatpanel/bridge 0.2.16 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/bridge",
-  "version": "0.2.16",
+  "version": "0.3.0",
   "type": "module",
   "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": [

package/src/engines/claude.js

@@ -16,7 +16,7 @@
 import { spawn } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
-import { resolveClaude, toWslPath, isCompiledBinary } from '../env.js';
+import { resolveClaude, buildSpawnSpec, isCompiledBinary } from '../env.js';
 
 const TIMEOUT_MS = Number(process.env.CHATPANEL_CLAUDE_TIMEOUT_MS) || 180_000;
 // Read-only tools allowed without approval in headless mode; writes/shell are
@@ -65,46 +65,13 @@ function buildPrompt(messages) {
   return prompt;
 }
 
-// Turn a launch spec + the claude CLI args into a concrete [bin, argv, options]
-// for spawn(). `cwd` is the resolved working dir (Windows path on win32), or null
-// to use the home directory.
-function buildSpawn(spec, args, cwd) {
-  if (spec.kind === 'wsl') {
-    // Run claude inside WSL's login shell so nvm/etc. PATH resolves it. The
-    // `'exec claude "$@"'` + 'chatpanel' ($0) trick passes our args through as a
-    // proper argv array — no manual quoting, even for multi-line system prompts.
-    const pre = [];
-    if (cwd) {
-      const wslCwd = toWslPath(cwd);
-      if (wslCwd) pre.push('--cd', wslCwd); // else: run in WSL home
-    }
-    const argv = [...pre, '-e', 'bash', '-lic', 'exec claude "$@"', 'chatpanel', ...args];
-    return ['wsl.exe', argv, { stdio: ['pipe', 'pipe', 'pipe'], env: process.env, windowsHide: true }];
-  }
-
-  const spawnCwd = cwd || os.homedir();
-  const opts = { cwd: spawnCwd, stdio: ['pipe', 'pipe', 'pipe'], env: process.env, windowsHide: true };
-  if (spec.kind === 'script') {
-    // Run cli.js with the interpreter already running the bridge (node/bun).
-    return [process.execPath, [spec.script, ...args], opts];
-  }
-  if (spec.kind === 'cmd') {
-    // Launch the .cmd/.bat shim via cmd.exe with a real argv (shell:false). Node
-    // applies cmd.exe-aware quoting here, so args are passed safely — unlike
-    // spawn(..., { shell: true }), which concatenates (DEP0190).
-    return ['cmd.exe', ['/d', '/s', '/c', spec.bin, ...args], opts];
-  }
-  // kind === 'native' — a directly executable file (mac/linux binary or .exe).
-  return [spec.bin, args, opts];
-}
-
 // Spawn claude (however it resolves) and stream its stream-json output via
 // `emit`. Resolves with { streamedAny, resultText } once it closes 0. Returns
 // null (no spawn) when claude can't be resolved, so the caller can fall back.
 function runClaude({ prompt, args, cwd, emit }) {
   const spec = resolveClaude();
   if (!spec) return null;
-  const [bin, argv, opts] = buildSpawn(spec, args, cwd);
+  const [bin, argv, opts] = buildSpawnSpec(spec, args, cwd);
 
   return new Promise((resolve, reject) => {
     let child;
@@ -159,8 +126,9 @@ function runClaude({ prompt, args, cwd, emit }) {
 }
 
 // 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) {
+// The CLI's stream-json mirrors the SDK message shapes. Exported so the custom
+// engine can reuse it for agents that emit Claude-style stream-json.
+export function handleMessage(msg, emit, alreadyStreamed) {
   const out = { streamed: false, result: null };
   if (msg.type === 'stream_event') {
     const ev = msg.event;

package/src/engines/custom.js

@@ -0,0 +1,148 @@
+// Custom ("bring your own") engine — runs ANY CLI the user onboards from the
+// extension's Agents settings (opencode, pi, ollama, a shell script, …) WITHOUT
+// a bridge code change per tool. The command spec travels in the chat request's
+// `options.custom`; this engine resolves the command cross-platform (PATH /
+// Windows cli.js+.cmd / WSL — same launcher as Claude), pipes the prompt in, and
+// streams output back.
+//
+// HARD Pro gate: a custom agent only runs if the request carries a valid,
+// server-signed entitlement token (verified OFFLINE here — no network). A forked
+// client or a raw POST can't forge it, so this is real gating, not UI.
+//
+// Output formats:
+//   'text' (default) — stream stdout straight through as text deltas. Works for
+//                      any program that prints a reply.
+//   'claude-stream-json' — parse Claude Code-style stream-json (for tools that
+//                      speak it), reusing the Claude engine's parser.
+
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { resolveCommand, buildSpawnSpec } from '../env.js';
+import { isProEntitled } from '../entitlement.js';
+import { handleMessage } from './claude.js';
+
+const TIMEOUT_MS = Number(process.env.CHATPANEL_CUSTOM_TIMEOUT_MS) || 180_000;
+
+export async function available() {
+  // The engine ships in every bridge; individual custom agents are user-defined
+  // (Pro) and validated per request and via /agent-check.
+  return { ok: true };
+}
+
+// The bridge is stateless, so replay the conversation as a single prompt.
+function buildPrompt(messages, system) {
+  let p = system ? `${system}\n\n` : '';
+  const history = messages.slice(0, -1);
+  const last = messages[messages.length - 1];
+  if (history.length) {
+    p += 'Conversation so far:\n';
+    for (const m of history) p += `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}\n\n`;
+    p += '---\n\n';
+  }
+  p += last ? last.content : '';
+  return p;
+}
+
+export async function chat({ messages, system, options }, emit) {
+  // Pro gate — verified, not just UI. No valid signed entitlement → no run.
+  if (!(await isProEntitled(options.entitlement))) {
+    throw new Error('Custom agents require ChatPanel Pro. Upgrade in Settings to bring your own CLI agent.');
+  }
+
+  const spec = options.custom || {};
+  if (!spec.command) throw new Error('This custom agent has no command configured.');
+
+  const resolved = resolveCommand(spec.command);
+  if (!resolved) {
+    throw new Error(`Couldn't find "${spec.command}". Enter its full path, or install it on your PATH (or in WSL).`);
+  }
+
+  const prompt = buildPrompt(messages, system);
+  const cwd = options.workingDir ? path.resolve(options.workingDir) : null;
+  const label = spec.label || spec.command;
+  const fmt = spec.format === 'claude-stream-json' ? 'claude-stream-json' : 'text';
+
+  // Args: either a real array or a space-split string. With promptVia:'arg' we
+  // substitute {prompt} (or append it if there's no placeholder); otherwise the
+  // prompt goes in on stdin.
+  const promptVia = spec.promptVia === 'arg' ? 'arg' : 'stdin';
+  let args = Array.isArray(spec.args)
+    ? spec.args.slice()
+    : spec.args
+      ? String(spec.args).split(/\s+/).filter(Boolean)
+      : [];
+  if (promptVia === 'arg') {
+    let placed = false;
+    args = args.map((a) => {
+      if (a.includes('{prompt}')) {
+        placed = true;
+        return a.replaceAll('{prompt}', prompt);
+      }
+      return a;
+    });
+    if (!placed) args.push(prompt);
+  }
+
+  const [bin, argv, opts] = buildSpawnSpec(resolved, args, cwd);
+
+  await new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(bin, argv, opts);
+    } catch (e) {
+      return reject(new Error(`Failed to start ${label}: ${e.message}`));
+    }
+
+    let stderr = '';
+    let streamedAny = false;
+    let resultText = '';
+    let jsonBuf = '';
+
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      reject(new Error(`${label} timed out after ${Math.round(TIMEOUT_MS / 1000)}s.`));
+    }, TIMEOUT_MS);
+
+    child.stdout.on('data', (d) => {
+      const s = d.toString();
+      if (fmt === 'claude-stream-json') {
+        jsonBuf += s;
+        let nl;
+        while ((nl = jsonBuf.indexOf('\n')) >= 0) {
+          const line = jsonBuf.slice(0, nl).trim();
+          jsonBuf = jsonBuf.slice(nl + 1);
+          if (!line.startsWith('{')) continue;
+          let msg;
+          try {
+            msg = JSON.parse(line);
+          } catch {
+            continue;
+          }
+          const r = handleMessage(msg, emit, streamedAny);
+          if (r.streamed) streamedAny = true;
+          if (r.result != null) resultText = r.result;
+        }
+      } else {
+        streamedAny = true;
+        emit({ type: 'delta', text: s });
+      }
+    });
+    child.stderr.on('data', (d) => (stderr += d.toString()));
+    child.on('error', (e) => {
+      clearTimeout(timer);
+      reject(new Error(`Failed to start ${label}: ${e.message}`));
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (code === 0) {
+        emit({ type: 'done', text: streamedAny ? '' : resultText });
+        resolve();
+      } else {
+        reject(new Error(`${label} exited ${code}: ${stderr.trim().split('\n').pop() || 'failed'}`));
+      }
+    });
+
+    if (promptVia === 'stdin') child.stdin.write(prompt);
+    child.stdin.end();
+  });
+}

package/src/entitlement.js

@@ -0,0 +1,81 @@
+// Offline Pro/Team entitlement verification — the HARD gate for paid features
+// (e.g. custom "bring your own CLI" agents).
+//
+// The license server (Cloudflare Worker) signs a compact entitlement token with
+// an ECDSA P-256 private key that lives ONLY there. The bridge ships the matching
+// PUBLIC key and verifies the signature locally — no network, no secret. A forked
+// client or a raw `curl` to the bridge can't forge entitlement without the
+// private key, so this is a real cryptographic gate, not a UI check.
+//
+// Token format (identical to the extension's, extension/js/license.js):
+//   token   = base64url(JSON payload) + "." + base64url(raw ECDSA signature)
+//   signed over UTF-8(head); payload = { typ:'ent', plan, install_id, sub, exp }
+//
+// Keep ENTITLEMENT_PUBLIC_JWK in sync with the extension's copy.
+
+import { webcrypto } from 'node:crypto';
+
+const ENTITLEMENT_PUBLIC_JWK = {
+  kty: 'EC',
+  crv: 'P-256',
+  x: 'CmgKLC4e3xDMvwhbjVqF7jbDe1JhC1KKQi8JN3qVX_4',
+  y: 'r40l6fQiyCcJYqW-SvB4VoSyn4F36yhSt82ZAOSo78E',
+};
+
+const PRO_PLANS = new Set(['pro', 'team']);
+
+const b64urlToBytes = (s) => {
+  const norm = s.replace(/-/g, '+').replace(/_/g, '/');
+  return new Uint8Array(Buffer.from(norm, 'base64'));
+};
+
+let keyPromise = null;
+function publicKey() {
+  if (!keyPromise) {
+    keyPromise = webcrypto.subtle.importKey(
+      'jwk',
+      ENTITLEMENT_PUBLIC_JWK,
+      { name: 'ECDSA', namedCurve: 'P-256' },
+      false,
+      ['verify'],
+    );
+  }
+  return keyPromise;
+}
+
+// Verify a server entitlement token. Returns its payload, or null. Checks the
+// ECDSA signature (unforgeable without the private key), the token type, and
+// expiry. install_id binding is the extension's concern — for the bridge gate the
+// signature is what matters.
+export async function verifyEntitlement(token) {
+  if (!token || typeof token !== 'string' || token.indexOf('.') < 0) return null;
+  const [head, sig] = token.split('.');
+  const enc = new TextEncoder();
+  let ok = false;
+  try {
+    ok = await webcrypto.subtle.verify(
+      { name: 'ECDSA', hash: 'SHA-256' },
+      await publicKey(),
+      b64urlToBytes(sig),
+      enc.encode(head),
+    );
+  } catch {
+    return null;
+  }
+  if (!ok) return null;
+  let payload;
+  try {
+    payload = JSON.parse(new TextDecoder().decode(b64urlToBytes(head)));
+  } catch {
+    return null;
+  }
+  if (payload.typ !== 'ent') return null;
+  if (payload.exp && Date.now() > payload.exp) return null;
+  return payload;
+}
+
+// True when `token` is a valid, unexpired Pro (or Team) entitlement.
+export async function isProEntitled(token) {
+  const p = await verifyEntitlement(token);
+  return !!(p && PRO_PLANS.has(p.plan));
+}

package/src/env.js

@@ -91,52 +91,74 @@ function shellWhich(name) {
 // than escapes (Node DEP0190 / a real injection surface). The 'script' and 'cmd'
 // kinds run the shim safely with a proper argv instead.
 export function resolveClaude() {
-  const override = process.env.CHATPANEL_CLAUDE_PATH;
-  if (override) {
-    const ext = path.extname(override).toLowerCase();
-    if (!isCompiledBinary() && /^\.(c?js|mjs)$/.test(ext)) return { kind: 'script', script: override };
-    if (process.platform === 'win32' && (ext === '.cmd' || ext === '.bat')) return { kind: 'cmd', bin: override };
-    return { kind: 'native', bin: override };
+  if (process.env.CHATPANEL_CLAUDE_PATH) return resolveCommand(process.env.CHATPANEL_CLAUDE_PATH);
+  // The Claude npm package additionally ships a cli.js we prefer; otherwise this
+  // is the same generic resolution every command uses.
+  return resolveCommand('claude');
+}
+
+// Resolve ANY command (a bare name like `opencode`, or an absolute/relative path)
+// to a launch spec, the same way resolveClaude does — so custom user-onboarded
+// agents get identical cross-platform launching (PATH, Windows cli.js/.cmd, WSL).
+//
+// Returns one of:
+//   { kind: 'native', bin }              → spawn(bin, args)
+//   { kind: 'script', script }           → spawn(process.execPath, [script, ...args])
+//   { kind: 'cmd', bin }                 → spawn('cmd.exe', ['/c', bin, ...args])
+//   { kind: 'wsl', command }             → spawn('wsl.exe', [prefix, command, ...args])
+//   null                                 → not found
+//
+// We never use spawn's `shell: true` — with an args array it concatenates rather
+// than escapes (Node DEP0190 / a real injection surface). The 'script'/'cmd'/'wsl'
+// kinds run things safely with a proper argv instead.
+export function resolveCommand(command) {
+  if (!command) return null;
+  const looksLikePath = command.includes('/') || command.includes('\\') || /\.[a-z0-9]+$/i.test(command);
+
+  if (looksLikePath) {
+    if (!existsSync(command)) return null; // an explicit path: don't PATH-search
+    const ext = path.extname(command).toLowerCase();
+    if (!isCompiledBinary() && /^\.(c?js|mjs)$/.test(ext)) return { kind: 'script', script: command };
+    if (process.platform === 'win32' && (ext === '.cmd' || ext === '.bat')) return { kind: 'cmd', bin: command };
+    return { kind: 'native', bin: command };
   }
 
   if (process.platform === 'win32') {
-    const win = findClaudeWindows();
+    const win = findCommandWindows(command);
     if (win) return win;
-    if (claudeInWsl()) return { kind: 'wsl' };
+    // Common: tool only installed inside WSL. Only probe safe, simple names.
+    if (/^[\w.-]+$/.test(command) && commandInWsl(command)) return { kind: 'wsl', command };
     return null;
   }
 
-  // macOS / Linux / WSL-native: same resolution the engine used before.
-  const bin = findAgentBin('claude');
+  const bin = findAgentBin(command);
   return bin ? { kind: 'native', bin } : null;
 }
 
-// Locate a runnable Claude Code on Windows. Prefer the package's cli.js (run
-// with our own Node/Bun — clean arg passing, no cmd.exe quoting), then a real
-// .exe, then a .cmd/.bat shim launched safely via cmd.exe.
-function findClaudeWindows() {
+// Locate a runnable command on Windows. Prefer a runnable JS entry (run with our
+// own Node/Bun — clean arg passing, no cmd.exe quoting), then a real .exe, then a
+// .cmd/.bat shim launched safely via cmd.exe.
+function findCommandWindows(name) {
   const dirs = (process.env.PATH || '').split(path.delimiter);
   for (const d of dirs) {
     if (!d) continue;
-    const hasShim = ['claude', 'claude.cmd', 'claude.exe', 'claude.ps1', 'claude.bat'].some((n) =>
-      existsSync(path.join(d, n)),
-    );
-    if (!hasShim) continue;
+    const exts = ['', '.cmd', '.exe', '.ps1', '.bat'];
+    if (!exts.some((e) => existsSync(path.join(d, name + e)))) continue;
     // Running cli.js with our own interpreter only works under a real Node/Bun,
     // not inside a compiled single-file binary (which is not a JS interpreter).
     if (!isCompiledBinary()) {
-      const js = claudeCliJs(d) || shimTarget(d);
+      const js = (name === 'claude' && claudeCliJs(d)) || shimTarget(d, name);
       if (js) return { kind: 'script', script: js };
     }
-    if (existsSync(path.join(d, 'claude.exe'))) return { kind: 'native', bin: path.join(d, 'claude.exe') };
-    if (existsSync(path.join(d, 'claude.cmd'))) return { kind: 'cmd', bin: path.join(d, 'claude.cmd') };
-    if (existsSync(path.join(d, 'claude.bat'))) return { kind: 'cmd', bin: path.join(d, 'claude.bat') };
+    if (existsSync(path.join(d, name + '.exe'))) return { kind: 'native', bin: path.join(d, name + '.exe') };
+    if (existsSync(path.join(d, name + '.cmd'))) return { kind: 'cmd', bin: path.join(d, name + '.cmd') };
+    if (existsSync(path.join(d, name + '.bat'))) return { kind: 'cmd', bin: path.join(d, name + '.bat') };
   }
   return null;
 }
 
-// The npm shim usually sits next to (or one level up from) the claude-code
-// package — quick static guesses before parsing the shim itself.
+// The Claude npm package additionally ships a cli.js we prefer (static guesses
+// before parsing the shim).
 function claudeCliJs(dir) {
   const rels = [
     ['node_modules', '@anthropic-ai', 'claude-code', 'cli.js'],
@@ -150,12 +172,12 @@ function claudeCliJs(dir) {
   return null;
 }
 
-// Robust fallback: every npm/pnpm/yarn/volta shim literally names the JS entry it
-// runs, relative to the shim dir (`%dp0%\…\cli.js` in .cmd, `$basedir/…/cli.js`
-// in the sh/.ps1 shims). Extract that so any install layout resolves to a real
-// cli.js we can run with our own interpreter.
-function shimTarget(dir) {
-  for (const shim of ['claude.cmd', 'claude', 'claude.ps1']) {
+// Robust, general fallback: every npm/pnpm/yarn/volta shim literally names the JS
+// entry it runs, relative to the shim dir (`%dp0%\…\cli.js` in .cmd,
+// `$basedir/…/cli.js` in the sh/.ps1 shims). Extract that so any install layout
+// resolves to a real JS entry we can run with our own interpreter.
+function shimTarget(dir, name) {
+  for (const shim of [`${name}.cmd`, name, `${name}.ps1`]) {
     let txt;
     try {
       txt = readFileSync(path.join(dir, shim), 'utf8');
@@ -171,25 +193,46 @@ function shimTarget(dir) {
   return null;
 }
 
-// Is `claude` reachable inside the default WSL distro's login shell? Cached;
-// re-probed (throttled) while not found so it self-heals once WSL/claude appear.
-let wslClaude = null;
-let wslProbe = 0;
-function claudeInWsl() {
-  if (wslClaude === null || (!wslClaude && Date.now() - wslProbe > 4000)) {
-    wslProbe = Date.now();
-    try {
-      const r = spawnSync('wsl.exe', ['-e', 'bash', '-lic', 'command -v claude'], {
-        encoding: 'utf8',
-        timeout: 8000,
-        windowsHide: true,
-      });
-      wslClaude = r.status === 0 && /\S/.test(stripBom(r.stdout || ''));
-    } catch {
-      wslClaude = false;
+// Is `name` reachable inside the default WSL distro's login shell? Cached per
+// name; re-probed (throttled) while not found so it self-heals once it appears.
+const wslSeen = new Map(); // name -> { ok, at }
+function commandInWsl(name) {
+  const c = wslSeen.get(name);
+  if (c && (c.ok || Date.now() - c.at < 4000)) return c.ok;
+  let ok = false;
+  try {
+    const r = spawnSync('wsl.exe', ['-e', 'bash', '-lic', `command -v ${name}`], {
+      encoding: 'utf8',
+      timeout: 8000,
+      windowsHide: true,
+    });
+    ok = r.status === 0 && /\S/.test(stripBom(r.stdout || ''));
+  } catch {
+    ok = false;
+  }
+  wslSeen.set(name, { ok, at: Date.now() });
+  return ok;
+}
+
+// Turn a launch spec + CLI args into a concrete [bin, argv, opts] for spawn().
+// `cwd` is the resolved working dir (a Windows path on win32), or null for home.
+export function buildSpawnSpec(spec, args, cwd) {
+  if (spec.kind === 'wsl') {
+    // Run inside WSL's login shell so nvm/etc. PATH resolves the tool. The
+    // `exec <cmd> "$@"` + 'chatpanel' ($0) trick passes our args through as a
+    // proper argv array — no manual quoting, even for multi-line prompts.
+    const pre = [];
+    if (cwd) {
+      const wslCwd = toWslPath(cwd);
+      if (wslCwd) pre.push('--cd', wslCwd); // else: run in WSL home
     }
+    const argv = [...pre, '-e', 'bash', '-lic', `exec ${spec.command} "$@"`, 'chatpanel', ...args];
+    return ['wsl.exe', argv, { stdio: ['pipe', 'pipe', 'pipe'], env: process.env, windowsHide: true }];
   }
-  return wslClaude;
+  const opts = { cwd: cwd || os.homedir(), stdio: ['pipe', 'pipe', 'pipe'], env: process.env, windowsHide: true };
+  if (spec.kind === 'script') return [process.execPath, [spec.script, ...args], opts];
+  if (spec.kind === 'cmd') return ['cmd.exe', ['/d', '/s', '/c', spec.bin, ...args], opts];
+  return [spec.bin, args, opts]; // native
 }
 
 // Translate a Windows path to its WSL (/mnt/c/…) equivalent. Returns null on

package/src/server.js

@@ -19,14 +19,15 @@ 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 * as custom from './engines/custom.js';
 import { installService, uninstallService, serviceStatus, restartService } from './service.js';
-import { enrichPath, findAgentBin } from './env.js';
+import { enrichPath, findAgentBin, resolveCommand } from './env.js';
 import { checkForUpdate, selfUpdate } from './update.js';
 
 // Hardcoded (not read from package.json) so it survives Bun's single-file
 // --compile, where package.json isn't on a readable FS. CI fails the publish if
 // this drifts from package.json, so the two can't silently diverge.
-const VERSION = '0.2.16';
+const VERSION = '0.3.0';
 const HOST = process.env.CHATPANEL_BRIDGE_HOST || '127.0.0.1';
 const PORT = Number(process.env.CHATPANEL_BRIDGE_PORT) || 4319;
 
@@ -34,6 +35,10 @@ const ENGINES = {
   claude: { engine: claude, label: 'Claude Code' },
   codex: { engine: codex, label: 'Codex' },
   gemini: { engine: gemini, label: 'Gemini CLI' },
+  // "Bring your own" — one engine drives any user-onboarded CLI (Pro). Hidden
+  // from /health (it's not a single installable agent; the extension manages the
+  // list and validates commands via /agent-check).
+  custom: { engine: custom, label: 'Custom', hidden: true },
 };
 
 // --------------------------------------------------------------------------
@@ -80,10 +85,12 @@ function readBody(req) {
 // --------------------------------------------------------------------------
 async function handleHealth(res) {
   const agents = await Promise.all(
-    Object.entries(ENGINES).map(async ([id, { engine, label }]) => {
-      const a = await engine.available().catch((e) => ({ ok: false, reason: String(e?.message || e) }));
-      return { id, label, available: a.ok, reason: a.reason };
-    }),
+    Object.entries(ENGINES)
+      .filter(([, e]) => !e.hidden)
+      .map(async ([id, { engine, label }]) => {
+        const a = await engine.available().catch((e) => ({ ok: false, reason: String(e?.message || e) }));
+        return { id, label, available: a.ok, reason: a.reason };
+      }),
   );
   const update = await checkForUpdate(VERSION).catch(() => ({ current: VERSION, updateAvailable: false }));
   json(res, 200, { ok: true, version: VERSION, agents, update });
@@ -184,6 +191,28 @@ async function handleComplete(req, res) {
   }
 }
 
+// POST /agent-check → { command } → { ok, via } — does this command resolve on
+// this machine? Powers the "✓ found" indicator when onboarding a custom agent.
+// `via` tells the user HOW it resolved (native / script / cmd / wsl) so a Windows
+// user sees e.g. "found in WSL". No execution, no entitlement needed (read-only).
+async function handleAgentCheck(req, res) {
+  let body;
+  try {
+    body = await readBody(req);
+  } catch (e) {
+    return json(res, 400, { error: 'Bad JSON: ' + e.message });
+  }
+  const command = String(body.command || '').trim();
+  if (!command) return json(res, 400, { error: 'No command' });
+  let spec = null;
+  try {
+    spec = resolveCommand(command);
+  } catch {
+    spec = null;
+  }
+  return json(res, 200, { ok: !!spec, via: spec ? spec.kind : null });
+}
+
 const server = createServer(async (req, res) => {
   cors(req, res);
   if (req.method === 'OPTIONS') {
@@ -204,6 +233,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 === '/agent-check') return handleAgentCheck(req, res);
     if (req.method === 'POST' && url.pathname === '/update') return handleUpdate(res);
     json(res, 404, { error: 'Not found' });
   } catch (e) {
@@ -220,7 +250,8 @@ function startServer() {
   enrichPath(); // so codex/gemini are found even under a minimal service PATH
   server.listen(PORT, HOST, async () => {
     log('info', `listening on http://${HOST}:${PORT}`);
-    for (const [, { engine, label }] of Object.entries(ENGINES)) {
+    for (const [, { engine, label, hidden }] of Object.entries(ENGINES)) {
+      if (hidden) continue;
       const a = await engine.available().catch(() => ({ ok: false }));
       log('info', `  ${a.ok ? '✓' : '✕'} ${label}${a.ok ? '' : ' — ' + (a.reason || 'unavailable')}`);
     }