@gleapai/kai-bridge 0.2.7 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gleapai/kai-bridge",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "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/acp-runner.mjs

@@ -116,6 +116,13 @@ const ASK_USER_MCP_PATH = process.env.KAI_ASK_USER_MCP_PATH || join(RUNNER_DIR,
 // todo tool at all. `todo_write` calls are folded onto the canonical
 // TodoWrite path by the mapper, which emits the dashboard `todos`
 // events either way.
+// Predicted next user prompt (Claude Code's composer ghost text).
+// The SDK generates it AFTER the turn's result on the warm prompt
+// cache (measured 1–3s behind the result); the runner holds the
+// process open for at most this long to pick it up. Only when the
+// harness can produce one — otherwise the turn ends as before.
+const PROMPT_SUGGESTION_WAIT_MS = Math.max(0, Number(process.env.KAI_PROMPT_SUGGESTION_WAIT_MS ?? 5000) || 0);
+const PROMPT_SUGGESTIONS_ENABLED = process.env.KAI_PROMPT_SUGGESTIONS !== "0" && PROMPT_SUGGESTION_WAIT_MS > 0;
 const TODO_SERVER_KEY = "kai_todos";
 const TODO_MCP_PATH = process.env.KAI_TODO_MCP_PATH || join(RUNNER_DIR, "tools", "todo-mcp.mjs");
 const TODO_NOTE =
@@ -615,6 +622,14 @@ async function main() {
   inFlight = false;
   stopHeartbeat?.();
 
+  // Start the suggestion wait NOW so it overlaps the transcript/usage
+  // work below; awaited just before the harness is torn down. Skipped
+  // when the turn ended abnormally or by a question / plan hand-off
+  // (the SDK suppresses suggestions there anyway).
+  const wantSuggestion =
+    PROMPT_SUGGESTIONS_ENABLED && !promptError && !cancelRequested && stopReason !== "refusal" && !!HARNESS.supportsPromptSuggestions?.(ctx);
+  const suggestionPromise = wantSuggestion ? mapper.waitForPromptSuggestion(PROMPT_SUGGESTION_WAIT_MS) : Promise.resolve(null);
+
   const finished = mapper.finish();
   if (IS_ARTIFACT_WRITER) {
     try {
@@ -664,6 +679,12 @@ async function main() {
     tracker.setProviderCostUsd(finished.usage.costUsd);
   }
 
+  const suggestionWaitStarted = Date.now();
+  const promptSuggestion = await suggestionPromise;
+  if (wantSuggestion) {
+    traceLog("prompt_suggestion", { received: !!promptSuggestion, waitedMs: Date.now() - suggestionWaitStarted });
+  }
+
   try {
     child.kill("SIGTERM");
   } catch {
@@ -691,6 +712,15 @@ async function main() {
   }
   const resultMessage = IS_PLAN_MODE && !finished.planEmitted && !finished.questionAsked ? finished.lastText : "";
   if (IS_PLAN_MODE && resultMessage) emit({ type: "plan", message: resultMessage });
+  // Before `result`: the host treats result as terminal, and the bridge
+  // relay answers 410 for events on an ended turn.
+  if (promptSuggestion) {
+    emit({
+      type: "prompt_suggestion",
+      message: promptSuggestion,
+      promptSuggestion: { text: promptSuggestion, source: "harness", harness: HARNESS_ID },
+    });
+  }
   emitSync(tracker.buildResultEvent({ message: resultMessage, sessionId: acpSessionId }));
   debugLog("done", { stopReason, cancelRequested, steps: usageRows.length });
   process.exit(0);

package/runner/lib/acp/harnesses.mjs

@@ -8,10 +8,11 @@
 // 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 { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 import { findClaudeTranscript, findCodexRollout, readClaudeTurnUsage, readCodexTurnUsage } from "./transcripts.mjs";
+import { isClaudeAcpPatched } from "../../tools/patch-claude-acp.mjs";
 
 export const HARNESS_IDS = ["claude", "codex", "cursor"];
 
@@ -103,6 +104,27 @@ function resolveAgentCommand(runnerDir, name, extraArgs = []) {
   return { cmd: name, args: [...extraArgs] };
 }
 
+/**
+ * Does the resolved claude-agent-acp build forward the SDK's
+ * `prompt_suggestion` (see tools/patch-claude-acp.mjs)? Upstream drops
+ * it, so the runner only waits for a suggestion when the marker is
+ * present — an unpatched adapter costs nothing but the feature.
+ */
+function claudeAdapterForwardsSuggestions(ctx) {
+  // Test hook: the conformance suite drives a scripted agent (no adapter
+  // build on disk) and asserts the suggestion path end to end.
+  if (process.env.KAI_PROMPT_SUGGESTIONS === "force") return true;
+  const { cmd } = resolveAgentCommand(ctx.runnerDir, "claude-agent-acp");
+  // `.bin/claude-agent-acp` → `<pkg>/dist/index.js`; acp-agent.js sits beside it.
+  let target = cmd;
+  try {
+    target = realpathSync(cmd);
+  } catch {
+    return false;
+  }
+  return isClaudeAcpPatched(join(dirname(target), "acp-agent.js"));
+}
+
 const tomlString = (v) => JSON.stringify(String(v ?? ""));
 const sanitizeMcpKey = (raw) => String(raw || "").replace(/[^a-zA-Z0-9_-]/g, "_");
 
@@ -224,6 +246,11 @@ export const HARNESSES = {
       claudeCode: {
         options: {
           model: ctx.engineModel || deriveEngineSlug(ctx.model),
+          // Predicted next user prompt after each turn (Claude Code's
+          // ghost text). Rides the turn's prompt cache, so ~free; the
+          // patched adapter forwards it, the runner emits it as a
+          // `prompt_suggestion` contract event.
+          promptSuggestions: true,
           // 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
@@ -259,6 +286,13 @@ export const HARNESSES = {
         },
       },
     }),
+    /**
+     * Can this harness hand back a predicted next prompt after a turn?
+     * Claude: the SDK generates one (suppressed in plan mode, after
+     * errors, near usage limits) and the patched adapter forwards it.
+     * Absent on codex/cursor — neither exposes anything comparable.
+     */
+    supportsPromptSuggestions: (ctx) => !ctx.isPlanMode && !ctx.isArtifactWriter && claudeAdapterForwardsSuggestions(ctx),
     /** 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. */

package/runner/lib/acp/mapper.mjs

@@ -223,6 +223,7 @@ function contentToValue(content) {
  * @param {boolean} opts.isPlanMode            plan agents hold prose for the result
  * @param {(reason: string) => void} opts.onTurnShouldEnd  question/plan asked → caller cancels the ACP turn
  * @param {(model: string, tokens: number, window?: number) => void} [opts.onContextSnapshot]
+ * @param {(text: string) => void} [opts.onPromptSuggestion] predicted next user prompt (harness-provided, arrives after the turn's result)
  */
 /**
  * Permission policy for `request_permission`: build mode allows everything
@@ -254,7 +255,7 @@ export function permissionPolicy({ isPlanMode = false, isArtifactWriter = false,
   };
 }
 
-export function createAcpMapper({ emit, isPlanMode = false, onTurnShouldEnd, onContextSnapshot, mcpServerIds = {}, readPlanFile = () => "", allowTool = () => true }) {
+export function createAcpMapper({ emit, isPlanMode = false, onTurnShouldEnd, onContextSnapshot, onPromptSuggestion, mcpServerIds = {}, readPlanFile = () => "", allowTool = () => true }) {
   /** toolCallId → { name, input, parent, emitted } */
   const tools = new Map();
   /** MCP server keys whose `connected` status already went out. */
@@ -284,6 +285,14 @@ export function createAcpMapper({ emit, isPlanMode = false, onTurnShouldEnd, onC
   let planEmitted = false;
   let lastPlanMarkdown = "";
   let lastUsage = null; // { used, size, costUsd }
+  /** Harness-predicted next user prompt (null until one arrives). */
+  let promptSuggestion = null;
+  /** Resolvers parked by waitForPromptSuggestion. */
+  const suggestionWaiters = [];
+  const settleSuggestion = (text) => {
+    promptSuggestion = text;
+    for (const resolve of suggestionWaiters.splice(0)) resolve(text);
+  };
 
   const flushThought = () => {
     const t = thoughtBuffer.trim();
@@ -497,12 +506,25 @@ export function createAcpMapper({ emit, isPlanMode = false, onTurnShouldEnd, onC
           }
           return;
         }
+        case "session_info_update": {
+          // Harness-agnostic extension point: an adapter that predicts
+          // the user's next prompt rides it in `_meta.kai.promptSuggestion`
+          // (claude-agent-acp via tools/patch-claude-acp.mjs today; a
+          // codex adapter could do the same tomorrow). Title/updatedAt
+          // stay ignored — the dashboard owns the session title.
+          const text = update._meta?.kai?.promptSuggestion;
+          if (typeof text === "string" && text.trim()) {
+            const clean = text.trim();
+            settleSuggestion(clean);
+            onPromptSuggestion?.(clean);
+          }
+          return;
+        }
         case "compaction_update":
         case "compaction_summary_chunk":
         case "current_mode_update":
         case "config_option_update":
         case "available_commands_update":
-        case "session_info_update":
         case "user_message_chunk":
         case "plan_update":
         case "plan_removed":
@@ -580,6 +602,28 @@ export function createAcpMapper({ emit, isPlanMode = false, onTurnShouldEnd, onC
       return true;
     },
 
+    /**
+     * The harness's predicted next prompt, or null once `timeoutMs`
+     * passes without one. The SDK emits it AFTER the turn's result (a
+     * background request on the warm cache), and emits nothing at all
+     * when it skips (plan mode, errors, usage limit) — hence the cap.
+     */
+    waitForPromptSuggestion(timeoutMs) {
+      if (promptSuggestion) return Promise.resolve(promptSuggestion);
+      return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          const i = suggestionWaiters.indexOf(settle);
+          if (i >= 0) suggestionWaiters.splice(i, 1);
+          resolve(null);
+        }, Math.max(0, Number(timeoutMs) || 0));
+        const settle = (text) => {
+          clearTimeout(timer);
+          resolve(text);
+        };
+        suggestionWaiters.push(settle);
+      });
+    },
+
     /** End-of-turn bookkeeping; returns what the runner needs for `result`. */
     finish() {
       flushThought();

package/runner/tools/patch-claude-acp.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// Patch `@agentclientprotocol/claude-agent-acp` so the Agent SDK's
+// `prompt_suggestion` message (the predicted next user prompt Claude
+// Code shows as ghost text in its own composer) reaches the runner.
+//
+// Upstream (≤ 0.75.1) drops the message on the floor — `case
+// "prompt_suggestion": break;` — because ACP has no update kind for it.
+// We forward it as a `session_info_update` carrying `_meta.kai
+// .promptSuggestion` (ACP's sanctioned extension point; the SDK's
+// zod schema allows an arbitrary `_meta` record), which the mapper
+// turns into the `prompt_suggestion` contract event.
+//
+// Idempotent and loud: re-running on a patched build is a no-op, a
+// build whose source drifted from the expected shape exits 2 so the
+// image bake / bridge install notices instead of silently shipping a
+// harness that never suggests. The runner itself detects the patch by
+// the `PATCH_MARKER` string, so an unpatched adapter costs nothing but
+// the feature.
+//
+//   node patch-claude-acp.mjs [<node_modules root>]
+//   node patch-claude-acp.mjs --file <path/to/acp-agent.js>
+//   node patch-claude-acp.mjs --check [...]      exit 0 patched / 1 not
+//
+// Default root: the runner's own `node_modules`, then one level up
+// (the kai-bridge package's `node_modules`) — the same lookup order
+// `resolveAgentCommand` uses to find the adapter binary.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PATCH_MARKER = "[gleap:prompt-suggestion]";
+
+const UNPATCHED = /case "tool_use_summary":\s*\n(\s*)case "prompt_suggestion":\s*\n\s*break;/;
+
+/** Apply the patch to the adapter source. Returns `{ source, status }`. */
+export function patchClaudeAcpSource(source) {
+  if (typeof source !== "string") return { source, status: "invalid" };
+  if (source.includes(PATCH_MARKER)) return { source, status: "already" };
+  const match = UNPATCHED.exec(source);
+  if (!match) return { source, status: "unrecognized" };
+  const indent = match[1];
+  const replacement = [
+    `case "tool_use_summary":`,
+    `${indent}    break;`,
+    `${indent}case "prompt_suggestion":`,
+    `${indent}    // ${PATCH_MARKER} Forward the SDK's predicted next prompt as a`,
+    `${indent}    // session_info_update; the Kai runner reads _meta.kai.promptSuggestion.`,
+    `${indent}    if (typeof message.suggestion === "string" && message.suggestion.trim()) {`,
+    `${indent}        await this.client.sessionUpdate({`,
+    `${indent}            sessionId: params.sessionId,`,
+    `${indent}            update: { sessionUpdate: "session_info_update", _meta: { kai: { promptSuggestion: message.suggestion } } },`,
+    `${indent}        });`,
+    `${indent}    }`,
+    `${indent}    break;`,
+  ].join("\n");
+  return { source: source.replace(UNPATCHED, replacement), status: "patched" };
+}
+
+/** Locate `dist/acp-agent.js` under a node_modules root. */
+export function resolveAdapterFile(root) {
+  return join(root, "@agentclientprotocol", "claude-agent-acp", "dist", "acp-agent.js");
+}
+
+/** True when the adapter at `file` forwards prompt suggestions. */
+export function isClaudeAcpPatched(file) {
+  try {
+    return readFileSync(file, "utf8").includes(PATCH_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+/** Patch the adapter on disk. Returns the status string. */
+export function patchClaudeAcpFile(file) {
+  if (!existsSync(file)) return "missing";
+  const before = readFileSync(file, "utf8");
+  const { source, status } = patchClaudeAcpSource(before);
+  if (status === "patched") writeFileSync(file, source);
+  return status;
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const argv = process.argv.slice(2);
+  const check = argv.includes("--check");
+  const fileIdx = argv.indexOf("--file");
+  let file = null;
+  if (fileIdx >= 0 && argv[fileIdx + 1]) {
+    file = resolve(argv[fileIdx + 1]);
+  } else {
+    const positional = argv.filter((a) => !a.startsWith("--"));
+    const runnerDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    const roots = positional.length > 0 ? positional.map((p) => resolve(p)) : [join(runnerDir, "node_modules"), join(runnerDir, "..", "node_modules")];
+    file = roots.map(resolveAdapterFile).find((f) => existsSync(f)) ?? resolveAdapterFile(roots[0]);
+  }
+  if (check) {
+    const ok = isClaudeAcpPatched(file);
+    console.log(`[patch-claude-acp] ${ok ? "patched" : "NOT patched"}: ${file}`);
+    process.exit(ok ? 0 : 1);
+  }
+  const status = patchClaudeAcpFile(file);
+  console.log(`[patch-claude-acp] ${status}: ${file}`);
+  if (status === "unrecognized" || status === "missing" || status === "invalid") process.exit(2);
+}

package/scripts/postinstall.mjs

@@ -8,6 +8,14 @@
 //
 // MUST never fail or block an install: CI, docker builds, and dependency
 // installs all run this too.
+// Forward Claude Code's prompt suggestions through the bundled adapter
+// (upstream drops them). Best-effort — see src/acp-patch.mjs.
+try {
+  const { ensureClaudeAcpPatched } = await import("../src/acp-patch.mjs");
+  ensureClaudeAcpPatched();
+} catch {
+  // The daemon retries on start; a missing patch only means no suggestions.
+}
 try {
   const interactive = process.stdin.isTTY && process.stdout.isTTY && !process.env.CI;
   const isGlobal = process.env.npm_config_global === "true";

package/src/acp-patch.mjs

@@ -0,0 +1,48 @@
+// Keep the bundled claude-agent-acp forwarding prompt suggestions.
+//
+// The Agent SDK predicts the user's next prompt after every turn; the
+// upstream adapter drops that message. The runner ships the patch
+// (runner/tools/patch-claude-acp.mjs) and applies it to the sandbox
+// image at bake time — on a device it has to be applied to THIS
+// package's node_modules instead, after every install (self-update
+// reinstalls the package) and, belt and braces, on daemon start. Always
+// best-effort: a read-only install just means no suggestions.
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+import { isClaudeAcpPatched, patchClaudeAcpFile } from "../runner/tools/patch-claude-acp.mjs";
+
+/** `dist/acp-agent.js` of the claude-agent-acp build this package resolves. */
+export function bundledClaudeAcpFile() {
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require.resolve("@agentclientprotocol/claude-agent-acp/package.json");
+    return join(dirname(pkg), "dist", "acp-agent.js");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Apply the patch if needed. Returns `{ file, status }` — status is
+ * `patched` | `already` | `missing` | `unrecognized` | `error`.
+ */
+export function ensureClaudeAcpPatched({ log } = {}) {
+  const file = bundledClaudeAcpFile();
+  if (!file) return { file: null, status: "missing" };
+  try {
+    const status = patchClaudeAcpFile(file);
+    if (status === "patched") log?.("info", "acp.patch.applied", { file });
+    else if (status !== "already") log?.("warn", "acp.patch.skipped", { file, status });
+    return { file, status };
+  } catch (err) {
+    log?.("warn", "acp.patch.failed", { file, error: err?.message ?? String(err) });
+    return { file, status: "error" };
+  }
+}
+
+/** True when the bundled adapter forwards prompt suggestions. */
+export function claudeAcpForwardsSuggestions() {
+  const file = bundledClaudeAcpFile();
+  return !!file && isClaudeAcpPatched(file);
+}

package/src/daemon.mjs

@@ -16,6 +16,7 @@ import { join, resolve as resolvePath } from "node:path";
 import { homedir, platform } from "node:os";
 
 import { BridgeApi, createEventBatcher } from "./api.mjs";
+import { ensureClaudeAcpPatched } from "./acp-patch.mjs";
 import { KAI_HOME, defaultConfig, loadConfig, saveConfig } from "./config.mjs";
 import { runTurn } from "./executor.mjs";
 import { createManagedProfile, describeProfiles, managedConfigDir, ambientConfigDir, openLoginTerminal, probeUsageLimits } from "./profiles.mjs";
@@ -155,6 +156,10 @@ export class BridgeDaemon {
     // worktree — interleaved events, racing pushes, mangled diffs. Very
     // easy to hit: `kai-bridge install` and then `kai-bridge start`.
     this.acquireLock();
+    // The bundled claude-agent-acp must forward prompt suggestions
+    // (postinstall applies the patch; a self-update or --ignore-scripts
+    // install can leave it unpatched). Idempotent, best-effort.
+    ensureClaudeAcpPatched({ log: (level, event, data) => this.log(level, event, data) });
     // A previous run that was killed (reboot, crash, `kill -9`) never got
     // to report its turns. Tell the server before doing anything else,
     // so those sessions settle instead of spinning.