@gleapai/kai-bridge 0.2.0

package/runner/lib/acp/harnesses.mjs

@@ -0,0 +1,342 @@
+// Harness registry for the ACP runner.
+//
+// One entry per coding harness that speaks the Agent Client Protocol.
+// Each entry knows how to (1) spawn its ACP adapter, (2) build the env
+// that routes the model (native key, OpenRouter skin, limits), (3) shape
+// the `session/new` `_meta` that carries persona / permissions / resume,
+// and (4) read its own transcript for billing-grade usage after a turn.
+// Adding a harness = adding an entry here; the runner and the mapper
+// never branch on harness id.
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { findClaudeTranscript, findCodexRollout, readClaudeTurnUsage, readCodexTurnUsage } from "./transcripts.mjs";
+
+export const HARNESS_IDS = ["claude", "codex", "cursor"];
+
+/** Strip the registry namespace down to the engine's own model slug. */
+export function deriveEngineSlug(canonical) {
+  const id = String(canonical || "");
+  if (id.startsWith("anthropic/")) return id.slice("anthropic/".length);
+  if (id.startsWith("openai/")) return id.slice("openai/".length);
+  if (id.startsWith("openrouter/")) return id.slice("openrouter/".length);
+  if (id.startsWith("xai/")) return `x-ai/${id.slice("xai/".length)}`;
+  return id;
+}
+
+export function isNativeAnthropic(model) {
+  const id = String(model || "");
+  return id.startsWith("anthropic/") || !id.includes("/");
+}
+
+/**
+ * Pick the harness for a model when the host didn't say: `openai/*` →
+ * codex, everything else → claude (native Anthropic + the OpenRouter long
+ * tail, exactly today's `getCloudEngine` rule).
+ */
+export function resolveHarnessId(explicit, model) {
+  if (explicit && HARNESS_IDS.includes(explicit)) return explicit;
+  const id = String(model || "");
+  if (id.startsWith("openai/")) return "codex";
+  if (id.startsWith("cursor/")) return "cursor";
+  return "claude";
+}
+
+/**
+ * Pick the ACP session mode: the first of `preferred` the agent actually
+ * advertises (`session/new` → `modes.availableModes`); null when the
+ * agent advertises no modes (then `session/set_mode` is skipped).
+ */
+export function pickSessionMode(preferred, available) {
+  const ids = new Set((Array.isArray(available) ? available : []).map((m) => String(m?.id ?? m)));
+  if (ids.size === 0) return preferred[0] ?? null;
+  return preferred.find((id) => ids.has(id)) ?? null;
+}
+
+const OPENROUTER_BASE_URL = "https://openrouter.ai/api";
+
+/**
+ * Resolve the adapter binary: explicit override (`KAI_ACP_AGENT_CMD`,
+ * JSON `{cmd, args}` — tests and the local bridge's per-profile
+ * binaries), else the npm bin baked next to the runner, else PATH.
+ */
+function resolveAgentCommand(runnerDir, name, extraArgs = []) {
+  const override = process.env.KAI_ACP_AGENT_CMD;
+  if (override) {
+    try {
+      const parsed = JSON.parse(override);
+      if (parsed?.cmd) return { cmd: String(parsed.cmd), args: Array.isArray(parsed.args) ? parsed.args.map(String) : [] };
+    } catch {
+      return { cmd: override, args: [] };
+    }
+  }
+  // Baked next to the runner (/opt/gleap-runners/node_modules) or one
+  // level up (the bridge package's own node_modules); else PATH.
+  for (const dir of [join(runnerDir, "node_modules", ".bin"), join(runnerDir, "..", "node_modules", ".bin")]) {
+    const p = join(dir, name);
+    if (existsSync(p)) return { cmd: p, args: [...extraArgs] };
+  }
+  return { cmd: name, args: [...extraArgs] };
+}
+
+const tomlString = (v) => JSON.stringify(String(v ?? ""));
+const sanitizeMcpKey = (raw) => String(raw || "").replace(/[^a-zA-Z0-9_-]/g, "_");
+
+/**
+ * Codex: MCP servers + tool kill-switches live in `$CODEX_HOME/config.toml`,
+ * NOT in `session/new.mcpServers` — codex-acp replaces the `mcp_servers`
+ * config layer wholesale with the session list, and that list has no
+ * per-tool `disabled_tools`. The TOML mirrors the retired codex-runner.mjs
+ * (`default_tools_approval_mode`, startup/tool timeouts, engine-enforced
+ * `disabled_tools` for disabled + gated tools).
+ */
+export function buildCodexConfigToml(mcpServers) {
+  const lines = [
+    "# generated by acp-runner — do not edit",
+    "show_raw_agent_reasoning = true",
+    "[features]",
+    "collaboration_modes = true",
+  ];
+  for (const server of mcpServers || []) {
+    if (!server || typeof server !== "object") continue;
+    const key = sanitizeMcpKey(server.name || server.id);
+    if (!key) continue;
+    lines.push("", `[mcp_servers.${key}]`);
+    if (server.transport === "http" && server.url) {
+      lines.push(`url = ${tomlString(server.url)}`);
+      const headers = server.headers || {};
+      if (Object.keys(headers).length > 0) {
+        lines.push(`http_headers = { ${Object.entries(headers).map(([k, v]) => `${tomlString(k)} = ${tomlString(v)}`).join(", ")} }`);
+      }
+    } else if (server.command) {
+      lines.push(`command = ${tomlString(server.command)}`);
+      lines.push(`args = [${(Array.isArray(server.args) ? server.args : []).map(tomlString).join(", ")}]`);
+      const env = server.env || {};
+      if (Object.keys(env).length > 0) {
+        lines.push(`env = { ${Object.entries(env).map(([k, v]) => `${tomlString(k)} = ${tomlString(v)}`).join(", ")} }`);
+      }
+    } else {
+      lines.pop();
+      lines.pop();
+      continue;
+    }
+    lines.push("startup_timeout_sec = 60", "tool_timeout_sec = 60", 'default_tools_approval_mode = "approve"');
+    const disabled = [
+      ...(Array.isArray(server.disabledTools) ? server.disabledTools : []),
+      ...(Array.isArray(server.gatedTools) ? server.gatedTools : []),
+    ];
+    if (disabled.length > 0) lines.push(`disabled_tools = [${disabled.map(tomlString).join(", ")}]`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+export const HARNESSES = {
+  claude: {
+    id: "claude",
+    /** Which env var the adapter needs to be able to run at all. */
+    requiredEnv: (ctx) => (isNativeAnthropic(ctx.model) ? "ANTHROPIC_API_KEY" : "OPENROUTER_API_KEY"),
+    command: (ctx) => resolveAgentCommand(ctx.runnerDir, "claude-agent-acp"),
+    env: (ctx) => {
+      const env = { ...process.env };
+      const native = isNativeAnthropic(ctx.model);
+      const engineModel = ctx.engineModel || deriveEngineSlug(ctx.model);
+      // Isolated config dir per run: keeps the sandbox's ambient ~/.claude
+      // (settings, other sessions) out of the picture and gives the
+      // transcript a known location for usage collection. EXCEPT for an
+      // ambient BYO profile: macOS `claude` reads its OAuth from the
+      // keychain only while CLAUDE_CONFIG_DIR is unset, so the user's own
+      // login dir must be inherited, never exported (transcripts are still
+      // read from ctx.configDir — it IS the CLI's default dir then).
+      if (ctx.configDirAmbient) delete env.CLAUDE_CONFIG_DIR;
+      else env.CLAUDE_CONFIG_DIR = ctx.configDir;
+      env.ANTHROPIC_MODEL = engineModel;
+      if (native) {
+        delete env.ANTHROPIC_BASE_URL;
+        delete env.ANTHROPIC_AUTH_TOKEN;
+        // BYO login: the CLI's own OAuth in CLAUDE_CONFIG_DIR authenticates.
+        if (ctx.byoLogin) delete env.ANTHROPIC_API_KEY;
+      } else {
+        // OpenRouter's Anthropic-Messages skin. Same wiring as
+        // the retired claude-runner.mjs buildCliEnv (limits, background + subagent
+        // pins), minus the local capture proxy — see PARITY.md.
+        // Through the local wire proxy when the runner started one
+        // (provider pins / MiniMax / xAI shims / capture), else direct.
+        env.ANTHROPIC_BASE_URL = ctx.wireBaseUrl || OPENROUTER_BASE_URL;
+        env.ANTHROPIC_AUTH_TOKEN = env.OPENROUTER_API_KEY;
+        delete env.ANTHROPIC_API_KEY;
+        if (ctx.maxContextTokens) env.CLAUDE_CODE_MAX_CONTEXT_TOKENS = String(ctx.maxContextTokens);
+        if (ctx.maxOutputTokens) env.CLAUDE_CODE_MAX_OUTPUT_TOKENS = String(ctx.maxOutputTokens);
+        env.API_TIMEOUT_MS = env.API_TIMEOUT_MS || "1200000";
+        env.ANTHROPIC_DEFAULT_HAIKU_MODEL = ctx.backgroundModel
+          ? deriveEngineSlug(ctx.backgroundModel)
+          : engineModel;
+      }
+      const subagentWireMatches =
+        ctx.subagentModel && isNativeAnthropic(ctx.subagentModel) === native;
+      if (subagentWireMatches) env.CLAUDE_CODE_SUBAGENT_MODEL = deriveEngineSlug(ctx.subagentModel);
+      else if (!native) env.CLAUDE_CODE_SUBAGENT_MODEL = engineModel;
+      // The adapter never opens a browser in a sandbox; IS_SANDBOX lets it
+      // offer bypassPermissions even when the process happens to be root.
+      env.NO_BROWSER = "1";
+      env.IS_SANDBOX = env.IS_SANDBOX || "1";
+      return env;
+    },
+    /** Which MCP servers ride `session/new` (all of them for Claude). */
+    sessionMcpServers: (ctx, acpServers) => acpServers,
+    /** `session/new` `_meta` — persona + SDK options. */
+    sessionMeta: (ctx) => ({
+      systemPrompt: {
+        append: ctx.appendSystemPrompt,
+        // Drops the CLI's per-run dynamic sections (cwd listing, date …)
+        // so the cached prefix stays byte-stable across turns.
+        excludeDynamicSections: true,
+      },
+      claudeCode: {
+        options: {
+          model: ctx.engineModel || deriveEngineSlug(ctx.model),
+          // BYO inherits the user's OWN MCP world by design (their
+          // user-scope servers + claude.ai connectors, alongside the
+          // project's injected ones): it's their machine and only they
+          // can dispatch sessions to it — product call, Lukas 2026-08-25.
+          // Cloud sandboxes have no user scope, so cloud stays clean.
+          ...(ctx.effort ? { effort: ctx.effort } : {}),
+          ...(ctx.resumeSessionId ? { resume: ctx.resumeSessionId } : {}),
+          // plan → CLI plan gating; artifact writers → dontAsk + the
+          // `.kai/`-scoped allow rules (any other write auto-denied);
+          // build → bypass (the worktree is the boundary).
+          permissionMode: ctx.isPlanMode ? "plan" : ctx.isArtifactWriter ? "dontAsk" : "bypassPermissions",
+          ...(ctx.allowedTools?.length ? { allowedTools: ctx.allowedTools } : {}),
+          ...(ctx.disallowedTools?.length ? { disallowedTools: ctx.disallowedTools } : {}),
+          ...(ctx.maxSteps ? { maxTurns: ctx.maxSteps } : {}),
+          ...(ctx.maxBudgetUsd ? { maxBudgetUsd: ctx.maxBudgetUsd } : {}),
+          ...(ctx.additionalDirectories?.length ? { additionalDirectories: ctx.additionalDirectories } : {}),
+          settings: {
+            outputStyle: "Concise",
+            ...(ctx.plansDir ? { plansDirectory: ctx.plansDir } : {}),
+            ...(ctx.settings || {}),
+          },
+          ...(ctx.agents ? { agents: ctx.agents } : {}),
+        },
+      },
+    }),
+    /** ACP session modes to try, in order (`session/set_mode`) — the adapter's own ids. */
+    sessionModePreference: (ctx) => (ctx.isPlanMode ? ["plan"] : ctx.isArtifactWriter ? ["dontAsk", "plan"] : ["bypassPermissions", "acceptEdits", "default"]),
+    /** A prior turn's transcript on disk is what makes `resume` viable. */
+    hasResumableSession: (ctx) => !!findClaudeTranscript(ctx.configDir, ctx.workDir, ctx.resumeSessionId),
+    /** Billing-grade usage for the turn from the CLI's own transcript. */
+    collectTurnUsage: (ctx) =>
+      readClaudeTurnUsage({
+        configDir: ctx.configDir,
+        cwd: ctx.workDir,
+        sessionId: ctx.sessionId,
+        sinceTs: ctx.turnStartedAt,
+      }),
+    /** Canonical registry id for a transcript model string. */
+    canonicalModel: (ctx, raw) => {
+      const r = String(raw || "");
+      if (!r) return ctx.model;
+      const engine = ctx.engineModel || deriveEngineSlug(ctx.model);
+      // Transcripts echo the API's own id — the slug we sent, or its
+      // dated form (`claude-haiku-4-5-20251001`). Both are the model the
+      // host priced under `ctx.model`; anything else (a subagent on a
+      // different model) keeps its own canonical id.
+      if (r === engine || r.startsWith(`${engine}-`)) return ctx.model;
+      if (isNativeAnthropic(ctx.model)) return r.startsWith("anthropic/") ? r : `anthropic/${r}`;
+      return r;
+    },
+  },
+
+  codex: {
+    id: "codex",
+    requiredEnv: () => "OPENAI_API_KEY",
+    command: (ctx) => resolveAgentCommand(ctx.runnerDir, "codex-acp"),
+    env: (ctx) => {
+      const env = { ...process.env };
+      env.CODEX_HOME = ctx.configDir;
+      // Codex reads the key from auth.json, not the env (verified in
+      // the retired codex-runner.mjs ensureCodexHome); write the same file the
+      // `codex login --with-api-key` path produces. A BYO ChatGPT
+      // auth.json dropped in here is the bridge's subscription path.
+      mkdirSync(ctx.configDir, { recursive: true });
+      const authPath = join(ctx.configDir, "auth.json");
+      if (!ctx.byoLogin && !existsSync(authPath) && env.OPENAI_API_KEY) {
+        writeFileSync(authPath, JSON.stringify({ OPENAI_API_KEY: env.OPENAI_API_KEY }), { mode: 0o600 });
+      }
+      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));
+      env.NO_BROWSER = "1";
+      env.INITIAL_AGENT_MODE = ctx.isPlanMode ? "read-only" : "agent-full-access";
+      // Session config merged by the adapter: model + effort + our
+      // developer instructions (persona) via the instructions file.
+      const config = {
+        model: ctx.engineModel || deriveEngineSlug(ctx.model),
+        ...(ctx.effort ? { model_reasoning_effort: ctx.effort } : {}),
+        ...(ctx.instructionsPath ? { model_instructions_file: ctx.instructionsPath } : {}),
+        ...(ctx.maxContextTokens ? { model_context_window: ctx.maxContextTokens } : {}),
+      };
+      env.CODEX_CONFIG = JSON.stringify(config);
+      return env;
+    },
+    sessionMcpServers: () => [],
+    sessionMeta: () => ({}),
+    sessionModePreference: (ctx) => (ctx.isPlanMode || ctx.isArtifactWriter ? ["read-only"] : ["agent-full-access", "agent"]),
+    hasResumableSession: (ctx) => !!findCodexRollout(ctx.configDir, ctx.resumeSessionId),
+    collectTurnUsage: (ctx) =>
+      readCodexTurnUsage({
+        codexHome: ctx.configDir,
+        threadId: ctx.sessionId,
+        sinceTs: ctx.turnStartedAt,
+        model: ctx.engineModel || deriveEngineSlug(ctx.model),
+      }),
+    canonicalModel: (ctx, raw) => {
+      const r = String(raw || "");
+      const engine = ctx.engineModel || deriveEngineSlug(ctx.model);
+      if (!r || r === engine) return ctx.model;
+      return r.startsWith("openai/") ? r : `openai/${r}`;
+    },
+  },
+};
+
+HARNESSES.cursor = {
+  id: "cursor",
+  /**
+   * Cursor Agent CLI (`agent acp`, https://cursor.com/docs/cli). LOCAL ONLY:
+   * it runs on the user's Cursor login (or CURSOR_API_KEY); Gleap has no
+   * Cursor credentials, so the cloud never selects it. ACP v1 with
+   * loadSession + MCP over http/sse on session/new (probed 2026-08-23,
+   * build 2026.08.11). Binary is `cursor-agent` (legacy alias `agent`,
+   * which collides with other vendors' CLIs — resolve by explicit path).
+   */
+  requiredEnv: (ctx) => (ctx.byoLogin ? null : "CURSOR_API_KEY"),
+  command: (ctx) => resolveAgentCommand(ctx.runnerDir, "cursor-agent", ["acp"]),
+  env: () => {
+    const env = { ...process.env };
+    env.NO_OPEN_BROWSER = "1";
+    return env;
+  },
+  sessionMcpServers: (ctx, acpServers) => acpServers,
+  sessionMeta: () => ({}),
+  // Mode ids come from the session/new response; first match wins.
+  sessionModePreference: (ctx) => (ctx.isPlanMode || ctx.isArtifactWriter ? ["plan", "ask", "read-only"] : ["agent", "default"]),
+  /**
+   * No system-prompt channel over ACP and no per-profile config dir:
+   * the persona travels as a prefix of the first prompt instead.
+   */
+  promptPrefix: (ctx) => (ctx.resumeSessionId ? "" : ctx.appendSystemPrompt || ""),
+  /** No transcript with a per-request split — context comes from usage_update; BYO bills nothing. */
+  collectTurnUsage: () => ({ path: null, rows: [], contextWindow: null }),
+  canonicalModel: (ctx, raw) => {
+    const r = String(raw || "");
+    if (!r) return ctx.model;
+    return r.startsWith("cursor/") ? r : `cursor/${r}`;
+  },
+};
+
+export function getHarness(id) {
+  const h = HARNESSES[id];
+  if (!h) throw new Error(`acp-runner: unknown harness "${id}" (known: ${HARNESS_IDS.join(", ")})`);
+  return h;
+}