@gleapai/kai-bridge 0.2.0

package/runner/lib/acp/mapper.mjs

@@ -0,0 +1,575 @@
+// ACP → runner-contract mapper.
+//
+// Turns Agent Client Protocol `session/update` notifications (and the
+// permission requests an agent raises mid-turn) into the exact JSONL
+// events the analyzer host already consumes (`parseContractOutputLine`
+// in src/coder/agents/contract.ts): thinking / text / tool_status /
+// todos / question / plan / result / error. Harness-agnostic by design:
+// anything that speaks ACP (claude-agent-acp, codex-acp, gemini, opencode,
+// …) produces the same timeline. Harness-specific details — the real
+// tool name behind a call, subagent parentage — are read from the
+// namespaced `_meta` the adapters attach, with graceful fallbacks to
+// ACP's generic `kind`/`title`.
+//
+// Pure: no I/O, no process state. `emit` is injected so tests can
+// capture the stream.
+
+import {
+  canonicalToolName,
+  sanitizeToolValue,
+  summarizeTool,
+} from "../contract.mjs";
+
+/** Tool names (canonical) whose calls END the turn instead of running. */
+const QUESTION_TOOL = "Question";
+const EXIT_PLAN_TOOL = "ExitPlanMode";
+
+/** Generic ACP `kind` → a readable tool label when no meta name exists. */
+const KIND_LABEL = {
+  read: "Read",
+  edit: "Edit",
+  delete: "Delete",
+  move: "Move",
+  search: "Search",
+  execute: "Bash",
+  think: "Think",
+  fetch: "WebFetch",
+  switch_mode: "SwitchMode",
+  other: "Tool",
+};
+
+/** Best-effort tool name from an ACP tool_call (+ harness meta). */
+export function toolNameFromUpdate(update) {
+  const meta = update?._meta ?? {};
+  const fromMeta =
+    meta.claudeCode?.toolName ??
+    meta.codex?.toolName ??
+    meta.codex?.tool ??
+    meta.toolName;
+  if (typeof fromMeta === "string" && fromMeta) return fromMeta;
+  // codex-acp encodes MCP tool calls as `rawInput: {server, tool,
+  // arguments}` under kind "execute" — without this they'd render as a
+  // Bash row, and the ask_user question bridge would never be detected.
+  if (typeof update?.rawInput?.server === "string" && typeof update?.rawInput?.tool === "string") {
+    return `mcp__${update.rawInput.server}__${update.rawInput.tool}`;
+  }
+  // Generic adapters (codex-acp) describe shell runs by `rawInput.command`
+  // whatever `kind` they classify them as (`ls` → read) — the dashboard
+  // wants the Bash row + command summary.
+  if (typeof update?.rawInput?.command === "string" || Array.isArray(update?.rawInput?.command)) return "Bash";
+  // The kai_todos bridge's announce can arrive before `_meta` names the
+  // call — the adapter's human title still says todo_write. Without this
+  // the announce leaks a bare "Tool (running)" row that the suppressed
+  // completion never clears.
+  if (typeof update?.title === "string" && /todo_write/.test(update.title)) return "TodoWrite";
+  if (update?.kind && KIND_LABEL[update.kind]) return KIND_LABEL[update.kind];
+  return "Tool";
+}
+
+/** Normalise adapter-specific raw inputs into the shapes summarizeTool knows. */
+export function normalizeToolInput(name, update) {
+  const raw = update?.rawInput;
+  // MCP calls (codex-acp): the useful input is the nested `arguments`.
+  if (name.startsWith("mcp__") && raw && typeof raw.arguments === "object" && raw.arguments !== null) return raw.arguments;
+  if (name === "Bash" && raw && Array.isArray(raw.command)) return { ...raw, command: raw.command.join(" ") };
+  if (raw && typeof raw === "object" && Object.keys(raw).length > 0) return raw;
+  // Edits arrive as diff content blocks with no rawInput (claude-agent-acp
+  // and codex-acp both do this). Preserve the actual edit — oldText/newText —
+  // as Claude-Code-shaped fields so the dashboard can render the diff view
+  // and the "+N -N" line counts; dropping them here is why bridge sessions
+  // used to show "(no diff captured)".
+  if (Array.isArray(update?.content)) {
+    const diffs = update.content.filter((c) => c?.type === "diff" && c.path);
+    if (diffs.length === 1) {
+      const d = diffs[0];
+      const base = { file_path: d.path };
+      if (typeof d.newText === "string") {
+        if (typeof d.oldText === "string" && d.oldText.length > 0) {
+          base.old_string = d.oldText;
+          base.new_string = d.newText;
+        } else {
+          // No prior content → a Write (new file / full overwrite).
+          base.content = d.newText;
+        }
+      }
+      return base;
+    }
+    if (diffs.length > 1) {
+      return {
+        file_path: diffs[0].path,
+        files: diffs.map((d) => d.path),
+        edits: diffs.map((d) => ({
+          old_string: typeof d.oldText === "string" ? d.oldText : "",
+          new_string: typeof d.newText === "string" ? d.newText : "",
+        })),
+      };
+    }
+  }
+  // Read/search actions carry `locations` instead of an input.
+  if (Array.isArray(update?.locations) && update.locations[0]?.path) return { file_path: update.locations[0].path };
+  return raw ?? null;
+}
+
+function parentFromUpdate(update) {
+  const meta = update?._meta ?? {};
+  const parent = meta.claudeCode?.parentToolUseId ?? meta.codex?.parentToolCallId;
+  return typeof parent === "string" && parent ? parent : null;
+}
+
+/** ACP plan entries → the TodoWrite `todos` shape the dashboard renders. */
+export function planEntriesToTodos(entries) {
+  return (Array.isArray(entries) ? entries : [])
+    .map((e) => ({
+      content: String(e?.content ?? ""),
+      status: e?.status === "completed" ? "completed" : e?.status === "in_progress" ? "in_progress" : "pending",
+      priority: typeof e?.priority === "string" ? e.priority : "medium",
+    }))
+    .filter((t) => t.content.length > 0);
+}
+
+/** AskUserQuestion-style input → contract `questions[]`. */
+export function normalizeQuestions(input) {
+  const raw = Array.isArray(input?.questions) ? input.questions : [];
+  return raw
+    .map((q) => ({
+      question: String(q?.question || ""),
+      header: String(q?.header || ""),
+      options: Array.isArray(q?.options)
+        ? q.options.map((o) => ({
+            label: String(o?.label || ""),
+            description: String(o?.description || ""),
+          }))
+        : [],
+      multiSelect: q?.multiSelect === true || q?.multiple === true,
+    }))
+    .filter((q) => q.question.length > 0);
+}
+
+const hasInput = (v) => v != null && (typeof v !== "object" || Array.isArray(v) || Object.keys(v).length > 0);
+
+/**
+ * ACP form elicitation (claude-agent-acp's AskUserQuestion bridge) →
+ * contract `questions[]`. The adapter encodes each question as
+ * `question_<n>` (`oneOf` = single choice, `items.anyOf` = multi) plus a
+ * free-text `question_<n>_custom`; a single question's text rides on
+ * `message`, multiple questions carry theirs in `description`.
+ */
+export function questionsFromElicitation(request) {
+  const props = request?.requestedSchema?.properties;
+  if (!props || typeof props !== "object") return [];
+  const keys = Object.keys(props)
+    .filter((k) => /^question_\d+$/.test(k))
+    .sort((a, b) => Number(a.slice(9)) - Number(b.slice(9)));
+  const single = keys.length === 1;
+  return keys
+    .map((k) => {
+      const field = props[k] || {};
+      const multiSelect = field.type === "array";
+      const opts = multiSelect ? field.items?.anyOf : field.oneOf;
+      return {
+        question: String((single ? request.message : field.description) || field.description || request.message || ""),
+        header: String(field.title || ""),
+        options: (Array.isArray(opts) ? opts : []).map((o) => ({
+          label: String(o?.const ?? o?.title ?? ""),
+          description: String(o?.description ?? ""),
+        })),
+        multiSelect,
+      };
+    })
+    .filter((q) => q.question.length > 0);
+}
+
+/** Flatten ACP content blocks / raw tool output into something emit-able. */
+function contentToValue(content) {
+  if (content == null) return undefined;
+  if (typeof content === "string") return content;
+  if (typeof content === "object" && !Array.isArray(content) && typeof content.formatted_output === "string") {
+    const exit = content.exit_code;
+    return exit != null && exit !== 0 ? `${content.formatted_output}\n[exit ${exit}]` : content.formatted_output;
+  }
+  if (Array.isArray(content)) {
+    const parts = [];
+    for (const c of content) {
+      if (!c || typeof c !== "object") continue;
+      if (c.type === "content" && c.content?.type === "text") parts.push(String(c.content.text ?? ""));
+      else if (c.type === "text") parts.push(String(c.text ?? ""));
+      else if (c.type === "diff") parts.push(`diff ${c.path ?? ""}`);
+      else if (c.type === "terminal") parts.push(`[terminal ${c.terminalId ?? ""}]`);
+      else parts.push(JSON.stringify(c));
+    }
+    return parts.join("\n");
+  }
+  return content;
+}
+
+/**
+ * @param {object} opts
+ * @param {(event: object) => void} opts.emit   contract line sink
+ * @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]
+ */
+/**
+ * Permission policy for `request_permission`: build mode allows everything
+ * (the worktree/sandbox is the boundary); plan mode and artifact writers
+ * deny repo mutations — artifact writers may still write under `.kai/`.
+ * Belt-and-braces next to the session mode (`plan` / `dontAsk`) set on
+ * the agent: a mode the adapter fails to apply must not become a free
+ * pass for edits.
+ */
+export function permissionPolicy({ isPlanMode = false, isArtifactWriter = false, workDir = "" } = {}) {
+  const WRITE_TOOLS = /^(Write|Edit|MultiEdit|NotebookEdit)$/;
+  const READONLY_BASH = /^\s*(cat|head|tail|wc|stat|ls|find|grep|rg|git (log|diff|show|status|ls-files|grep|rev-parse|branch)|sed -n|awk|jq|sort|uniq|cut|tr|diff|nl|basename|dirname|realpath|file|echo|pwd|which)\b/;
+  const kaiDir = workDir ? `${workDir.replace(/\/+$/, "")}/.kai/` : "/.kai/";
+  return (name, input) => {
+    if (!isPlanMode && !isArtifactWriter) return true;
+    const canonical = canonicalToolName(name);
+    if (WRITE_TOOLS.test(canonical)) {
+      if (!isArtifactWriter) return false;
+      const path = String(input?.file_path ?? input?.filePath ?? input?.notebook_path ?? "");
+      return path.startsWith(kaiDir) || path.startsWith(".kai/");
+    }
+    if (canonical === "Bash") {
+      const cmd = String(input?.command ?? "");
+      // Allow plain read-only commands; anything with redirection or
+      // mutation verbs is denied (the post-turn revert catches leaks).
+      return READONLY_BASH.test(cmd) && !/[>|]|\b(rm|mv|cp|touch|mkdir|chmod|chown|git (add|commit|push|checkout|reset|rebase|merge|stash)|npm|pnpm|yarn|pip|make)\b/.test(cmd);
+    }
+    return true;
+  };
+}
+
+export function createAcpMapper({ emit, isPlanMode = false, onTurnShouldEnd, onContextSnapshot, mcpServerIds = {}, readPlanFile = () => "", allowTool = () => true }) {
+  /** toolCallId → { name, input, parent, emitted } */
+  const tools = new Map();
+  /** MCP server keys whose `connected` status already went out. */
+  const mcpConnectedEmitted = new Set();
+
+  // ACP carries no MCP boot/health signal. A tool call `mcp__<key>__…`
+  // that completes WITHOUT error is proof the server is connected — emit
+  // `mcp_status ok:true` once per server so the host's sticky-success
+  // rollup gets the signal it waits for (same inference as the claude
+  // runner's noteMcpTrafficSuccess).
+  const noteMcpTrafficSuccess = (rawName) => {
+    const m = /^mcp__([^_].*?)__/.exec(String(rawName || ""));
+    if (!m) return;
+    const key = m[1];
+    if (mcpConnectedEmitted.has(key)) return;
+    mcpConnectedEmitted.add(key);
+    emit({
+      type: "mcp_status",
+      message: `MCP ${key} connected`,
+      mcpStatus: { serverId: mcpServerIds[key] ?? key, ok: true },
+    });
+  };
+  let textBuffer = "";
+  let thoughtBuffer = "";
+  let lastText = "";
+  let questionAsked = false;
+  let planEmitted = false;
+  let lastPlanMarkdown = "";
+  let lastUsage = null; // { used, size, costUsd }
+
+  const flushThought = () => {
+    const t = thoughtBuffer.trim();
+    thoughtBuffer = "";
+    if (t) emit({ type: "thinking", message: t });
+  };
+  const flushText = () => {
+    const t = textBuffer.trim();
+    textBuffer = "";
+    if (!t) return;
+    lastText = t;
+    // Plan agents keep prose for the result-time fallback (same as the
+    // claude/opencode runners) — the plan itself arrives via ExitPlanMode.
+    if (!isPlanMode) emit({ type: "text", message: t });
+  };
+
+  const emitToolStatus = (id, status, { output, error } = {}) => {
+    const meta = tools.get(id);
+    if (!meta) return;
+    const name = canonicalToolName(meta.name);
+    if (name === "TodoWrite") {
+      // Emit only when the input actually carries the list — an
+      // input-less announce would otherwise wipe the dashboard's todo
+      // stage with `[]` for a beat before the real update lands.
+      if (Array.isArray(meta.input?.todos)) {
+        emit({ type: "todos", message: JSON.stringify(meta.input.todos) });
+      }
+      return;
+    }
+    // Adapter-provided titles ("List files in 'src'") stand in when the
+    // input carries nothing summarizeTool understands.
+    const summary = summarizeTool(name, meta.input || {}) || meta.title || "";
+    emit({
+      type: "tool_status",
+      message: summary ? `${name} ${summary}` : name,
+      toolName: name,
+      toolSummary: summary,
+      toolInput: meta.input != null ? sanitizeToolValue(meta.input, 4000) : undefined,
+      toolOutput: output != null ? sanitizeToolValue(output, 4000) : undefined,
+      toolError: error != null ? sanitizeToolValue(error, 1000) : undefined,
+      toolStatus: status,
+      toolPartId: id,
+      ...(meta.parent ? { parentToolPartId: meta.parent } : {}),
+    });
+  };
+
+  const isTurnEndingTool = (name) => {
+    const canonical = canonicalToolName(name);
+    return canonical === QUESTION_TOOL || canonical === EXIT_PLAN_TOOL || /(^|__|\.)ask_user$/.test(String(name));
+  };
+
+  /** Remember plan-file writes so a question / hand-off can surface the plan. */
+  const notePlanWrite = (name, input) => {
+    if (!isPlanMode || !/^(Write|Edit|MultiEdit)$/.test(canonicalToolName(name))) return;
+    const body = typeof input?.content === "string" ? input.content : "";
+    const path = String(input?.file_path ?? input?.filePath ?? "");
+    if (body && /plan/i.test(path)) lastPlanMarkdown = body.trim();
+  };
+
+  /** A turn-ending tool surfaced (question or plan hand-off). */
+  const handleTurnEndingTool = (name, input) => {
+    const canonical = canonicalToolName(name);
+    if (canonical === QUESTION_TOOL || /(^|__|\.)ask_user$/.test(String(name))) {
+      const questions = normalizeQuestions(input);
+      if (questions.length === 0 || questionAsked) return false;
+      questionAsked = true;
+      flushThought();
+      flushText();
+      emit({
+        type: "question",
+        message: questions.length === 1 ? "Asking a question…" : `Asking ${questions.length} questions…`,
+        questions,
+      });
+      if (isPlanMode && lastPlanMarkdown) emit({ type: "plan", message: lastPlanMarkdown });
+      onTurnShouldEnd?.("question");
+      return true;
+    }
+    if (canonical === EXIT_PLAN_TOOL) {
+      if (questionAsked || planEmitted) return true;
+      // ExitPlanMode's own `plan` input, else the last plan-file write we
+      // saw, else the newest file in the plans directory (the CLI writes
+      // there itself on 2.1.24x and only references it by path).
+      const markdown = (typeof input?.plan === "string" && input.plan.trim()) || lastPlanMarkdown || String(readPlanFile() || "").trim();
+      if (!markdown) return false;
+      planEmitted = true;
+      flushThought();
+      flushText();
+      emit({ type: "plan", message: markdown });
+      onTurnShouldEnd?.("plan");
+      return true;
+    }
+    return false;
+  };
+
+  return {
+    /** Feed one `session/update` notification's `update` payload. */
+    handleUpdate(update) {
+      if (!update || typeof update !== "object") return;
+      switch (update.sessionUpdate) {
+        case "agent_thought_chunk": {
+          flushText();
+          if (update.content?.type === "text") thoughtBuffer += update.content.text ?? "";
+          return;
+        }
+        case "agent_message_chunk": {
+          flushThought();
+          if (update.content?.type === "text") textBuffer += update.content.text ?? "";
+          return;
+        }
+        case "tool_call": {
+          flushThought();
+          flushText();
+          const id = String(update.toolCallId ?? "");
+          if (!id) return;
+          const name = toolNameFromUpdate(update);
+          const input = normalizeToolInput(name, update);
+          notePlanWrite(name, input);
+          if (handleTurnEndingTool(name, input)) return;
+          if (isTurnEndingTool(name)) return; // input still streaming — the elicitation/permission carries it
+          const existing = tools.get(id);
+          const meta = {
+            name,
+            input: hasInput(input) ? input : existing?.input ?? null,
+            title: typeof update.title === "string" && update.title !== name ? update.title : existing?.title ?? "",
+            parent: parentFromUpdate(update),
+            emitted: existing?.emitted ?? false,
+          };
+          tools.set(id, meta);
+          // Adapters announce the call before the streamed input is
+          // complete (`rawInput: {}`); hold the "running" row until the
+          // input lands so the dashboard summary isn't blank.
+          if (!meta.emitted && (hasInput(meta.input) || (meta.title && update.status === "in_progress"))) {
+            meta.emitted = true;
+            emitToolStatus(id, "running");
+          }
+          return;
+        }
+        case "tool_call_update": {
+          const id = String(update.toolCallId ?? "");
+          const meta = tools.get(id);
+          // Turn-ending tools (question / plan hand-off) are rendered as their
+          // own cards by handleTurnEndingTool / handleElicitation — never as
+          // a tool row, even when their input arrives late.
+          if (meta && isTurnEndingTool(meta.name)) {
+            tools.delete(id);
+            return;
+          }
+          if (!meta) {
+            // Update for a call we never saw start (adapter cache miss or
+            // turn-ending tool) — nothing to pair it with.
+            return;
+          }
+          // Late-arriving input: adapters often attach the real payload
+          // (rawInput, or diff content blocks) only on the completion
+          // update — and claude-agent-acp's rawInput can be PARTIAL
+          // (old_string without new_string). Merge instead of replace:
+          // the earliest value wins per key, later updates only fill
+          // holes, so a path-only or half-truncated stub still ends up
+          // carrying the full edit for the dashboard's diff view.
+          {
+            const richer = normalizeToolInput(meta.name, update);
+            if (hasInput(richer) && typeof richer === "object" && !Array.isArray(richer)) {
+              if (!hasInput(meta.input) || typeof meta.input !== "object" || Array.isArray(meta.input)) {
+                meta.input = richer;
+                notePlanWrite(meta.name, meta.input);
+              } else {
+                let filled = false;
+                for (const [key, value] of Object.entries(richer)) {
+                  if (meta.input[key] == null) {
+                    meta.input[key] = value;
+                    filled = true;
+                  }
+                }
+                if (filled) notePlanWrite(meta.name, meta.input);
+              }
+            }
+          }
+          if (!meta.emitted && (hasInput(meta.input) || update.status === "completed" || update.status === "failed")) {
+            meta.emitted = true;
+            emitToolStatus(id, "running");
+          }
+          if (update.status === "completed" || update.status === "failed") {
+            if (update.status === "completed") noteMcpTrafficSuccess(meta.name);
+            const output = contentToValue(update.rawOutput ?? update.content);
+            emitToolStatus(
+              id,
+              update.status === "failed" ? "failed" : "completed",
+              update.status === "failed" ? { error: output } : { output },
+            );
+            tools.delete(id);
+          }
+          return;
+        }
+        case "plan": {
+          // ACP "plan" = the agent's task list (TodoWrite equivalent), NOT
+          // the planner's markdown hand-off.
+          emit({ type: "todos", message: JSON.stringify(planEntriesToTodos(update.entries)) });
+          return;
+        }
+        case "usage_update": {
+          const used = Number(update.used);
+          const size = Number(update.size);
+          const costUsd = Number(update.cost?.amount);
+          lastUsage = {
+            used: Number.isFinite(used) ? used : null,
+            size: Number.isFinite(size) && size > 0 ? size : null,
+            costUsd: Number.isFinite(costUsd) ? costUsd : null,
+          };
+          if (lastUsage.used != null && lastUsage.used > 0) {
+            onContextSnapshot?.(undefined, lastUsage.used, lastUsage.size ?? undefined);
+          }
+          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":
+        default:
+          return;
+      }
+    },
+
+    /**
+     * A `session/request_permission` arrived. Returns the option id to
+     * answer with, or `null` when the turn should be cancelled instead
+     * (question / plan hand-off). Build mode allows everything — the
+     * sandbox/worktree IS the permission boundary, same as today's
+     * `--dangerously-skip-permissions`.
+     */
+    handlePermission(params) {
+      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;
+      if (!allowTool(name, input)) {
+        emit({
+          type: "tool_status",
+          message: `${canonicalToolName(name)} blocked (read-only mode)`,
+          toolName: canonicalToolName(name),
+          toolSummary: "blocked (read-only mode)",
+          toolInput: input != null ? sanitizeToolValue(input, 1000) : undefined,
+          toolStatus: "failed",
+          toolError: "Not allowed in this mode.",
+          toolPartId: String(toolCall.toolCallId ?? `deny-${Date.now()}`),
+        });
+        return pick("reject_once") ?? pick("reject_always") ?? "__reject__";
+      }
+      return pick("allow_always") ?? pick("allow_once") ?? options[0]?.optionId ?? null;
+    },
+
+    /**
+     * A form elicitation arrived (AskUserQuestion via claude-agent-acp).
+     * Emits the question event and asks the runner to end the turn; the
+     * answers arrive as the next user turn. Returns true when handled.
+     */
+    handleElicitation(request) {
+      if (request?.mode && request.mode !== "form") return false;
+      const questions = questionsFromElicitation(request);
+      if (questions.length === 0 || questionAsked) return false;
+      questionAsked = true;
+      flushThought();
+      flushText();
+      emit({
+        type: "question",
+        message: questions.length === 1 ? "Asking a question…" : `Asking ${questions.length} questions…`,
+        questions,
+      });
+      if (isPlanMode && lastPlanMarkdown) emit({ type: "plan", message: lastPlanMarkdown });
+      onTurnShouldEnd?.("question");
+      return true;
+    },
+
+    /** End-of-turn bookkeeping; returns what the runner needs for `result`. */
+    finish() {
+      flushThought();
+      flushText();
+      for (const id of [...tools.keys()]) {
+        // Calls still open when the agent stopped — resolve so the
+        // dashboard row never spins forever.
+        const meta = tools.get(id);
+        if (!meta.emitted) {
+          meta.emitted = true;
+          emitToolStatus(id, "running");
+        }
+        emitToolStatus(id, "completed", {});
+        tools.delete(id);
+      }
+      return {
+        lastText,
+        questionAsked,
+        planEmitted,
+        lastPlanMarkdown,
+        usage: lastUsage,
+      };
+    },
+  };
+}