@gleapai/kai-bridge 0.2.6 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gleapai/kai-bridge",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "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.",
   "type": "module",
   "license": "MIT",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@agentclientprotocol/claude-agent-acp": "0.73.0",
-    "@agentclientprotocol/codex-acp": "1.8.0",
+    "@agentclientprotocol/codex-acp": "1.10.0",
     "@agentclientprotocol/sdk": "1.4.0",
     "@playwright/mcp": "^0.0.79",
     "@sockudo/client": "^2.0.0",

package/runner/acp-runner.mjs

@@ -39,8 +39,9 @@ import {
   startHeartbeat,
   traceLog,
 } from "./lib/contract.mjs";
-import { deriveEngineSlug, getHarness, isNativeAnthropic, pickSessionMode, resolveHarnessId } from "./lib/acp/harnesses.mjs";
+import { deriveEngineSlug, getHarness, isNativeAnthropic, pickSessionConfigOptions, pickSessionMode, resolveHarnessId } from "./lib/acp/harnesses.mjs";
 import { createAcpMapper, permissionPolicy } from "./lib/acp/mapper.mjs";
+import { describeProviderError, extractProviderError } from "./lib/acp/providerError.mjs";
 import { aggregateUsageRows, lastRootContextSnapshot } from "./lib/acp/transcripts.mjs";
 import { needsWireProxy, startWireProxy } from "./lib/wire-proxy.mjs";
 
@@ -145,6 +146,17 @@ const GATEWAY_PLAN_GUARD =
   `If you asked questions via the ${ASK_USER_TOOL_REF}, ` +
   "do NOT also finalise the plan in the same turn — wait for " +
   "the answers first.";
+// Harnesses without an enforced read-only plan mode (codex-acp's
+// "read-only" is a workspace-write sandbox that merely asks before
+// touching files OUTSIDE the workspace — found live 2026-09-06 when
+// Codex implemented the whole ticket during its plan turn). The prompt
+// has to carry the rule, and the bridge discards plan-turn edits.
+const READ_ONLY_PLAN_NOTE =
+  "PLAN MODE IS READ-ONLY. Do not create, edit or delete files and do " +
+  "not run commands that change the workspace (no installs, no " +
+  "formatters, no git writes) — nothing enforces this for you, and every " +
+  "change made during a plan turn is discarded before the build starts. " +
+  "Read, search and reason; then end your turn with the plan.";
 // Tool allow-lists (Claude permission rules). Plan mode and artifact
 // writers (kai-asker / researcher / documentarian: `.kai/` outputs only,
 // never repo edits) run under the CLI's own gating with these rules;
@@ -244,6 +256,7 @@ function buildAppendSystemPrompt() {
   }
   if (NEEDS_ASK_USER_MCP && !IS_ARTIFACT_WRITER) sections.push(GATEWAY_QUESTION_NOTE);
   if (IS_PLAN_MODE) sections.push(NEEDS_ASK_USER_MCP ? GATEWAY_PLAN_GUARD : PLAN_QUESTION_GUARD);
+  if (IS_PLAN_MODE && HARNESS_ID !== "claude") sections.push(READ_ONLY_PLAN_NOTE);
   if (!IS_PLAN_MODE) sections.push(GIT_HANDOFF_PROMPT);
   // After the safety guards (their leading position is load-bearing for
   // cursor's prompt-prefix mode) but before project instructions.
@@ -573,6 +586,15 @@ async function main() {
       traceLog("session.mode.failed", { modeId: desiredMode, error: String(err?.message ?? err) });
     }
   }
+  // Codex's native plan collaboration mode (see pickSessionConfigOptions).
+  for (const option of pickSessionConfigOptions(HARNESS_ID, ctx, sessionResponse.configOptions)) {
+    try {
+      await conn.setSessionConfigOption({ sessionId: acpSessionId, ...option });
+      traceLog("session.config", option);
+    } catch (err) {
+      traceLog("session.config.failed", { ...option, error: String(err?.message ?? err) });
+    }
+  }
 
   // Artifact writers must leave the repo untouched: snapshot before,
   // revert anything outside `.kai/` after (belt-and-braces under the
@@ -658,6 +680,15 @@ async function main() {
   if (stopReason === "refusal") {
     emit({ type: "error", message: "The model declined to continue (refusal)." });
   }
+  // A backend rejection codex-acp forwarded as text is a failed turn,
+  // not an answer — and never a plan (see providerError.mjs).
+  const providerError = cancelRequested ? null : extractProviderError(finished.lastText);
+  if (providerError) {
+    traceLog("provider.error", providerError);
+    emitSync({ type: "error", message: describeProviderError(providerError) });
+    emitSync(tracker.buildResultEvent({ sessionId: acpSessionId }));
+    process.exit(1);
+  }
   const resultMessage = IS_PLAN_MODE && !finished.planEmitted && !finished.questionAsked ? finished.lastText : "";
   if (IS_PLAN_MODE && resultMessage) emit({ type: "plan", message: resultMessage });
   emitSync(tracker.buildResultEvent({ message: resultMessage, sessionId: acpSessionId }));

package/runner/lib/acp/harnesses.mjs

@@ -48,6 +48,24 @@ export function resolveHarnessId(explicit, model) {
  * advertises (`session/new` → `modes.availableModes`); null when the
  * agent advertises no modes (then `session/set_mode` is skipped).
  */
+/**
+ * Session config options to set right after the mode. Codex has a NATIVE
+ * plan collaboration mode ("Plan before making changes") that codex-acp
+ * exposes as the `collaboration_mode` select option — the only real
+ * read-only plan mode Codex has: its ACP "read-only" mode is a
+ * workspace-write sandbox, and the prompt alone did not stop it from
+ * editing during a plan turn (2026-09-06). Empty when the agent does not
+ * advertise the option (older codex-acp, other harnesses).
+ */
+export function pickSessionConfigOptions(harnessId, ctx, configOptions) {
+  if (harnessId !== "codex" || !ctx?.isPlanMode) return [];
+  const option = (Array.isArray(configOptions) ? configOptions : []).find((o) => o?.id === "collaboration_mode");
+  if (!option) return [];
+  const values = (Array.isArray(option.options) ? option.options : []).map((o) => String(o?.value ?? o));
+  if (!values.includes("plan")) return [];
+  return option.currentValue === "plan" ? [] : [{ configId: "collaboration_mode", value: "plan" }];
+}
+
 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;
@@ -102,6 +120,12 @@ export function buildCodexConfigToml(mcpServers) {
     "show_raw_agent_reasoning = true",
     "[features]",
     "collaboration_modes = true",
+    // The user's ChatGPT connectors ("apps") stay out of Kai sessions:
+    // a bridge turn runs under the teammate's own ChatGPT login, and
+    // with apps on, Codex reached the Gleap connector of that account —
+    // tools the session's MCP config had disabled (draft_reply_to_composer
+    // landed in the composer through it; found live 2026-09-06).
+    "apps = false",
   ];
   for (const server of mcpServers || []) {
     if (!server || typeof server !== "object") continue;

package/runner/lib/acp/mapper.mjs

@@ -66,6 +66,21 @@ export function toolNameFromUpdate(update) {
   return "Tool";
 }
 
+/**
+ * codex-acp's post-plan permission request ("Implement this plan?", kind
+ * switch_mode, `_meta.codex.kind: "plan_review"`, the plan in
+ * `rawInput.plan`) → the plan markdown; null for every other request.
+ */
+export function planReviewText(params) {
+  const toolCall = params?.toolCall ?? {};
+  const isPlanReview =
+    params?._meta?.codex?.kind === "plan_review" ||
+    (toolCall.kind === "switch_mode" && /implement this plan/i.test(String(toolCall.title ?? "")));
+  if (!isPlanReview) return null;
+  const plan = toolCall.rawInput?.plan;
+  return typeof plan === "string" ? plan.trim() : "";
+}
+
 /** Normalise adapter-specific raw inputs into the shapes summarizeTool knows. */
 export function normalizeToolInput(name, update) {
   const raw = update?.rawInput;
@@ -507,9 +522,26 @@ export function createAcpMapper({ emit, isPlanMode = false, onTurnShouldEnd, onC
       const toolCall = params?.toolCall ?? {};
       const name = toolNameFromUpdate(toolCall);
       const input = toolCall.rawInput ?? null;
-      if (handleTurnEndingTool(name, input)) return null;
       const options = Array.isArray(params?.options) ? params.options : [];
       const pick = (kind) => options.find((o) => o?.kind === kind)?.optionId;
+      // Codex's native plan mode ends with "Implement this plan?" — and
+      // codex-acp asks the CLIENT: a "yes" switches to default mode and
+      // runs the implementation inside the same prompt. We auto-allowed
+      // it like any unknown permission, so Codex implemented during plan
+      // turns (2026-09-06). Gleap owns that question (the dashboard's plan
+      // card): capture the plan, end the turn, answer no.
+      const planReview = isPlanMode ? planReviewText(params) : null;
+      if (planReview !== null) {
+        if (!planEmitted) {
+          planEmitted = true;
+          flushThought();
+          flushText();
+          emit({ type: "plan", message: planReview || lastText });
+        }
+        onTurnShouldEnd?.("plan");
+        return pick("reject_once") ?? pick("reject_always") ?? "__reject__";
+      }
+      if (handleTurnEndingTool(name, input)) return null;
       if (!allowTool(name, input)) {
         emit({
           type: "tool_status",

package/runner/lib/acp/providerError.mjs

@@ -0,0 +1,83 @@
+// A backend rejection the ACP adapter forwarded as prose.
+//
+// codex-acp streams a non-retryable app-server error (an HTTP 4xx from
+// the Responses API: unknown model, bad request, model gated behind a
+// newer CLI) as a plain agent text chunk — `${message}\n\n`, where
+// `message` is the raw JSON envelope — and then ends the turn normally.
+// Without this the runner took that text for the agent's answer; in
+// plan mode it BECAME the plan and the dashboard asked "Implement this
+// plan?" over `{"type":"error","status":400,…}` (found live 2026-09-06:
+// gpt-6-astra on a bundled Codex CLI too old for it).
+
+/**
+ * The provider error hidden in the agent's final text, or `null` when
+ * the text is a real answer. Only the LAST paragraph decides: the CLI's
+ * own "Warning: …" lines ride ahead of the envelope, while an error the
+ * agent quoted and then worked past is still an answer.
+ */
+export function extractProviderError(text) {
+  if (typeof text !== "string" || !text.trim()) return null;
+  const paragraphs = text.trim().split(/\n\s*\n/);
+  const candidate = paragraphs[paragraphs.length - 1].trim();
+  if (!candidate.startsWith("{") || !candidate.endsWith("}")) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(candidate);
+  } catch {
+    return null; // prose that happens to sit in braces
+  }
+  if (!parsed || typeof parsed !== "object" || parsed.type !== "error")
+    return null;
+  const inner =
+    parsed.error && typeof parsed.error === "object" ? parsed.error : parsed;
+  const message =
+    typeof inner.message === "string" && inner.message.trim()
+      ? inner.message.trim()
+      : candidate;
+  const status = Number.isInteger(parsed.status)
+    ? parsed.status
+    : Number.isInteger(inner.status)
+      ? inner.status
+      : null;
+  const code =
+    inner !== parsed && typeof inner.type === "string"
+      ? inner.type
+      : typeof inner.code === "string"
+        ? inner.code
+        : null;
+  return { message, status, code };
+}
+
+/**
+ * What the teammate can DO about it. The provider's own text is written
+ * for people running the CLI by hand ("upgrade the latest app or CLI") —
+ * on a paired machine the CLI is bundled with Kai Bridge, so the fix is
+ * the bridge, not Codex. Null when there is no known remedy.
+ */
+export function adviseProviderError(error) {
+  const text = `${error.message} ${error.code ?? ""}`;
+  if (/newer version of codex|upgrade .*(app|cli)/i.test(text)) {
+    return (
+      "This model needs a newer Codex than the one bundled with Kai Bridge on this machine. " +
+      "Kai Bridge updates itself when idle (0.2.6 and later) — give it a few minutes and retry, " +
+      "or run `npm i -g @gleapai/kai-bridge@latest` there. Or pick a model from this machine's list."
+    );
+  }
+  if (error.status === 401 || /unauthori[sz]ed|not logged in|login required|invalid.*(token|api key)/i.test(text)) {
+    return "The Codex login on this machine has expired — run `kai-bridge login` there, then retry.";
+  }
+  if (error.status === 404 || /model.*(not found|does not exist|unknown|unsupported)|unknown model/i.test(text)) {
+    return "This machine's Codex does not know that model — pick one from this machine's list.";
+  }
+  if (error.status === 429 || /rate limit|too many requests|usage limit/i.test(text)) {
+    return "The ChatGPT account on this machine is rate-limited — wait for the window to reset or run in Gleap Cloud.";
+  }
+  return null;
+}
+
+/** One line for the dashboard's failed-turn row: what happened, then what to do. */
+export function describeProviderError(error) {
+  const where = error.status ? ` (HTTP ${error.status})` : "";
+  const advice = adviseProviderError(error);
+  return `The model provider rejected the request${where}: ${error.message}${advice ? ` ${advice}` : ""}`;
+}

package/src/daemon.mjs

@@ -20,7 +20,7 @@ import { KAI_HOME, defaultConfig, loadConfig, saveConfig } from "./config.mjs";
 import { runTurn } from "./executor.mjs";
 import { createManagedProfile, describeProfiles, managedConfigDir, ambientConfigDir, openLoginTerminal, probeUsageLimits } from "./profiles.mjs";
 import { defaultRoots, groupByRepo, preferredCloneRoot, scanRoots, toDeviceRepoReport } from "./repos.mjs";
-import { collectChanges, commitAndPush, copyPrimaryEnvFiles, currentBranch, materializeBinding, sessionSlug, worktreePath, ensureCommitExcludes } from "./workspace.mjs";
+import { discardChanges, collectChanges, commitAndPush, copyPrimaryEnvFiles, currentBranch, materializeBinding, sessionSlug, worktreePath, ensureCommitExcludes } from "./workspace.mjs";
 import { ServiceRunner, detectDevConfig, previewMcpServer, readDevConfig } from "./preview.mjs";
 import { describeHarnesses, installHarness, probeHarnessAuth } from "./harnesses.mjs";
 import { probeHarnessModels } from "./models.mjs";
@@ -925,6 +925,21 @@ export class BridgeDaemon {
       const completed = !ctrl.signal.aborted && res.code === 0 && !res.rateLimited;
       const changes = [...bound, ...this.adoptSessionWorktrees(turn, bound)].map((b) => {
         ensureCommitExcludes(b.cwd, { allowDevConfig: !!turn.allowDevConfig });
+        // A plan turn must leave the worktree as it found it — see
+        // discardChanges. Local checkouts are the user's; only report.
+        if (turn.planMode) {
+          const leaked = b.mode === "worktree" ? discardChanges(b.cwd).discarded : collectChanges(b.cwd).files;
+          if (leaked.length > 0) {
+            this.log("warn", "plan.changes", { turnId, repo: b.key, mode: b.mode, files: leaked.length, discarded: b.mode === "worktree" });
+            batcher.push({
+              type: "text",
+              message:
+                b.mode === "worktree"
+                  ? `Plan mode is read-only — ${leaked.length} file change${leaked.length === 1 ? "" : "s"} made during planning ${leaked.length === 1 ? "was" : "were"} discarded; the build starts from the plan.`
+                  : `Plan mode is read-only, but ${leaked.length} file change${leaked.length === 1 ? "" : "s"} landed in your local checkout of ${b.key} — review them before building.`,
+            });
+          }
+        }
         const diff = collectChanges(b.cwd);
         // Build turns in worktree mode publish the session branch so the
         // Server can open the PR; plan turns and local mode never push.
@@ -940,6 +955,10 @@ export class BridgeDaemon {
         // work that stayed on this machine (files but no push).
         return { key: b.key, mode: b.mode, branch: b.branch, base: b.base, cwd: b.cwd, adopted: b.adopted || undefined, ...diff, push };
       });
+      // The plan-mode notices above were queued AFTER the post-turn
+      // flush; land them before the result closes the turn (the Server
+      // answers 410 for events on an ended turn).
+      await batcher.flush();
       // Built OUTSIDE the report call: if posting the result throws, the
       // catch below must not turn a finished turn into a failed one. The
       // work is already committed and pushed at this point.
@@ -996,7 +1015,9 @@ export class BridgeDaemon {
         notes.push(
           `\n\nNo .gleap/dev.yaml found in ${b.key}. If you figure out how this project's dev server runs, ` +
             `write .gleap/dev.yaml (services: { <name>: { cwd, run, port, health } }, preview: <name>) ` +
-            `so Gleap can run live previews for this repo in future sessions.`,
+            `so Gleap can run live previews for this repo in future sessions. This is optional housekeeping ` +
+            `for Gleap, not part of the task: it is committed separately, so never count it as work the user asked for ` +
+            `or mention it in your summary.`,
         );
       }
       if (!committed || !live) continue;

package/src/models.mjs

@@ -11,18 +11,23 @@
 //            (subscription tier, `availableModels` allowlist, gateway
 //            settings all applied by the CLI itself). Spawns the CLI
 //            (~2s), so never on hello's path — see the daemon's refresh.
-//   codex  — `<CODEX_HOME>/models_cache.json`, the model catalogue the
-//            Codex CLI fetches for the signed-in ChatGPT account. No
-//            spawn, plain file read.
+//   codex  — `codex debug models` from the BUNDLED CLI: the catalogue the
+//            backend serves for THIS client version under the signed-in
+//            ChatGPT account (spawns the CLI, ~1-2s). The profile's
+//            models_cache.json is only the fallback — another Codex (the
+//            ChatGPT app, a newer global CLI) writes it and lists models
+//            the bundled CLI cannot run yet.
 //   cursor — no catalogue surface; the dashboard keeps its static list.
 //
 // Ids are namespaced exactly like the Server's registry (`anthropic/…`,
 // `openai/…`) so the harness derivation, the BYO gate and the runner's
 // engine-slug derivation all keep working unchanged.
 
-import { existsSync, readFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { promisify } from "node:util";
 import { harnessBinary } from "./harnesses.mjs";
 import { ambientConfigDir } from "./profiles.mjs";
 
@@ -168,7 +173,56 @@ export async function probeClaudeModels(configDir, kaiHome = process.env.KAI_HOM
   }
 }
 
-export function probeCodexModels(configDir) {
+const execFileAsync = promisify(execFile);
+
+/**
+ * Where the Codex catalogue probe runs. `codex debug models` needs a
+ * login, and CODEX_HOME must never be the user's real ~/.codex (the CLI
+ * writes its own cache + config there) — so a scratch home under
+ * ~/.kai/state seeded with a COPY of the profile's auth.json, the same
+ * rule the executor applies for turns.
+ */
+export function codexProbeHome(configDir, kaiHome) {
+  const home = join(kaiHome, "state", "models-probe", "codex");
+  mkdirSync(home, { recursive: true });
+  const auth = join(configDir, "auth.json");
+  if (existsSync(auth)) copyFileSync(auth, join(home, "auth.json"));
+  return home;
+}
+
+/**
+ * The bundled CLI's OWN catalogue: `codex debug models` renders the
+ * list the backend serves for THIS client version. The profile's
+ * models_cache.json is written by whichever Codex the user runs (the
+ * ChatGPT app, a newer global CLI) and can list models the bundled CLI
+ * cannot run yet — found live 2026-09-06: the picker offered
+ * gpt-6-astra, the turn died with "requires a newer version of Codex".
+ * `null` = the CLI could not answer (missing, signed out, timeout).
+ */
+export async function codexModelsFromCli(configDir, kaiHome, { timeoutMs = 30_000, exec = execFileAsync } = {}) {
+  const bin = harnessBinary("codex", kaiHome);
+  if (!bin) return null;
+  const env = { ...process.env, CODEX_HOME: codexProbeHome(configDir, kaiHome) };
+  delete env.OPENAI_API_KEY;
+  const { stdout } = await exec(bin, ["debug", "models"], { env, cwd: kaiHome, timeout: timeoutMs, maxBuffer: 32 * 1024 * 1024 });
+  const parsed = JSON.parse(String(stdout));
+  const rows = codexModelsFromCache(parsed);
+  return rows.length ? rows : null;
+}
+
+/**
+ * Codex models under a login: the bundled CLI's own answer first, the
+ * profile's cache file only when the CLI cannot answer — never a list
+ * the CLI would then reject.
+ */
+export async function probeCodexModels(configDir, kaiHome = process.env.KAI_HOME || join(HOME, ".kai"), opts = {}) {
+  let fromCli = null;
+  try {
+    fromCli = await codexModelsFromCli(configDir, kaiHome, opts);
+  } catch {
+    fromCli = null;
+  }
+  if (fromCli) return fromCli;
   const cache = readCodexModelsCache(configDir);
   return cache ? codexModelsFromCache(cache) : null;
 }
@@ -181,6 +235,6 @@ export function probeCodexModels(configDir) {
  */
 export async function probeHarnessModels(harness, configDir, kaiHome, opts) {
   if (harness === "claude") return probeClaudeModels(configDir, kaiHome, opts);
-  if (harness === "codex") return probeCodexModels(configDir);
+  if (harness === "codex") return probeCodexModels(configDir, kaiHome, opts);
   return null;
 }

package/src/workspace.mjs

@@ -118,7 +118,12 @@ export function currentBranch(cwd) {
 
 /** Diff of what the turn changed (for the dashboard's file-changes panel). */
 export function collectChanges(cwd) {
-  const status = git(cwd, ["status", "--porcelain"]);
+  // NOT via git(): its trailing .trim() also strips the LEADING space of
+  // the first porcelain line, so a first entry that is a tracked
+  // modification (" M path") lost its space and every field shifted one
+  // char left — the file list reported to the Server read "EADME.md"
+  // (found 2026-09-06). Read raw; porcelain columns are fixed-width.
+  const status = execFileSync("git", ["status", "--porcelain"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
   const files = status
     .split("\n")
     .filter(Boolean)
@@ -127,6 +132,25 @@ export function collectChanges(cwd) {
   return { files, diff };
 }
 
+/**
+ * Throw away everything a turn left uncommitted — tracked edits and new
+ * files alike (ignored files stay: node_modules, .env copies). Plan
+ * turns are read-only by contract, but not every harness enforces it:
+ * codex-acp's "read-only" mode is a workspace-write sandbox that only
+ * asks before touching files OUTSIDE the workspace, and Codex went on to
+ * implement a whole ticket during its plan turn (2026-09-06). Whatever a
+ * plan turn changed is discarded here so the build turn starts from the
+ * base, exactly as the plan promised. Worktree mode only — a `local`
+ * binding is the user's own checkout and is never reset.
+ */
+export function discardChanges(cwd) {
+  const before = collectChanges(cwd).files;
+  if (before.length === 0) return { discarded: [] };
+  git(cwd, ["checkout", "--", "."]);
+  git(cwd, ["clean", "-fd"]);
+  return { discarded: before };
+}
+
 /** Drop a session's worktrees (after merge/close). */
 export function removeWorktree({ kaiHome, repo, sessionId, title }) {
   const dir = worktreePath(kaiHome, repo.name, sessionSlug(sessionId, title));