@gleapai/kai-bridge 0.6.0 → 0.7.0

package/fly/Dockerfile

@@ -0,0 +1,11 @@
+FROM node:24-bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates curl sudo openssh-client lsof procps supervisor xvfb fluxbox x11vnc novnc websockify python3 make g++ && rm -rf /var/lib/apt/lists/*
+RUN useradd --home-dir /data/home/kai --shell /bin/bash kai && printf 'kai ALL=(ALL) NOPASSWD:ALL\n' > /etc/sudoers.d/kai && chmod 440 /etc/sudoers.d/kai
+WORKDIR /opt/kai-bridge
+COPY package.json package-lock.json ./
+RUN npm ci --ignore-scripts
+COPY . .
+ENV PLAYWRIGHT_BROWSERS_PATH=/opt/playwright
+RUN node scripts/postinstall.mjs && node scripts/runtime-smoke.mjs && chmod +x src/codex-broker-client.mjs src/hosted-git.mjs fly/runtime-cli.sh fly/entrypoint.sh fly/login-codex.sh && for cli in codex claude git; do ln -s /opt/kai-bridge/fly/runtime-cli.sh /usr/local/bin/$cli; done && npx playwright install --with-deps chromium
+ENV KAI_HOSTED=1 KAI_HOME=/data/home/kai/.kai HOME=/data/home/kai KAI_BRIDGE_NO_SELF_UPDATE=1 DISABLE_AUTOUPDATER=1
+ENTRYPOINT ["/opt/kai-bridge/fly/entrypoint.sh"]

package/fly/UPDATES.md

@@ -0,0 +1,76 @@
+# Hosted coding runtime releases
+
+One Bridge release owns the complete coding runtime: Codex CLI, Claude Agent SDK
+(including its native Claude Code binary), both ACP adapters, Bridge and its
+runner. Versions are pinned in package.json and package-lock.json. The image no
+longer installs separate global CLIs. `codex`, `claude`, login, version probes,
+coding turns and the supervised Codex process all resolve this bundle.
+
+## Routine updates
+
+Dependabot checks npm dependencies daily and groups the coding runtime changes.
+The `Coding runtime compatibility` workflow runs the full Bridge tests, native
+CLI versions, Codex app-server and both ACP initialization checks, package checks
+and the Linux image build. Vendor CLI updates are disabled for the managed
+executables so they cannot mutate a tested bundle underneath active sessions.
+
+After review and internal qualification, publish a new Bridge version and promote
+that exact version to the npm `hosted-stable` dist-tag. Promotion is a release
+operation, never something a customer VM decides from upstream `latest` versions.
+The channel is intentionally separate from `latest`, which connected devices use.
+No tag is published or promoted merely by adding this workflow.
+
+`npm pack`/`npm publish` generate a published npm-shrinkwrap.json from the committed
+lockfile. Consumers therefore receive the dependency tree that was tested. The
+temporary shrinkwrap is removed after packing. Always bump the Bridge version and
+refresh its lockfile for a new release; npm versions are immutable.
+
+Each hosted machine checks `hosted-stable` on a normal start, at most once per day.
+It does not wake a stopped machine to check. Updates only happen **before
+supervisord starts**, under a file lock; running coding, validation, previews,
+maintenance and login processes are never hot-replaced. A machine that remains
+running applies updates on its next normal stop/start.
+
+The updater downloads an exact release, checks protocol compatibility, installs
+the shrinkwrapped dependencies with lifecycle scripts disabled, and runs native
+startup checks with an empty temporary home. It selects the new bundle atomically
+only after those checks pass. Registry failures, invalid releases, failed checks
+and interrupted installs preserve the previous selection. Failed versions are
+quarantined; the next distinct approved version can still update.
+
+Runtime files are stored under `/opt/kai-runtime`. User repositories, worktrees,
+home directories and authentication remain on `/data` and are never copied or
+overwritten by updates. The current and one previous installed bundle are kept.
+This does not rebuild the VM, reset its usage allowance, or require a new login.
+Setup/update running time still counts against the slot allowance.
+
+## Rollback and support
+
+Inspect `/opt/kai-runtime/state.json` for the active version, previous version,
+last check, failed version and update error. Bridge's normal version/harness
+reports show the selected executable versions in Gleap. Updates can be disabled
+with the machine environment `KAI_HOSTED_RUNTIME_UPDATES=0`.
+
+If a runtime passes startup checks but later proves incompatible, schedule a
+rollback through maintenance SSH:
+
+```sh
+sudo node /opt/kai-bridge/fly/runtime-update.mjs --rollback-next-start
+```
+
+Then stop and start the machine through Gleap. This selects the retained previous
+bundle (or the image's original bundle), preserves credentials/files and
+quarantines the rejected release. The command does not interrupt current work.
+Do not run `npm update` inside active release directories.
+
+The startup checks exercise real binaries and protocol initialization without
+account credentials or billable prompts. They do not replace authenticated
+two-session coding/refresh/verification tests on the internal cohort before
+promoting `hosted-stable`. A startup pass cannot guarantee compatibility with
+every provider-side behavior. Keep the previous runtime available for rollback.
+
+Changing the bootstrap protocol, OS packages, browser revision or persistent data formats requires
+an explicit image/migration release; the boot updater rejects unsupported
+protocol versions and Playwright revisions that differ from the image's installed
+browser. System modifications survive normal starts as configured by
+Fly root-filesystem persistence.

package/fly/codex-auth.mjs

@@ -0,0 +1,5 @@
+import { startCodexBroker } from '../src/codex-broker.mjs';
+import { mkdirSync } from 'node:fs';
+mkdirSync('/data/home/kai/.codex', { recursive: true });
+const broker = startCodexBroker();
+process.on('SIGTERM', () => { broker.close(); process.exit(0); });

package/fly/entrypoint.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+set -eu
+mkdir -p /data/home/kai/.codex /data/home/kai/.claude /data/repos /data/logs
+chown kai:kai /data/home/kai /data/home/kai/.codex /data/home/kai/.claude /data/repos /data/logs
+touch /run/kai-runtime-update.lock
+chown root:kai /run/kai-runtime-update.lock
+chmod 660 /run/kai-runtime-update.lock
+# The lock and boot boundary keep installations away from coding/login/preview
+# processes. Failed or interrupted updates keep the previous validated bundle.
+KAI_RUNTIME_ROOT="$(flock /run/kai-runtime-update.lock node /opt/kai-bridge/fly/runtime-update.mjs)"
+export KAI_RUNTIME_ROOT
+exec /usr/bin/supervisord -n -c /opt/kai-bridge/fly/supervisord.conf

package/fly/login-codex.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+set -eu
+# Pause the single refresh owner while native device authentication updates it.
+exec 9>/data/codex-login.lock
+flock -n 9 || { echo 'Another Codex sign-in is already in progress.'; exit 1; }
+control='/opt/kai-bridge/fly/supervisord.conf'
+supervisorctl -c "$control" stop codex-auth
+trap 'supervisorctl -c "$control" start codex-auth' EXIT
+sudo -iu kai codex login --device-auth

package/fly/runtime-cli.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { basename, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { spawn } from 'node:child_process';
+import { runtimeRoot } from './runtime-update.mjs';
+
+const root = process.env.KAI_RUNTIME_ROOT || runtimeRoot();
+const name = process.env.KAI_RUNTIME_CLI_NAME || basename(process.argv[1]).replace(/\.mjs$/, '');
+const { harnessBinary } = await import(pathToFileURL(join(root, 'src/harnesses.mjs')));
+const command = name === 'git' ? process.execPath : harnessBinary(name);
+if (!command) { process.stderr.write('The selected Kai runtime is missing this executable.\n'); process.exit(1); }
+const args = name === 'git' ? [join(root, 'src/hosted-git.mjs'), ...process.argv.slice(2)] : process.argv.slice(2);
+const child = spawn(command, args, { stdio: 'inherit', env: { ...process.env, KAI_RUNTIME_ROOT: root, DISABLE_AUTOUPDATER: '1' } });
+child.on('error', () => process.exit(1));
+child.on('exit', (code, signal) => { if (signal) process.kill(process.pid, signal); else process.exit(code ?? 1); });

package/fly/runtime-cli.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+set -eu
+KAI_RUNTIME_CLI_NAME="${0##*/}"
+export KAI_RUNTIME_CLI_NAME
+# Startup validation has an isolated HOME and already holds the exclusive lock.
+if [ "${KAI_RUNTIME_UPDATE_CHECK:-0}" = '1' ]; then
+  exec node /opt/kai-bridge/fly/runtime-cli.mjs "$@"
+fi
+# A native CLI opened through maintenance SSH waits for an in-progress update.
+exec flock --shared /run/kai-runtime-update.lock node /opt/kai-bridge/fly/runtime-cli.mjs "$@"

package/fly/runtime-launch.mjs

@@ -0,0 +1,8 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { runtimeRoot } from './runtime-update.mjs';
+const entry = { bridge: 'start.mjs', 'codex-auth': 'codex-auth.mjs' }[process.argv[2]];
+if (!entry) throw new Error('Unknown hosted runtime service.');
+const root = process.env.KAI_RUNTIME_ROOT || runtimeRoot();
+process.env.KAI_RUNTIME_ROOT = root;
+await import(pathToFileURL(join(root, 'fly', entry)));

package/fly/runtime-update.mjs

@@ -0,0 +1,137 @@
+import { execFile } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { isNewer } from '../src/selfupdate.mjs';
+
+const exec = promisify(execFile);
+export const BASE_RUNTIME = '/opt/kai-bridge';
+export const RUNTIME_STORE = '/opt/kai-runtime';
+const CHANNEL = 'https://registry.npmjs.org/@gleapai/kai-bridge/hosted-stable';
+const DAY = 86400_000;
+const version = value => typeof value === 'string' && /^\d+\.\d+\.\d+$/.test(value);
+const read = path => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return {}; } };
+const packageAt = root => read(join(root, 'package.json'));
+export function browserVersion(root) {
+  const lock = read(join(root, existsSync(join(root, 'npm-shrinkwrap.json')) ? 'npm-shrinkwrap.json' : 'package-lock.json'));
+  return lock.packages?.['node_modules/playwright-core']?.version;
+}
+
+export function assertImageCompatibility(candidate, base) {
+  // Chromium is installed by the image, outside the replaceable runtime. Never
+  // activate a new Playwright revision against the old browser executable.
+  if (!browserVersion(candidate) || browserVersion(candidate) !== browserVersion(base)) {
+    throw Object.assign(new Error('This release needs a browser image update.'), { code: 'image_required' });
+  }
+}
+
+export function runtimeRoot(store = RUNTIME_STORE, base = BASE_RUNTIME) {
+  const state = read(join(store, 'state.json'));
+  const candidate = version(state.active) ? join(store, 'releases', state.active) : base;
+  return existsSync(join(candidate, 'package.json')) ? candidate : base;
+}
+
+function save(store, state) {
+  mkdirSync(store, { recursive: true });
+  const temporary = join(store, `state.${process.pid}.tmp`);
+  writeFileSync(temporary, JSON.stringify(state, null, 2) + '\n', { mode: 0o644 });
+  renameSync(temporary, join(store, 'state.json'));
+}
+
+export function supervisorRunning() {
+  const pid = Number(readFileText('/run/supervisord.pid'));
+  if (!Number.isSafeInteger(pid) || pid <= 1) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+const readFileText = path => { try { return readFileSync(path, 'utf8').trim(); } catch { return ''; } };
+
+export function requestRuntimeRollback(store = RUNTIME_STORE) {
+  const state = read(join(store, 'state.json'));
+  if (!state.active || !state.previousVersion) throw new Error('No previous runtime is available.');
+  writeFileSync(join(store, 'rollback-next-start'), '1\n', { mode: 0o600 });
+}
+
+export async function fetchHostedRelease() {
+  const response = await fetch(CHANNEL, { signal: AbortSignal.timeout(8000), headers: { accept: 'application/json' } });
+  if (response.status === 404) return null; // Channel has not been promoted yet.
+  if (!response.ok) throw new Error(`Release registry unavailable (${response.status}).`);
+  return response.json();
+}
+
+export async function installHostedRelease(release, destination, store, base = BASE_RUNTIME) {
+  mkdirSync(destination, { recursive: true });
+  const home = join(destination, '.install-home'); mkdirSync(home);
+  // No customer HOME, OAuth profiles, bootstrap token or npm login is inherited.
+  const env = { PATH: process.env.PATH, HOME: home, CI: '1', KAI_RUNTIME_UPDATE_CHECK: '1', npm_config_registry: 'https://registry.npmjs.org', npm_config_cache: join(store, 'cache') };
+  try {
+    const packed = await exec('npm', ['pack', `@gleapai/kai-bridge@${release.version}`, '--ignore-scripts', '--json', '--pack-destination', destination], { env, timeout: 30_000, maxBuffer: 1024 * 1024 });
+    const archive = JSON.parse(packed.stdout)?.[0]?.filename;
+    if (archive !== `gleapai-kai-bridge-${release.version}.tgz`) throw new Error('Unexpected runtime archive.');
+    await exec('tar', ['-xzf', join(destination, archive), '--strip-components=1', '-C', destination], { timeout: 10_000 });
+    const pkg = packageAt(destination), lock = read(join(destination, 'npm-shrinkwrap.json'));
+    if (pkg.name !== '@gleapai/kai-bridge' || pkg.version !== release.version || pkg.kaiHostedRuntime?.protocol !== 1 || lock.version !== pkg.version) throw new Error('Release lacks a matching locked runtime.');
+    assertImageCompatibility(destination, base);
+    await exec('npm', ['ci', '--ignore-scripts', '--omit=dev', '--no-audit', '--no-fund'], { cwd: destination, env, timeout: 60_000, maxBuffer: 1024 * 1024 });
+    await exec(process.execPath, [join(destination, 'scripts/runtime-smoke.mjs')], { cwd: destination, env, timeout: 45_000, maxBuffer: 1024 * 1024 });
+    rmSync(join(destination, archive), { force: true });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+}
+
+/** Called under flock BEFORE supervisord starts. Running VMs never hot-swap
+ * runtimes. Install/check failures and interrupted installs retain the old root. */
+export async function updateHostedRuntime({ store = RUNTIME_STORE, base = BASE_RUNTIME, now = Date.now(), busy = supervisorRunning(), enabled = true,
+  fetchRelease = fetchHostedRelease, install = installHostedRelease, log = message => process.stderr.write(`${message}\n`) } = {}) {
+  const current = runtimeRoot(store, base);
+  if (busy) return current;
+  const state = read(join(store, 'state.json'));
+  if (existsSync(join(store, 'rollback-next-start')) && state.active && state.previousVersion) {
+    save(store, { checkedAt: now, active: state.previous || null, failed: state.active, rolledBackAt: now });
+    rmSync(join(store, 'rollback-next-start'), { force: true });
+    log('Previous hosted runtime selected; the rejected release is quarantined.');
+    return runtimeRoot(store, base);
+  }
+  if (!enabled) return current;
+  if (state.checkedAt && now - state.checkedAt < DAY) return current;
+  state.checkedAt = now; save(store, state);
+  let release, staging;
+  try {
+    release = await fetchRelease();
+    if (!release || release.name !== '@gleapai/kai-bridge' || release.kaiHostedRuntime?.protocol !== 1 || !version(release.version)) return current;
+    if (!isNewer(release.version, packageAt(current).version) || state.failed === release.version) return current;
+    staging = join(store, 'releases', `.staging-${release.version}`);
+    rmSync(staging, { recursive: true, force: true });
+    await install(release, staging, store, base);
+    // Recheck admission boundary before activation, including manual invocation.
+    if (supervisorRunning()) throw new Error('Machine became busy during the update.');
+    const destination = join(store, 'releases', release.version);
+    rmSync(destination, { recursive: true, force: true });
+    renameSync(staging, destination);
+    save(store, { checkedAt: now, active: release.version, previous: state.active || null, previousVersion: packageAt(current).version, activatedAt: now });
+    // Keep one rollback bundle. User repositories and auth are outside this store.
+    try {
+      for (const entry of readdirSync(join(store, 'releases'))) {
+        if (version(entry) && entry !== release.version && entry !== state.active) rmSync(join(store, 'releases', entry), { recursive: true, force: true });
+      }
+      rmSync(join(store, 'cache'), { recursive: true, force: true });
+    } catch { /* Cleanup cannot invalidate an already-validated activation. */ }
+    log(`Hosted runtime ${release.version} validated and selected for this start.`);
+    return destination;
+  } catch (error) {
+    if (staging) rmSync(staging, { recursive: true, force: true });
+    save(store, { ...state, ...(release?.version && version(release.version) ? { failed: release.version } : {}), error: error.code === 'image_required' ? 'This release needs a browser image update; previous runtime retained.' : 'Runtime update failed; previous release retained.' });
+    log('Hosted runtime update failed; starting the previous release.');
+    return current;
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  if (process.argv.includes('--rollback-next-start')) {
+    requestRuntimeRollback(); process.stdout.write('Rollback scheduled. Stop and start the machine from Gleap to apply it.\n');
+  } else {
+  // stdout is consumed by the entrypoint: emit only the selected absolute path.
+  updateHostedRuntime({ enabled: process.env.KAI_HOSTED_RUNTIME_UPDATES !== '0' })
+    .then(root => process.stdout.write(`${root}\n`))
+    .catch(() => process.stdout.write(`${runtimeRoot()}\n`));
+  }
+}

package/fly/start.mjs

@@ -0,0 +1,7 @@
+import { bootstrapHosted } from '../src/hosted.mjs';
+import { BridgeDaemon } from '../src/daemon.mjs';
+await bootstrapHosted();
+const daemon = new BridgeDaemon();
+process.on('SIGTERM', () => { void daemon.stop(); });
+process.on('SIGINT', () => { void daemon.stop(); });
+await daemon.start();

package/fly/supervisord.conf

@@ -0,0 +1,45 @@
+[unix_http_server]
+file=/run/supervisor.sock
+chmod=0700
+[supervisord]
+nodaemon=true
+logfile=/data/logs/supervisor.log
+pidfile=/run/supervisord.pid
+[rpcinterface:supervisor]
+supervisor.rpcinterface_factory=supervisor.rpcinterface:make_main_rpcinterface
+[supervisorctl]
+serverurl=unix:///run/supervisor.sock
+[program:kai-bridge]
+command=node /opt/kai-bridge/fly/runtime-launch.mjs bridge
+user=kai
+environment=HOME="/data/home/kai",KAI_HOME="/data/home/kai/.kai",DISPLAY=":99"
+autorestart=unexpected
+stopasgroup=true
+killasgroup=true
+stdout_logfile=/data/logs/bridge.log
+stderr_logfile=/data/logs/bridge-error.log
+[program:codex-auth]
+command=node /opt/kai-bridge/fly/runtime-launch.mjs codex-auth
+user=kai
+environment=HOME="/data/home/kai",CODEX_HOME="/data/home/kai/.codex"
+autorestart=true
+stopasgroup=true
+stdout_logfile=/data/logs/codex-auth.log
+stderr_logfile=/data/logs/codex-auth-error.log
+[program:display]
+command=/usr/bin/Xvfb :99 -screen 0 1440x900x24 -nolisten tcp
+user=kai
+autorestart=true
+[program:desktop]
+command=/usr/bin/fluxbox
+user=kai
+environment=DISPLAY=":99",HOME="/data/home/kai"
+autorestart=true
+[program:vnc]
+command=/usr/bin/x11vnc -display :99 -localhost -forever -shared -nopw -rfbport 5900
+user=kai
+autorestart=true
+[program:browser-login]
+command=/usr/bin/websockify --web=/usr/share/novnc 127.0.0.1:6080 127.0.0.1:5900
+user=kai
+autorestart=true