@gleapai/kai-bridge 0.2.0

package/runner/tools/todo-mcp.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Minimal stdio MCP server exposing ONE tool: `todo_write` — the todo
+// bridge that stands in for Claude Code's native task tools. Zero
+// dependencies; speaks newline-delimited JSON-RPC 2.0 per the MCP
+// stdio transport (same skeleton as ask-user-mcp.mjs).
+//
+// Why it exists: the SDK's own task tools (TaskCreate/TaskUpdate — the
+// TodoWrite successors) drop out of resumed ACP sessions on BYO
+// machines (the CLI's deferred-tool reconciliation removes them on
+// every resume when the ambient claude.ai connector set is loaded), and
+// Codex never had a todo tool at all. This server gives every harness a
+// stable, schema'd todo tool; the runner's mapper folds its calls onto
+// the canonical TodoWrite handling and emits the dashboard's `todos`
+// events. The tool itself is a signalling no-op — the INPUT is the
+// product.
+
+import { createInterface } from "node:readline";
+
+const TOOL = {
+  name: "todo_write",
+  description:
+    "Publish your CURRENT task list to the user's dashboard. Pass the " +
+    "FULL updated list every time (not a delta) whenever you start, " +
+    "finish, or add a step. Use this to keep the user oriented during " +
+    "multi-step work.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      todos: {
+        type: "array",
+        minItems: 1,
+        items: {
+          type: "object",
+          properties: {
+            content: {
+              type: "string",
+              description: "Imperative description of the task.",
+            },
+            status: {
+              type: "string",
+              enum: ["pending", "in_progress", "completed"],
+              description: "Current state of this task.",
+            },
+            priority: {
+              type: "string",
+              enum: ["high", "medium", "low"],
+              description: "Optional priority.",
+            },
+          },
+          required: ["content", "status"],
+        },
+      },
+    },
+    required: ["todos"],
+  },
+};
+
+function send(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function reply(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+
+function replyError(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+const rl = createInterface({ input: process.stdin, terminal: false });
+rl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  let msg;
+  try {
+    msg = JSON.parse(trimmed);
+  } catch {
+    return;
+  }
+  const { id, method } = msg ?? {};
+  if (typeof method !== "string") return;
+
+  if (method === "initialize") {
+    reply(id, {
+      protocolVersion: msg.params?.protocolVersion ?? "2025-06-18",
+      capabilities: { tools: {} },
+      serverInfo: { name: "kai-todos", version: "1.0.0" },
+    });
+    return;
+  }
+  if (method === "notifications/initialized" || id == null) {
+    return; // notifications need no response
+  }
+  if (method === "tools/list") {
+    reply(id, { tools: [TOOL] });
+    return;
+  }
+  if (method === "tools/call") {
+    if (msg.params?.name !== TOOL.name) {
+      replyError(id, -32602, `unknown tool: ${msg.params?.name}`);
+      return;
+    }
+    const todos = msg.params?.arguments?.todos;
+    const count = Array.isArray(todos) ? todos.length : 0;
+    reply(id, {
+      content: [
+        {
+          type: "text",
+          text: `Todo list updated (${count} task${count === 1 ? "" : "s"}). Continue working.`,
+        },
+      ],
+    });
+    return;
+  }
+  replyError(id, -32601, `unknown method: ${method}`);
+});

package/scripts/postinstall.mjs

@@ -0,0 +1,24 @@
+// npm postinstall — hand off to the guided setup when a human can see it.
+//
+// npm ≥7 runs lifecycle scripts with stdio piped (nothing shows, stdin is
+// not a TTY), so in a normal `npm i -g` this exits silently and the user's
+// first `kai-bridge` runs the wizard instead. With `--foreground-scripts`
+// (or npm 6) stdio is inherited and the wizard starts right away —
+// re-running the install re-runs the setup, as intended.
+//
+// MUST never fail or block an install: CI, docker builds, and dependency
+// installs all run this too.
+try {
+  const interactive = process.stdin.isTTY && process.stdout.isTTY && !process.env.CI;
+  const isGlobal = process.env.npm_config_global === "true";
+  if (interactive && isGlobal) {
+    const { runSetup } = await import("../src/setup.mjs");
+    const { fileURLToPath } = await import("node:url");
+    const { join, dirname } = await import("node:path");
+    const binPath = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "kai-bridge.mjs");
+    await runSetup({ binPath });
+  }
+} catch {
+  // Setup can always be run later — never break `npm i`.
+}
+process.exit(0);

package/src/api.mjs

@@ -0,0 +1,141 @@
+// Thin REST client for the Gleap bridge endpoints (device-token auth).
+//
+//   POST   /gleapcode/bridge/pair/start            → { code, pollToken, url }   (no auth)
+//   POST   /gleapcode/bridge/pair/poll             → { status, device?, token? } (pollToken)
+//   PUT    /gleapcode/bridge/devices/me/hello      { name, platform, version, profiles, repos, roots }
+//   POST   /gleapcode/bridge/devices/me/heartbeat  { running: [turnIds] }
+//   POST   /gleapcode/bridge/turns/:id/events      { events: [contract lines] }
+//   POST   /gleapcode/bridge/turns/:id/result      { result, changes, status }
+//   POST   /users/me/pusher                        { socket_id, channel_name }   (channel auth)
+
+export class BridgeApi {
+  constructor({ apiBase, token, fetchImpl = fetch }) {
+    this.apiBase = String(apiBase).replace(/\/+$/, "");
+    this.token = token;
+    this.fetch = fetchImpl;
+  }
+
+  /**
+   * One HTTP call. Always time-bounded: a laptop that switches wifi or
+   * wakes onto a captive portal leaves sockets black-holed, and undici's
+   * default would park this await for five minutes — long enough to
+   * stall the event batcher and look like a hung turn.
+   */
+  async request(method, path, body, { auth = true, headers = {}, timeoutMs = 30_000 } = {}) {
+    const res = await this.fetch(`${this.apiBase}${path}`, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        ...(auth && this.token ? { authorization: `Bearer ${this.token}` } : {}),
+        ...headers,
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const text = await res.text();
+    let data = null;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      data = { raw: text };
+    }
+    if (!res.ok) {
+      const err = new Error(`${method} ${path} → ${res.status}: ${data?.message ?? data?.error ?? text.slice(0, 200)}`);
+      err.status = res.status;
+      err.data = data;
+      throw err;
+    }
+    return data;
+  }
+
+  /**
+   * Retry a report until it lands. Losing one of these is worse than
+   * being slow: a dropped `turnResult` leaves the session running
+   * forever, and a 5xx during a deploy is routine. 4xx (except 429) is
+   * permanent — a revoked token or an ended turn — so it stops there.
+   */
+  async requestWithRetry(method, path, body, { tries = 6, onRetry } = {}) {
+    let delay = 1_000;
+    for (let attempt = 1; ; attempt += 1) {
+      try {
+        return await this.request(method, path, body);
+      } catch (err) {
+        const permanent = err.status >= 400 && err.status < 500 && err.status !== 429;
+        if (permanent || attempt >= tries) throw err;
+        onRetry?.(err, attempt, delay);
+        await new Promise((r) => setTimeout(r, delay));
+        delay = Math.min(delay * 2, 30_000);
+      }
+    }
+  }
+
+  pairStart(device) {
+    return this.request("POST", "/gleapcode/bridge/pair/start", device, { auth: false });
+  }
+  pairPoll(pollToken) {
+    return this.request("POST", "/gleapcode/bridge/pair/poll", { pollToken }, { auth: false });
+  }
+  hello(payload) {
+    return this.request("PUT", "/gleapcode/bridge/devices/me/hello", payload);
+  }
+  /** Revoke THIS device's pairing (the CLI `logout`). */
+  logout() {
+    return this.request("POST", "/gleapcode/bridge/devices/me/logout", {});
+  }
+  heartbeat(payload) {
+    return this.request("POST", "/gleapcode/bridge/devices/me/heartbeat", payload);
+  }
+  turnEvents(turnId, events) {
+    return this.request("POST", `/gleapcode/bridge/turns/${encodeURIComponent(turnId)}/events`, { events });
+  }
+  turnPreview(turnId, payload) {
+    return this.request("POST", `/gleapcode/bridge/turns/${encodeURIComponent(turnId)}/preview`, payload);
+  }
+  /** Session-keyed preview report — works after every turn has ended
+   *  (on-demand Start/Stop preview from the dashboard). */
+  sessionPreview(sessionId, payload) {
+    return this.request("POST", `/gleapcode/bridge/sessions/${encodeURIComponent(sessionId)}/preview`, payload);
+  }
+  turnResult(turnId, payload, opts) {
+    return this.requestWithRetry(
+      "POST",
+      `/gleapcode/bridge/turns/${encodeURIComponent(turnId)}/result`,
+      payload,
+      opts
+    );
+  }
+
+  /** Turns the server still believes this device is running. */
+  pendingTurns() {
+    return this.request("GET", "/gleapcode/bridge/devices/me/pending");
+  }
+  commandAck(commandId, payload) {
+    return this.request("POST", `/gleapcode/bridge/commands/${encodeURIComponent(commandId)}/ack`, payload);
+  }
+}
+
+/** Batches contract events so a chatty turn doesn't POST per line. */
+export function createEventBatcher({ api, turnId, flushMs = 400, maxBatch = 50, onError = () => {} }) {
+  let queue = [];
+  let timer = null;
+  let inflight = Promise.resolve();
+  const flush = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (queue.length === 0) return inflight;
+    const batch = queue;
+    queue = [];
+    inflight = inflight.then(() => api.turnEvents(turnId, batch)).catch(onError);
+    return inflight;
+  };
+  return {
+    push(event) {
+      queue.push(event);
+      if (queue.length >= maxBatch) flush();
+      else if (!timer) timer = setTimeout(flush, flushMs);
+    },
+    flush,
+  };
+}

package/src/config.mjs

@@ -0,0 +1,76 @@
+// Bridge state on disk: `~/.kai/` (override with KAI_HOME).
+//
+//   config.json   — device identity + pairing token (mode 0600), API base,
+//                   scan roots, profiles, primary-checkout overrides,
+//                   per-repo last mode.
+//   accounts/     — managed harness profiles (see profiles.mjs)
+//   worktrees/    — session worktrees (see workspace.mjs)
+//   state/        — harness config dirs used by the ACP runner (transcripts)
+//   logs/         — daemon log
+//
+// The pairing token is the only secret the bridge stores; harness logins
+// stay inside the harnesses' own dirs and are never read or uploaded.
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, hostname, platform } from "node:os";
+import { join } from "node:path";
+
+export const KAI_HOME = process.env.KAI_HOME || join(homedir(), ".kai");
+export const CONFIG_PATH = join(KAI_HOME, "config.json");
+export const DEFAULT_API_BASE = process.env.KAI_API_BASE || "https://api.gleap.io/v3";
+export const DEFAULT_APP_BASE = process.env.KAI_APP_BASE || "https://app.gleap.io";
+export const DEFAULT_REALTIME = {
+  appKey: process.env.KAI_REALTIME_APP_KEY || "29b0a09928856b262405",
+  wsHost: process.env.KAI_SOCKUDO_HOST || "sockets.gleap.io",
+};
+
+export function defaultConfig() {
+  return {
+    version: 1,
+    apiBase: DEFAULT_API_BASE,
+    appBase: DEFAULT_APP_BASE,
+    realtime: DEFAULT_REALTIME,
+    device: null, // { id, name, token, organisationId, userId }
+    roots: [], // extra scan roots
+    profiles: [
+      { id: "claude-ambient", harness: "claude", kind: "ambient", label: "Claude (this machine)" },
+      { id: "codex-ambient", harness: "codex", kind: "ambient", label: "Codex (this machine)" },
+      { id: "cursor-ambient", harness: "cursor", kind: "ambient", label: "Cursor (this machine)" },
+    ],
+    primaryOverrides: {}, // repoKey → path
+    repoModes: {}, // repoKey → 'worktree' | 'local'
+  };
+}
+
+export function ensureHome() {
+  for (const d of ["", "accounts", "worktrees", "state", "logs"]) mkdirSync(join(KAI_HOME, d), { recursive: true });
+}
+
+export function loadConfig() {
+  ensureHome();
+  if (!existsSync(CONFIG_PATH)) return defaultConfig();
+  try {
+    const parsed = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+    return { ...defaultConfig(), ...parsed, realtime: { ...DEFAULT_REALTIME, ...(parsed.realtime || {}) } };
+  } catch {
+    return defaultConfig();
+  }
+}
+
+export function saveConfig(config, kaiHome = KAI_HOME) {
+  // Always write into the caller's home — a daemon constructed with an
+  // injected kaiHome (tests, embedded hosts) must never touch the real
+  // ~/.kai/config.json. (An e2e run once replaced a live pairing.)
+  mkdirSync(kaiHome, { recursive: true });
+  const path = join(kaiHome, "config.json");
+  writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    /* windows */
+  }
+}
+
+export function deviceDefaults() {
+  return { name: hostname().replace(/\.local$/, ""), platform: platform() };
+}