@gleapai/kai-bridge 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gleapai/kai-bridge",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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",

package/runner/lib/acp/harnesses.mjs

@@ -56,6 +56,11 @@ export function pickSessionMode(preferred, available) {
 
 const OPENROUTER_BASE_URL = "https://openrouter.ai/api";
 
+// Backstop turn cap for gateway (non-native-Anthropic) claude-harness
+// runs when the host sends no explicit maxSteps — see the maxTurns spread
+// in the claude harness options below.
+const GATEWAY_FALLBACK_MAX_TURNS = 500;
+
 /**
  * Resolve the adapter binary: explicit override (`KAI_ACP_AGENT_CMD`,
  * JSON `{cmd, args}` — tests and the local bridge's per-profile
@@ -208,7 +213,17 @@ export const HARNESSES = {
           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 } : {}),
+          // Turn cap: explicit maxSteps wins; otherwise native Anthropic
+          // runs uncapped — maxBudgetUsd is the guard, and the CLI can
+          // price its own models. Gateway models get a generous backstop
+          // instead: the CLI prices unknown slugs at ~$0, so the budget
+          // never trips for them and turns are the only in-run guard
+          // that still bites.
+          ...(ctx.maxSteps
+            ? { maxTurns: ctx.maxSteps }
+            : isNativeAnthropic(ctx.model)
+              ? {}
+              : { maxTurns: GATEWAY_FALLBACK_MAX_TURNS }),
           ...(ctx.maxBudgetUsd ? { maxBudgetUsd: ctx.maxBudgetUsd } : {}),
           ...(ctx.additionalDirectories?.length ? { additionalDirectories: ctx.additionalDirectories } : {}),
           settings: {

package/runner/lib/contract.mjs

@@ -336,13 +336,6 @@ export function revertRepoMutations(workDir, baselines = null) {
 const SUPPORTED_FILE_PART_MIME_PREFIXES = ["image/"];
 const SUPPORTED_FILE_PART_MIMES = new Set(["application/pdf"]);
 
-// LEGACY: steps are no longer enforced as a turn limit — budget
-// (--max-budget-usd) is the sole cap (budget-only decision, 2026-06-18).
-// Retained only so `--max-steps` parsing stays backward-compatible
-// (Runner Contract v1); runners parse the value but ignore it for
-// enforcement. Safe to remove once no caller passes --max-steps.
-export const DEFAULT_STEP_CAP = 50;
-
 /**
  * Decode the full runner argv contract into one options object. All
  * flags are optional except `--task-b64`; callers fail fast on an
@@ -355,9 +348,11 @@ export const DEFAULT_STEP_CAP = 50;
  *   --effort <tier>                      low|medium|high|extra_high|max
  *   --session-id <id>                    resume an existing engine session/thread
  *   --max-budget-usd <number>            abort when accumulated cost exceeds
- *   --max-steps <number>                 LEGACY/no-op — steps no longer abort a
- *                                        turn; budget (--max-budget-usd) is the
- *                                        sole limit. Still parsed for compat.
+ *   --max-steps <number>                 explicit turn cap (SDK maxTurns) for
+ *                                        agents that want one; OMITTED = no
+ *                                        turn cap — budget (--max-budget-usd)
+ *                                        is the primary limit (budget-only
+ *                                        decision, 2026-06-18).
  *   --task-b64 <base64>                  REQUIRED — the user prompt
  *   --feedback-b64 <base64>              wrapped follow-up prompt for resumes
  *   --answers-b64 <base64-json>          string[][] question replies
@@ -378,11 +373,13 @@ export function parseRunnerArgs(rawArgs) {
 
   const agent = normalizeAgentName(argv.agent);
 
+  // No default: an absent --max-steps means NO turn cap (the harness then
+  // omits the SDK's maxTurns entirely). Budget/deadline are the real guards.
   const maxSteps = (() => {
     const raw = argv["max-steps"];
-    if (raw == null || raw === true) return DEFAULT_STEP_CAP;
+    if (raw == null || raw === true) return undefined;
     const n = Number(raw);
-    return Number.isFinite(n) && n > 0 ? n : DEFAULT_STEP_CAP;
+    return Number.isFinite(n) && n > 0 ? n : undefined;
   })();
 
   const maxBudgetUsd =

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, materializeBinding, sessionSlug, worktreePath } from "./workspace.mjs";
+import { collectChanges, commitAndPush, copyPrimaryEnvFiles, materializeBinding, sessionSlug, worktreePath, ensureCommitExcludes } from "./workspace.mjs";
 import { ServiceRunner, detectDevConfig, previewMcpServer, readDevConfig } from "./preview.mjs";
 import { describeHarnesses, installHarness } from "./harnesses.mjs";
 import { dirname } from "node:path";
@@ -444,6 +444,12 @@ export class BridgeDaemon {
         return this.previewStart(data);
       case "bridge.preview.stop":
         return this.previewStop(data);
+      case "bridge.preview.keepalive":
+        // Dashboard heartbeat while someone is actually LOOKING at the
+        // preview — makes the idle auto-stop mean real idleness instead
+        // of a fixed TTL since boot.
+        if (this.services.has(data.sessionId)) this.armPreviewIdleTimer(data.sessionId);
+        return;
       default:
         this.log("warn", "command.unknown", { name });
     }
@@ -488,7 +494,15 @@ export class BridgeDaemon {
           const copied = copyPrimaryEnvFiles(group.primary.path, cwd);
           if (copied.length) this.log("info", "preview.env.copied", { cwd, copied });
         }
-        const config = readDevConfig(cwd) ?? detectDevConfig(cwd);
+        // Config resolution order: this worktree's own config, then the
+        // PRIMARY checkout's (a repo verified by the setup agent has its
+        // dev.yaml on an unmerged config PR — session worktrees cut from
+        // the base branch don't carry it yet), then the package.json
+        // heuristic. Closes the verified-before-config-merge window.
+        const config =
+          readDevConfig(cwd) ??
+          (cwd !== group.primary.path ? readDevConfig(group.primary.path) : null) ??
+          detectDevConfig(cwd);
         if (!config) continue;
         if (config.error) {
           await report({ status: "error", error: config.error });
@@ -594,8 +608,8 @@ export class BridgeDaemon {
   /**
    * Previews are for looking at, not for hosting: stop everything after
    * 30 idle minutes (Lukas 08-26 — was 4h). Re-armed on every (re)start,
-   * cleared on manual stop and session close. Turn-path services are
-   * unaffected until a preview start adopts the same runner.
+   * cleared on manual stop and session close. Turns never boot services
+   * themselves — they only reuse this runner while it is alive.
    */
   armPreviewIdleTimer(sessionId) {
     this.previewIdleTimers ??= new Map();
@@ -628,7 +642,7 @@ export class BridgeDaemon {
     await this.api.sessionPreview(sessionId, { status: "stopped" }).catch((err) => this.log("warn", "preview.report.failed", { error: err.message }));
   }
 
-  /** One ServiceRunner per session, shared by the turn path and on-demand preview. */
+  /** One ServiceRunner per session — created only by the on-demand preview; turns reuse it. */
   runnerFor(sessionId, onStatus) {
     let runner = this.services.get(sessionId);
     if (!runner) {
@@ -678,11 +692,12 @@ export class BridgeDaemon {
       const workDir = bound[0]?.cwd;
       if (!workDir) throw new Error("Turn has no repositories.");
       const repoNote = bound.length > 1 ? `\n\nRepositories for this task:\n${bound.map((b) => `- ${b.key}: ${b.cwd}`).join("\n")}` : "";
-      // Preview tier A: start the repos' dev services (from .gleap/dev.yaml)
-      // once per session, tell the agent where they run, and hand it the
-      // Playwright MCP so it can verify in a real browser.
-      const previewNote = await this.startServices(turn, bound, batcher);
-      const mcpServers = previewNote ? [...(turn.mcpServers || []), previewMcpServer(RUNNER_DIR)] : turn.mcpServers;
+      // Previews are manual-only (dashboard "Start preview") — a turn
+      // never boots dev servers on its own. When the user already has a
+      // preview running for this session, describe it to the agent and
+      // hand it the Playwright MCP so it can verify in a real browser.
+      const { note: previewNote, hasLivePreview } = await this.describeLivePreview(turn, bound, batcher);
+      const mcpServers = hasLivePreview ? [...(turn.mcpServers || []), previewMcpServer(RUNNER_DIR)] : turn.mcpServers;
       const res = await runTurn({
         turn: { ...turn, task: `${turn.task}${repoNote}${previewNote}`, mcpServers },
         profile,
@@ -695,12 +710,17 @@ export class BridgeDaemon {
       await batcher.flush();
       const completed = !ctrl.signal.aborted && res.code === 0 && !res.rateLimited;
       const changes = bound.map((b) => {
+        ensureCommitExcludes(b.cwd, { allowDevConfig: !!turn.allowDevConfig });
         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.
         const shouldPush = completed && b.mode === "worktree" && !turn.planMode && diff.files.length > 0;
         const push = shouldPush
-          ? commitAndPush(b.cwd, { branch: b.branch, message: `${turn.title || "Kai Code changes"}\n\nSession ${turn.sessionId} · run on ${this.config.device?.name || "a paired device"}` })
+          ? commitAndPush(b.cwd, {
+              branch: b.branch,
+              allowDevConfig: !!turn.allowDevConfig,
+              message: `${turn.title || "Kai Code changes"}\n\nSession ${turn.sessionId} · run on ${this.config.device?.name || "a paired device"}`,
+            })
           : null;
         return { key: b.key, mode: b.mode, branch: b.branch, base: b.base, ...diff, push };
       });
@@ -738,17 +758,22 @@ export class BridgeDaemon {
     }
   }
 
-  /** Start/adopt dev services for the turn's repos; returns the prompt note ("" when no dev.yaml). */
-  async startServices(turn, bound, batcher) {
+  /**
+   * Turn-path preview policy: previews start MANUALLY only. A turn never
+   * boots dev servers — that surprised people ("Kai always starts a
+   * preview") and tied every turn to a heavyweight app boot. When a
+   * dashboard-started preview is already RUNNING for this session, reuse
+   * it: describe the live services to the agent (plus browser tools via
+   * the caller). Returns { note, hasLivePreview }.
+   */
+  async describeLivePreview(turn, bound, batcher) {
     const notes = [];
     const previews = [];
+    // Only a runner created by the dashboard's "Start preview" counts —
+    // the map is cleared on manual stop, idle stop, and session close.
+    const live = this.services.get(turn.sessionId);
     for (const b of bound) {
-      // Turn path starts ONLY committed .gleap/dev.yaml services — the
-      // package.json heuristic is reserved for the user-initiated
-      // "Start preview" (auto-booting every node repo's dev server on
-      // every turn would be a heavyweight surprise).
       const committed = readDevConfig(b.cwd);
-      const config = committed;
       if (!committed && !turn.planMode) {
         // Nudge the agent to make the setup durable once it has learned it.
         notes.push(
@@ -757,32 +782,31 @@ export class BridgeDaemon {
             `so Gleap can run live previews for this repo in future sessions.`,
         );
       }
-      if (!config) continue;
-      if (config.error) {
-        batcher.push({ type: "text", message: `⚠️ ${config.error}` });
+      if (!committed || !live) continue;
+      if (committed.error) {
+        batcher.push({ type: "text", message: `⚠️ ${committed.error}` });
         continue;
       }
-      const runner = this.runnerFor(turn.sessionId, (message) =>
-        batcher.push({ type: "tool_status", message, toolName: "DevServer", toolSummary: message, toolStatus: "completed", toolPartId: `svc-${Date.now()}` }),
-      );
       try {
-        const started = await runner.start(b.cwd, config, { mode: b.mode });
-        notes.push(runner.describeForAgent(started));
+        // start() on the live runner reuses already-running processes and
+        // their ports — for a booted preview this only describes it.
+        const started = await live.start(b.cwd, committed, { mode: b.mode });
+        notes.push(live.describeForAgent(started));
         if (started.preview) previews.push({ repo: b.key, ...started.preview });
       } catch (err) {
-        this.log("error", "services.start.failed", { repo: b.key, error: err.message });
-        batcher.push({ type: "text", message: `⚠️ Could not start dev services for ${b.key}: ${err.message}` });
+        this.log("error", "preview.reuse.failed", { repo: b.key, error: err.message });
+        batcher.push({ type: "text", message: `⚠️ Could not reuse the running preview for ${b.key}: ${err.message}` });
       }
     }
     if (previews.length > 0) {
-      // Session-keyed report (new servers) with the turn-keyed route as
-      // fallback for servers that predate it.
+      // Refresh the session-keyed report (URLs may have changed) with the
+      // turn-keyed route as fallback for servers that predate it.
       await this.api
         .sessionPreview(turn.sessionId, { status: "running", previews })
         .catch(() => this.api.turnPreview(turn.turnId, { previews }))
         .catch((err) => this.log("warn", "preview.report.failed", { error: err.message }));
     }
-    return notes.join("");
+    return { note: notes.join(""), hasLivePreview: previews.length > 0 };
   }
 
   async cloneRepo({ commandId, remote, name }) {

package/src/executor.mjs

@@ -20,7 +20,7 @@ const RUNNER = join(dirname(fileURLToPath(import.meta.url)), "..", "runner", "ac
 const b64 = (v) => Buffer.from(typeof v === "string" ? v : JSON.stringify(v), "utf8").toString("base64");
 
 /** turn.start payload → runner argv (no shell — we spawn node directly). */
-export function buildRunnerArgs(turn, workDir) {
+export function buildRunnerArgs(turn, workDir, profile) {
   const args = ["--task-b64", b64(turn.task || ""), "--work-dir", workDir];
   // The Server's coder payload signals plan mode as `planMode`, not as an
   // agent name (the analyzer host does this same mapping before spawning
@@ -37,8 +37,18 @@ export function buildRunnerArgs(turn, workDir) {
   // hint and mints its own ACP id).
   if (turn.acpSessionId || turn.sessionId) args.push("--session-id", turn.acpSessionId || turn.sessionId);
   if (turn.harness) args.push("--harness", turn.harness);
-  if (turn.maxSteps > 0) args.push("--max-steps", String(Math.floor(turn.maxSteps)));
-  if (turn.maxBudgetUsd > 0) args.push("--max-budget-usd", String(turn.maxBudgetUsd));
+  // BYO turns run uncapped: no --max-steps and no --max-budget-usd, even
+  // when the Server sends them — the work bills the operator's own harness
+  // subscription, so cost guards are the cloud's concern only. An absent
+  // --max-steps means no SDK maxTurns — a deep run must never die with
+  // "Reached maximum number of turns".
+  //
+  // The one exception is the `gleap-key` profile: there the Server hands
+  // the device GLEAP's API key (turn.credentials) and bills the org's AI
+  // credits, so the Server-computed wallet headroom must keep enforcing.
+  if (profile?.kind === "gleap-key" && turn.maxBudgetUsd > 0) {
+    args.push("--max-budget-usd", String(turn.maxBudgetUsd));
+  }
   if (turn.feedback) args.push("--feedback-b64", b64(turn.feedback));
   if (turn.questionAnswers?.length) args.push("--answers-b64", b64(turn.questionAnswers));
   if (turn.attachments?.length) args.push("--attachments-b64", b64(turn.attachments));
@@ -114,7 +124,7 @@ export function buildRunnerEnv(turn, profile, kaiHome = KAI_HOME) {
  */
 export function runTurn({ turn, profile, workDir, onEvent, onLog = () => {}, signal, kaiHome = KAI_HOME }) {
   return new Promise((resolve) => {
-    const args = buildRunnerArgs(turn, workDir);
+    const args = buildRunnerArgs(turn, workDir, profile);
     const env = buildRunnerEnv(turn, profile, kaiHome);
     const child = spawn(process.execPath, [RUNNER, ...args], { cwd: workDir, env, stdio: ["ignore", "pipe", "pipe"] });
     let result = null;

package/src/workspace.mjs

@@ -145,19 +145,47 @@ export function removeWorktree({ kaiHome, repo, sessionId, title }) {
  * A failed push is NOT fatal: the dashboard still shows the diff, and the
  * result carries the reason (no credentials, protected branch, …).
  */
-export function commitAndPush(cwd, { branch, message, allowEmpty = false } = {}) {
+/**
+ * Git-level guard rails for what a turn may publish. Agent state dirs
+ * never enter commits; the preview config (.gleap/dev.yaml) stays out
+ * of FEATURE commits too — agents write it to self-verify with a dev
+ * server mid-turn, and it kept riding along into unrelated PRs (08-26
+ * release E2E). Preview-setup turns pass allowDevConfig: there the
+ * file IS the deliverable. On-demand previews read it uncommitted, so
+ * excluding it breaks nothing. Run before BOTH collectChanges and the
+ * commit so the reported diff matches what actually ships.
+ */
+export function ensureCommitExcludes(cwd, { allowDevConfig = false } = {}) {
+  const always = [".codex-kai/", ".kai-acp-state/", ".kai-carry.patch"];
+  const devConfig = [".gleap/dev.yaml", ".gleap/dev.yml"];
+  try {
+    // Worktrees have a FILE at .git — resolve the real exclude path via
+    // git itself. (The old join(cwd, ".git", …) silently failed in
+    // worktrees, which is how dev.yaml slipped into feature commits in
+    // the first place.) info/exclude is SHARED across a repo's
+    // worktrees, so the dev-config lines are managed both ways: added
+    // for feature turns, removed again for allowDevConfig turns.
+    const excludePath = git(cwd, ["rev-parse", "--git-path", "info/exclude"]);
+    const absolute = excludePath.startsWith("/") ? excludePath : join(cwd, excludePath);
+    mkdirSync(dirname(absolute), { recursive: true });
+    const current = existsSync(absolute) ? readFileSync(absolute, "utf8") : "";
+    const kept = current
+      .split("\n")
+      .filter((line) => !devConfig.includes(line.trim()));
+    const wanted = [...always, ...(allowDevConfig ? [] : devConfig)];
+    const merged = [...kept.filter((l, i) => l.trim() !== "" || i < kept.length - 1)];
+    for (const e of wanted) if (!merged.some((l) => l.trim() === e)) merged.push(e);
+    const next = merged.join("\n").trimEnd() + "\n";
+    if (next !== current) writeFileSync(absolute, next);
+  } catch {
+    /* best-effort — a failed exclude write must never block the turn */
+  }
+}
+
+export function commitAndPush(cwd, { branch, message, allowEmpty = false, allowDevConfig = false } = {}) {
   const out = { committed: false, pushed: false, branch, commitSha: null, remote: null, error: null };
   try {
-    // Agent state dirs must never enter the commit.
-    const excludes = [".codex-kai/", ".kai-acp-state/", ".kai-carry.patch"];
-    const excludePath = join(cwd, ".git", "info", "exclude");
-    try {
-      const current = existsSync(excludePath) ? readFileSync(excludePath, "utf8") : "";
-      const missing = excludes.filter((e) => !current.includes(e));
-      if (missing.length) writeFileSync(excludePath, `${current.trimEnd()}\n${missing.join("\n")}\n`);
-    } catch {
-      /* worktree .git is a file → exclude lives in the main repo; fine */
-    }
+    ensureCommitExcludes(cwd, { allowDevConfig });
     git(cwd, ["add", "-A"]);
     const staged = git(cwd, ["diff", "--cached", "--name-only"]);
     if (staged || allowEmpty) {