@gleapai/kai-bridge 0.6.0 → 0.9.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gleapai/kai-bridge",
-  "version": "0.6.0",
-  "description": "Run Gleap Kai Code sessions on your own machine with your own Claude Code / Codex login — and preview your real dev servers from the dashboard or the phone.",
+  "version": "0.9.0",
+  "description": "Kai Code Bridge runs Kai Code on your computer or server with your own coding subscriptions, local previews, and photo or video verification.",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -12,7 +12,9 @@
     "src",
     "runner",
     "scripts/postinstall.mjs",
-    "README.md"
+    "README.md",
+    "scripts/runtime-smoke.mjs",
+    "npm-shrinkwrap.json"
   ],
   "engines": {
     "node": ">=20"
@@ -20,19 +22,25 @@
   "scripts": {
     "test": "node --test 'test/**/*.test.mjs'",
     "sync-runner": "node scripts/sync-runner.mjs",
-    "postinstall": "node scripts/postinstall.mjs"
+    "postinstall": "node scripts/postinstall.mjs",
+    "runtime:check": "node scripts/runtime-smoke.mjs",
+    "prepack": "node scripts/prepare-release.mjs",
+    "postpack": "node scripts/prepare-release.mjs --clean"
   },
   "dependencies": {
-    "@agentclientprotocol/claude-agent-acp": "0.73.0",
+    "@agentclientprotocol/claude-agent-acp": "0.75.1",
     "@agentclientprotocol/codex-acp": "1.10.0",
     "@agentclientprotocol/sdk": "1.4.0",
     "@playwright/mcp": "^0.0.79",
     "@sockudo/client": "^2.0.0",
     "chokidar": "^4.0.1",
-    "yaml": "^2.9.0"
+    "ws": "^8.21.3",
+    "yaml": "^2.9.0",
+    "@openai/codex": "0.153.4",
+    "@anthropic-ai/claude-agent-sdk": "0.3.266"
   },
   "overrides": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.258"
+    "@anthropic-ai/claude-agent-sdk": "$@anthropic-ai/claude-agent-sdk"
   },
   "exports": {
     ".": "./src/daemon.mjs",

package/runner/lib/acp/harnesses.mjs

@@ -339,7 +339,7 @@ export const HARNESSES = {
       if (!ctx.byoLogin) env.CODEX_API_KEY = env.OPENAI_API_KEY;
       // MCP servers + disabled/gated tools via config.toml (see
       // buildCodexConfigToml) — never via session/new for codex.
-      writeFileSync(join(ctx.configDir, "config.toml"), buildCodexConfigToml(ctx.mcpServers));
+      if (process.env.KAI_HOSTED !== '1') writeFileSync(join(ctx.configDir, "config.toml"), buildCodexConfigToml(ctx.mcpServers));
       env.NO_BROWSER = "1";
       env.INITIAL_AGENT_MODE = ctx.isPlanMode ? "read-only" : "agent-full-access";
       // Session config merged by the adapter: model + effort + our
@@ -349,6 +349,11 @@ export const HARNESSES = {
         ...(ctx.effort ? { model_reasoning_effort: ctx.effort } : {}),
         ...(ctx.instructionsPath ? { model_instructions_file: ctx.instructionsPath } : {}),
         ...(ctx.maxContextTokens ? { model_context_window: ctx.maxContextTokens } : {}),
+        ...(process.env.KAI_HOSTED === '1' ? { features: { apps: false, collaboration_modes: true },
+          mcp_servers: Object.fromEntries((ctx.mcpServers || []).filter(s => s && (s.url || s.command)).map(s => [sanitizeMcpKey(s.name || s.id), {
+            ...(s.transport === 'http' ? { url: s.url, http_headers: s.headers || {} } : { command: s.command, args: s.args || [], env: s.env || {} }),
+            startup_timeout_sec: 60, tool_timeout_sec: 60, default_tools_approval_mode: 'approve', disabled_tools: [...(s.disabledTools || []), ...(s.gatedTools || [])],
+          }])) } : {}),
       };
       env.CODEX_CONFIG = JSON.stringify(config);
       return env;

package/scripts/runtime-smoke.mjs

@@ -0,0 +1,60 @@
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, basename } from 'node:path';
+import { createInterface } from 'node:readline';
+import { harnessBinary, harnessAcpCommand } from '../src/harnesses.mjs';
+import { ensureClaudeAcpPatched } from '../src/acp-patch.mjs';
+
+const exec = promisify(execFile);
+const home = mkdtempSync(join(tmpdir(), 'kai-runtime-check-'));
+// No real login, API key, project, device token or user settings in a smoke test.
+const env = { PATH: process.env.PATH, HOME: home, USERPROFILE: home, CODEX_HOME: join(home, 'codex'), CLAUDE_CONFIG_DIR: join(home, 'claude'), DISABLE_AUTOUPDATER: '1', CI: '1', KAI_RUNTIME_UPDATE_CHECK: '1' };
+mkdirSync(env.CODEX_HOME); mkdirSync(env.CLAUDE_CONFIG_DIR);
+
+async function initialize(command, args, params) {
+  const child = spawn(command, args, { env, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'] });
+  const lines = createInterface({ input: child.stdout });
+  let diagnostic = '';
+  child.stdin.on('error', () => {}); child.stderr.on('data', data => { diagnostic = (diagnostic + data).slice(-1500); });
+  let killTimer;
+  try {
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('Runtime protocol initialization timed out.')), 12_000);
+      const finish = error => { clearTimeout(timer); error ? reject(error) : resolve(); };
+      child.once('error', finish);
+      child.once('exit', (code, signal) => finish(new Error(`${basename(command)} exited before initialization (${code ?? signal}): ${diagnostic}`)));
+      lines.on('line', line => {
+        let message; try { message = JSON.parse(line); } catch { return; }
+        if (message.id === 1) finish(message.error || !message.result ? new Error('Runtime protocol initialization failed.') : null);
+      });
+      child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params }) + '\n');
+    });
+  } finally {
+    lines.close();
+    const kill = signal => { try { process.platform === 'win32' ? child.kill(signal) : process.kill(-child.pid, signal); } catch {} };
+    kill('SIGTERM');
+    await new Promise(resolve => { killTimer = setTimeout(() => { kill('SIGKILL'); resolve(); }, 1500); child.once('close', () => { clearTimeout(killTimer); resolve(); }); });
+  }
+}
+
+try {
+  ensureClaudeAcpPatched();
+  for (const harness of ['claude', 'codex']) {
+    const binary = harnessBinary(harness);
+    if (!binary) throw new Error(`${harness} executable is missing.`);
+    const { stdout } = await exec(binary, ['--version'], { env, timeout: 12_000, maxBuffer: 64 * 1024 });
+    if (!/\d+\.\d+\.\d+/.test(stdout)) throw new Error(`${harness} version check failed.`);
+    console.log(`${harness}: ${stdout.trim()}`);
+    env[harness === 'claude' ? 'CLAUDE_CODE_EXECUTABLE' : 'CODEX_PATH'] = binary;
+  }
+  await initialize(harnessBinary('codex'), ['app-server'], { clientInfo: { name: 'kai-runtime-check', version: '1.0.0' }, capabilities: {} });
+  for (const harness of ['claude', 'codex']) {
+    const adapter = harnessAcpCommand(harness);
+    await initialize(adapter.cmd, adapter.args, { protocolVersion: 1, clientCapabilities: {}, clientInfo: { name: 'kai-runtime-check', version: '1.0.0' } });
+  }
+  // Imports catch packaging omissions and syntax/dependency failures before boot.
+  await import('../src/daemon.mjs'); await import('../src/harness-install.mjs');
+  console.log('Native CLIs, Codex app-server and both ACP adapters passed isolated startup checks.');
+} finally { rmSync(home, { recursive: true, force: true }); }

package/src/daemon.mjs

@@ -1,3 +1,4 @@
+import { cloneRepository, locateRepository } from './repository-setup.mjs';
 // The always-on part: one outbound realtime subscription for commands,
 // REST for everything the device reports. Idles at ~0 CPU; reconnects
 // with backoff; keeps the machine awake only while a turn runs.
@@ -1452,6 +1453,7 @@ export class BridgeDaemon {
       outcome = {
         status: ctrl.signal.aborted ? "cancelled" : res.rateLimited ? "rate_limited" : res.code === 0 ? "completed" : "failed",
         exitCode: res.code,
+        ...(res.errorCode ? { errorCode: res.errorCode } : {}),
         result: verify?.redact?.size ? redactDeep(res.result, verify.redact) : res.result,
         // The runner's own failure text (e.g. the engine's usage-limit
         // message) — the Server prefers this over its generic fallback.
@@ -2393,65 +2395,27 @@ export class BridgeDaemon {
    * unattended runs: no credential prompts (`GIT_TERMINAL_PROMPT=0`,
    * `GIT_ASKPASS=echo`), stderr captured for the error, bounded by
    * `timeoutMs` (default 3 min). Resolves the checkout path; throws an Error
-   * carrying `.target` and the stderr tail. As a command handler
+   * carrying `.target` and a diagnostic message. As a command handler
    * (`bridge.repo.clone`) it acks ok/error instead of throwing.
    */
-  async cloneRepo({ commandId, remote, name, timeoutMs = CLONE_TIMEOUT_MS }) {
-    // Prefer the directory the machine's repos already live in (e.g.
-    // ~/Documents/Gleap), not the bare scan root that discovered them
-    // (~/Documents) — "Clone here" should land next to the other checkouts.
+  async cloneRepo({ commandId, remote, name, repoKey, timeoutMs = CLONE_TIMEOUT_MS }) {
     const root = preferredCloneRoot(this.repoGroups, (this.config.roots || [])[0] ?? defaultRoots()[0]);
-    const fail = async (err) => {
+    try {
+      const target = await cloneRepository({ remote, name, root, repoKey, timeoutMs });
+      await this.scanRepos();
+      // Ack only after the Server has the new inventory: recovery checks
+      // readiness before automatically retrying the blocked session.
+      await this.hello();
+      if (commandId) await this.api.commandAck(commandId, { ok: true, path: target });
+      return target;
+    } catch (err) {
+      if (err.target) err.cloneCommand = buildCloneCommand({ remote, target: err.target });
       if (commandId) {
         await this.api.commandAck(commandId, { ok: false, error: err.message, ...(err.cloneCommand ? { cloneCommand: err.cloneCommand } : {}) }).catch(() => {});
         return null;
       }
       throw err;
-    };
-    if (!root) return fail(new Error("No scan root to clone into — add one with `kai-bridge repo roots add <dir>`."));
-    const target = join(root, String(name || "").replace(/[^\w.-]/g, "-") || "repo");
-    if (existsSync(target)) {
-      const err = new Error(`${target} already exists — remove it or point Gleap at it (Locate…).`);
-      err.target = target;
-      return fail(err);
-    }
-    try {
-      await new Promise((resolve, reject) => {
-        const p = spawn("git", ["clone", remote, target], {
-          stdio: ["ignore", "ignore", "pipe"],
-          env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "echo", SSH_ASKPASS: "echo", GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND || "ssh -o BatchMode=yes" },
-        });
-        let stderr = "";
-        p.stderr.on("data", (d) => {
-          stderr = `${stderr}${d}`.slice(-4000);
-        });
-        const timer = setTimeout(() => {
-          try {
-            p.kill("SIGTERM");
-          } catch {}
-          reject(Object.assign(new Error(`git clone timed out after ${Math.round(timeoutMs / 60_000)} minutes`), { target, stderr }));
-        }, timeoutMs);
-        p.on("close", (code) => {
-          clearTimeout(timer);
-          if (code === 0) return resolve();
-          const tail = stderr.trim().split("\n").filter(Boolean).slice(-2).join(" · ").slice(0, 300);
-          reject(Object.assign(new Error(`git clone exited ${code}${tail ? ` — ${tail}` : ""}`), { target, stderr, code }));
-        });
-        p.on("error", (err) => {
-          clearTimeout(timer);
-          reject(Object.assign(err, { target }));
-        });
-      });
-    } catch (err) {
-      this.log("error", "repo.clone.failed", { remote, target, error: err.message });
-      rmSync(target, { recursive: true, force: true });
-      err.cloneCommand = buildCloneCommand({ remote, target });
-      return fail(err);
     }
-    await this.scanRepos();
-    await this.hello().catch(() => {});
-    if (commandId) await this.api.commandAck(commandId, { ok: true, path: target });
-    return target;
   }
 
   /**
@@ -2466,11 +2430,7 @@ export class BridgeDaemon {
    */
   async locateRepo({ commandId, repoKey, path: rawPath }) {
     try {
-      const target = resolvePath(String(rawPath || "").replace(/^~(?=$|\/)/, homedir()));
-      if (!existsSync(target)) throw new Error(`${target} does not exist on this machine.`);
-      if (repoKey && !existsSync(join(target, ".git"))) {
-        throw new Error(`${target} is not a git checkout.`);
-      }
+      const target = locateRepository(rawPath, repoKey);
       const root = repoKey ? dirname(target) : target;
       this.config.roots = [...new Set([...(this.config.roots || []), root])];
       if (repoKey) {
@@ -2499,10 +2459,10 @@ export class BridgeDaemon {
     }
   }
 
-  async harnessInstall({ commandId, harness }) {
+  async harnessInstall({ commandId, harness, update = false }) {
     const lines = [];
     try {
-      const res = await installHarness(harness, { kaiHome: this.kaiHome, onLog: (l) => { lines.push(l); this.log("info", "harness.install", { harness, line: l }); } });
+      const res = await installHarness(harness, { kaiHome: this.kaiHome, update, onLog: (l) => { lines.push(l); this.log("info", "harness.install", { harness, line: l }); } });
       await this.hello();
       if (commandId) await this.api.commandAck(commandId, { ok: res.ok, version: res.version, log: lines });
     } catch (err) {
@@ -2512,24 +2472,34 @@ export class BridgeDaemon {
   }
 
   async profileLogin({ commandId, profileId }) {
-    const profile = resolveProfiles(this.config, this.kaiHome).find((p) => p.id === profileId);
-    if (!profile) throw new Error(`Unknown profile ${profileId}`);
-    if (profile.kind === "managed") createManagedProfile(profile.harness, profile.id, this.kaiHome);
-    // Logins are interactive: open a terminal on this machine running the
-    // harness's own login under the profile's config dir, and re-announce
-    // the profile state once it exits.
-    const child = openLoginTerminal(profile.harness, profile.configDir);
-    if (!child) throw new Error(`Could not open a terminal for ${profile.harness} login on this device.`);
-    child.unref?.();
-    if (commandId) await this.api.commandAck(commandId, { ok: true, opened: "terminal" });
-    const poll = setInterval(() => {
-      this.hello().catch(() => {});
-      // First sign-in for this harness: learn its models as soon as the
-      // login lands (later refreshes ride the slow timer).
-      if (!this.modelsByHarness.has(profile.harness)) void this.refreshHarnessModels();
-    }, 15_000);
-    poll.unref?.();
-    setTimeout(() => clearInterval(poll), 10 * 60_000).unref?.();
+    try {
+      const profile = resolveProfiles(this.config, this.kaiHome).find((p) => p.id === profileId);
+      if (!profile) throw new Error(`Unknown profile ${profileId}`);
+      if (profile.kind === "managed") createManagedProfile(profile.harness, profile.id, this.kaiHome);
+      // Logins are interactive: open a terminal on this machine running the
+      // harness's own login under the profile's config dir, and re-announce
+      // the profile state once it exits.
+      await installHarness(profile.harness, { kaiHome: this.kaiHome });
+      const child = openLoginTerminal(profile.harness, profile.configDir, this.kaiHome);
+      if (child) await new Promise((resolve, reject) => {
+        child.once('spawn', resolve);
+        child.once('error', reject);
+      });
+      child?.unref?.();
+      const command = `kai-bridge profile login '${String(profile.id).replace(/'/g, "'\\''")}'${profile.harness === 'codex' ? ' --device-auth' : ''}`;
+      if (commandId) await this.api.commandAck(commandId, { ok: true, opened: child ? "terminal" : "ssh", ...(!child ? { command } : {}) });
+      const poll = setInterval(() => {
+        this.hello().catch(() => {});
+        // First sign-in for this harness: learn its models as soon as the
+        // login lands (later refreshes ride the slow timer).
+        if (!this.modelsByHarness.has(profile.harness)) void this.refreshHarnessModels();
+      }, 15_000);
+      poll.unref?.();
+      setTimeout(() => clearInterval(poll), 10 * 60_000).unref?.();
+    } catch (err) {
+      if (commandId) await this.api.commandAck(commandId, { ok: false, error: err.message }).catch(() => {});
+      else throw err;
+    }
   }
 }
 

package/src/executor.mjs

@@ -13,8 +13,9 @@ import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { ambientConfigDir, managedConfigDir } from "./profiles.mjs";
-import { harnessAcpCommand } from "./harnesses.mjs";
+import { harnessAcpCommand, harnessBinary } from "./harnesses.mjs";
 import { KAI_HOME } from "./config.mjs";
+import { classifyHarnessFailure } from './harness-errors.mjs';
 
 const RUNNER = join(dirname(fileURLToPath(import.meta.url)), "..", "runner", "acp-runner.mjs");
 const b64 = (v) => Buffer.from(typeof v === "string" ? v : JSON.stringify(v), "utf8").toString("base64");
@@ -77,6 +78,10 @@ export function buildRunnerEnv(turn, profile, kaiHome = KAI_HOME, extraEnv = nul
   for (const [k, v] of Object.entries(extraEnv || {})) if (v != null && v !== "") env[k] = String(v);
   // Never leak the Gleap device token into the harness.
   delete env.KAI_DEVICE_TOKEN;
+  // Login, version probes and coding must resolve the same release's binaries.
+  const native = harnessBinary(profile.harness, kaiHome);
+  if (native && profile.harness === 'claude') { env.CLAUDE_CODE_EXECUTABLE = native; env.DISABLE_AUTOUPDATER = '1'; }
+  if (native && profile.harness === 'codex') env.CODEX_PATH = native;
   // The daemon's own node first on PATH for the runner, the harness and
   // every shell the agent opens. Under launchd PATH is frozen at install
   // time and a stale /usr/local/bin/node (v20 here) beat the nvm node the
@@ -190,7 +195,7 @@ export function runTurn({ turn, profile, workDir, onEvent, onLog = () => {}, onS
     signal?.addEventListener("abort", onAbort, { once: true });
     child.on("close", (code) => {
       signal?.removeEventListener("abort", onAbort);
-      resolve({ code, result, rateLimited, lastError });
+      resolve({ code, result, rateLimited, lastError, errorCode: classifyHarnessFailure(lastError || '') });
     });
   });
 }

package/src/harness-errors.mjs

@@ -0,0 +1,8 @@
+// Only harness authentication failures invalidate a login. An application's
+// HTTP 401 during validation, a quota limit, or an outage must not sign it out.
+export function classifyHarnessFailure(message = '') {
+  if (/rate.?limit|429|usage limit|out of (extra )?usage/i.test(message)) return 'rate_limited';
+  if (/refresh_token_(reused|expired|invalidated)|not logged in|login (has )?expired|login required|authentication[_ ](?:error|required)|oauth.{0,30}(expired|invalid)|model provider rejected.{0,30}401/i.test(message)) return 'authentication_required';
+  if (/service unavailable|provider.{0,30}(unavailable|outage)|HTTP 50[234]|ECONNRESET|ETIMEDOUT/i.test(message)) return 'provider_unavailable';
+  return null;
+}

package/src/harness-install.mjs

@@ -0,0 +1,73 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+export const HARNESS_PACKAGES = { codex: '@openai/codex', claude: '@anthropic-ai/claude-agent-sdk' };
+const rootFor = (home, harness) => join(home, 'harnesses', harness);
+
+export function managedHarnessRoot(home, harness) {
+  try {
+    const { active } = JSON.parse(readFileSync(join(rootFor(home, harness), 'active.json'), 'utf8'));
+    if (!/^[a-f0-9-]{36}$/.test(active)) return null;
+    const root = join(rootFor(home, harness), 'releases', active);
+    return existsSync(join(root, 'package.json')) ? root : null;
+  } catch { return null; }
+}
+
+async function installPackage(destination, spec) {
+  const npmCli = [process.env.npm_execpath, join(dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js'), join(dirname(process.execPath), '../lib/node_modules/npm/bin/npm-cli.js')]
+    .find(p => p?.endsWith('npm-cli.js') && existsSync(p));
+  if (!npmCli && process.platform === 'win32') throw new Error('npm is missing. Install Node.js with npm, then retry.');
+  const args = ['install', '--prefix', destination, '--ignore-scripts', '--save-exact', '--no-audit', '--no-fund', spec];
+  await exec(npmCli ? process.execPath : 'npm', npmCli ? [npmCli, ...args] : args, {
+    timeout: 5 * 60_000, maxBuffer: 2 * 1024 * 1024,
+  });
+}
+
+/** Download into an isolated release, verify it runs, then atomically select it.
+ * Existing sessions retain their old binaries; profiles and global CLIs are untouched. */
+export async function installManagedHarness({ harness, kaiHome, version = 'latest', resolveBinary, probeVersion, onLog = () => {}, install = installPackage }) {
+  const packageName = HARNESS_PACKAGES[harness];
+  if (!packageName || !/^(latest|\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?)$/.test(version)) throw new Error('Choose a valid coding agent version.');
+  const root = rootFor(kaiHome, harness);
+  mkdirSync(root, { recursive: true });
+  const lock = join(root, '.install-lock');
+  try { mkdirSync(lock); } catch {
+    let abandoned = false;
+    try {
+      const { pid } = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'));
+      if (Number.isSafeInteger(pid) && pid > 0) {
+        try { process.kill(pid, 0); } catch (error) { abandoned = error.code === 'ESRCH'; }
+      }
+    } catch { abandoned = Date.now() - statSync(lock).mtimeMs > 10 * 60_000; }
+    if (!abandoned) throw new Error('An installation is already running for this agent. Try again when it finishes.');
+    rmSync(lock, { recursive: true, force: true });
+    try { mkdirSync(lock); } catch { throw new Error('Another agent installation started. Try again when it finishes.'); }
+  }
+  writeFileSync(join(lock, 'owner.json'), JSON.stringify({ pid: process.pid }));
+  const release = randomUUID();
+  const destination = join(root, 'releases', release);
+  const temporary = join(root, `active-${release}.tmp`);
+  let activated = false;
+  try {
+    mkdirSync(destination, { recursive: true });
+    writeFileSync(join(destination, 'package.json'), JSON.stringify({ private: true }));
+    onLog(`Installing ${harness} ${version}…`);
+    await install(destination, `${packageName}@${version}`);
+    const binary = resolveBinary(destination);
+    const detected = binary && await probeVersion(binary);
+    if (!detected) throw new Error('The new coding agent did not start. Your previous version is still selected.');
+    writeFileSync(temporary, JSON.stringify({ active: release, version: detected }), { mode: 0o600 });
+    renameSync(temporary, join(root, 'active.json'));
+    activated = true;
+    onLog(`Ready: ${detected}`);
+    return { ok: true, version: detected, binary };
+  } finally {
+    rmSync(temporary, { force: true });
+    if (!activated) rmSync(destination, { recursive: true, force: true });
+    rmSync(lock, { recursive: true, force: true });
+  }
+}

package/src/harnesses.mjs

@@ -1,27 +1,16 @@
-// Harness registry: which coding agents this device can run, how to find
-// their binaries, install/update them, probe their login, and open a
-// login.
-//
-//   claude — Claude Code. BUNDLED: the ACP adapter ships the Agent SDK,
-//            which ships the CLI. Nothing to install; only a login.
-//   codex  — Codex CLI. BUNDLED by codex-acp. Only a login.
-//   cursor — Cursor Agent CLI. NOT bundled (no npm package); installed by
-//            the bridge from Cursor's release tarball into
-//            ~/.kai/harnesses/cursor/<version>/ and called by path — never
-//            via the vendor's ~/.local/bin/agent symlink (other vendors
-//            use that name too: Grok's CLI on at least one dev machine).
-//
-// "Installed" therefore means: claude/codex always; cursor when the
-// tarball is present. "Signed in" is per profile (see profiles.mjs).
+// Coding agents: bundled defaults, optional managed updates, and per-profile sign-in.
 
 import { execFileSync, spawn } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { arch, homedir, platform } from "node:os";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createRequire } from 'node:module';
+import { managedHarnessRoot, installManagedHarness } from './harness-install.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), "..");
 const PKG_BIN = join(PKG, "node_modules", ".bin");
+const require = createRequire(import.meta.url);
 
 export const HARNESS_IDS = ["claude", "codex", "cursor"];
 
@@ -74,24 +63,43 @@ export function cursorDownloadUrl(version = CURSOR_AGENT_VERSION) {
 }
 
 /** Bundled / installed binary for a harness, or null. */
-export function harnessBinary(harness, kaiHome = join(homedir(), ".kai")) {
+function packageBinary(harness, packageRequire) {
   if (harness === "claude") {
-    const pkgDir = join(PKG, "node_modules", "@anthropic-ai");
     try {
-      const plat = readdirSync(pkgDir).find((d) => d.startsWith("claude-agent-sdk-") && d !== "claude-agent-sdk");
-      if (plat) {
-        const bin = join(pkgDir, plat, platform() === "win32" ? "claude.exe" : "claude");
-        if (existsSync(bin)) return bin;
-      }
+      // Resolve from the SDK exactly as the ACP adapter does, including nested
+      // npm installs and the correct libc. Directory order is not a platform check.
+      const sdkRequire = createRequire(packageRequire.resolve('@anthropic-ai/claude-agent-sdk'));
+      const libc = platform() === 'linux' && !process.report.getReport().header.glibcVersionRuntime ? '-musl' : '';
+      return sdkRequire.resolve(`@anthropic-ai/claude-agent-sdk-${platform()}-${arch()}${libc}/claude${platform() === 'win32' ? '.exe' : ''}`);
     } catch {
       /* not installed */
     }
     return null;
   }
   if (harness === "codex") {
-    const bin = join(PKG_BIN, platform() === "win32" ? "codex.cmd" : "codex");
-    return existsSync(bin) ? bin : null;
+    try {
+      if (platform() === 'win32') {
+        // execFile/ACP cannot execute a JS entrypoint or .cmd shim directly on
+        // Windows. Resolve the same pinned package's native executable there.
+        const codexRequire = createRequire(packageRequire.resolve('@openai/codex/package.json'));
+        const root = dirname(codexRequire.resolve(`@openai/codex-win32-${arch()}/package.json`));
+        const triple = `${arch() === 'arm64' ? 'aarch64' : 'x86_64'}-pc-windows-msvc`;
+        const binary = join(root, 'vendor', triple, 'bin', 'codex.exe');
+        return existsSync(binary) ? binary : null;
+      }
+      return packageRequire.resolve('@openai/codex/bin/codex.js');
+    } catch { return null; }
+  }
+  return null;
+}
+
+export function harnessBinary(harness, kaiHome = process.env.KAI_HOME || join(homedir(), ".kai")) {
+  const managed = managedHarnessRoot(kaiHome, harness);
+  if (managed) {
+    const binary = packageBinary(harness, createRequire(join(managed, "package.json")));
+    if (binary && existsSync(binary)) return binary;
   }
+  if (harness === "claude" || harness === "codex") return packageBinary(harness, require);
   if (harness === "cursor") {
     const bin = join(CURSOR_CURRENT(kaiHome), "dist-package", platform() === "win32" ? "cursor-agent.exe" : "cursor-agent");
     return existsSync(bin) ? bin : null;
@@ -135,18 +143,22 @@ export function describeHarnesses(kaiHome) {
 }
 
 /**
- * Install (or update) a harness. Bundled ones are no-ops. Cursor:
+ * Install (or update) a coding agent. Cursor:
  * download the release tarball for this platform into
  * ~/.kai/harnesses/cursor/<version>/ and point `current` at it.
  * `onLog(line)` receives progress; resolves `{ ok, version, binary }`.
  */
-export async function installHarness(harness, { kaiHome, onLog = () => {}, version = CURSOR_AGENT_VERSION } = {}) {
+export async function installHarness(harness, { kaiHome = process.env.KAI_HOME || join(homedir(), ".kai"), onLog = () => {}, version, update = false } = {}) {
   if (!HARNESS_IDS.includes(harness)) throw new Error(`unknown harness ${harness}`);
   if (HARNESS_INFO[harness].bundled) {
     const bin = harnessBinary(harness, kaiHome);
-    onLog(`${HARNESS_INFO[harness].label} is bundled with the bridge (${bin ? versionOf(bin) : "missing — run npm install"})`);
-    return { ok: !!bin, version: bin ? versionOf(bin) : null, binary: bin };
+    const currentVersion = bin ? versionOf(bin) : null;
+    if (!update && !version && currentVersion) return { ok: true, version: currentVersion, binary: bin };
+    return installManagedHarness({ harness, kaiHome, version: version || 'latest', onLog,
+      resolveBinary: root => packageBinary(harness, createRequire(join(root, 'package.json'))), probeVersion: versionOf });
   }
+  version ||= CURSOR_AGENT_VERSION;
+  if (!/^[0-9][a-zA-Z0-9.-]*$/.test(version)) throw new Error("Invalid Cursor version.");
   const root = CURSOR_ROOT(kaiHome);
   const target = join(root, version);
   const tmp = join(root, `.tmp-${version}-${process.pid}`);
@@ -186,7 +198,11 @@ export async function installHarness(harness, { kaiHome, onLog = () => {}, versi
 }
 
 /** Interactive login command for a harness under a profile's config dir. */
-export function harnessLoginCommand(harness, configDir, kaiHome) {
+export function isHeadless(env = process.env, os = platform()) {
+  return !!(env.SSH_CONNECTION || env.SSH_TTY || (os === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY));
+}
+
+export function harnessLoginCommand(harness, configDir, kaiHome, { deviceAuth = isHeadless() } = {}) {
   const bin = harnessBinary(harness, kaiHome);
   if (!bin) return null;
   if (harness === "claude") {
@@ -194,9 +210,9 @@ export function harnessLoginCommand(harness, configDir, kaiHome) {
     // Ambient login must land in the keychain (env untouched) so the
     // equally-untouched probe and turns find it; managed dirs are exported.
     const env = resolvePath(configDir) !== resolvePath(claudeDefault) ? { CLAUDE_CONFIG_DIR: configDir } : {};
-    return { cmd: bin, args: ["login"], env };
+    return { cmd: bin, args: ["auth", "login"], env };
   }
-  if (harness === "codex") return { cmd: bin, args: ["login"], env: { CODEX_HOME: configDir } };
+  if (harness === "codex") return { cmd: bin, args: ["login", ...(deviceAuth ? ["--device-auth"] : [])], env: { CODEX_HOME: configDir } };
   return { cmd: bin, args: ["login"], env: {} };
 }
 

package/src/preview-ports.mjs

@@ -0,0 +1,20 @@
+// Reserve before boot: two sessions can otherwise choose the same free port.
+export class PreviewPortPool {
+  constructor() { this.owners = new Map(); this.tail = Promise.resolve(); }
+  reserve(owner, preferred, pinned, listening) {
+    const operation = this.tail.then(async () => {
+      const current = [...this.owners].find(([, who]) => who === owner);
+      if (current) return current[0];
+      const first = Number.isInteger(preferred) && preferred >= 1024 && preferred <= 65535 ? preferred : 43000;
+      for (let i = 0; i < (pinned ? 1 : 10000); i++) {
+        const port = 1024 + ((first - 1024 + i) % (65536 - 1024));
+        if (this.owners.has(port) || await listening(port)) continue;
+        this.owners.set(port, owner); return port;
+      }
+      throw new Error(pinned ? `Port ${first} is already reserved. Use a port variable in .gleap/dev.yaml to run concurrent previews.` : 'No preview ports are available. Stop an unused preview and retry.');
+    });
+    this.tail = operation.catch(() => {}); return operation;
+  }
+  releaseSession(sessionId) { for (const [port, owner] of this.owners) if (owner.startsWith(`${sessionId}/`)) this.owners.delete(port); }
+}
+export const previewPorts = new PreviewPortPool();