hilos-agent 0.7.0 → 0.9.1

package/src/acp-session.mjs

@@ -0,0 +1,553 @@
+// ACP (Agent Client Protocol) session runner (0759).
+//
+// Drives an agent subprocess over ACP — JSON-RPC 2.0, newline-delimited, on
+// stdio — instead of argv + stdout scraping. The 0596 spike proved the loop
+// live against `opencode acp`: permissions arrive as blocking JSON-RPC
+// requests with allow-once/always/reject options, and streaming arrives as
+// structured session/update notifications.
+//
+// The permission callback contract is EXACTLY the HTTP bridge's
+// (requestPermission / getPermissionDecision, see opencode-permissions.mjs),
+// so neither transport can become the ungated exception; the decision
+// vocabulary is shared via mapOpenCodePermissionDecision. Every failure mode
+// answers the agent with a rejection — fail closed, never fail open.
+//
+// The public runner returns the same small shape as runCli /
+// runOpenCodeHttpSession so handler.mjs keeps one integration seam:
+//   { status, stdout, stderr, error?, sessionId?, aborted? }
+
+import { spawn } from "node:child_process";
+import { createAcpEventMapper } from "./agent-events.mjs";
+import { resolveHilosPermissionReply } from "./permission-gate.mjs";
+
+const DEFAULT_TIMEOUT_MS = 30 * 60_000;
+const DEFAULT_POLL_MS = 1_000;
+const SHUTDOWN_GRACE_MS = 750;
+const PROTOCOL_VERSION = 1;
+const MAX_LINE_BYTES = 4 * 1024 * 1024;
+
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function abortError(reason = "cancelled") {
+  const error = new Error(String(reason || "cancelled"));
+  error.name = "AbortError";
+  return error;
+}
+
+function raceWithAbort(promise, signal) {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(abortError(signal.reason));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortError(signal.reason));
+    signal.addEventListener("abort", onAbort, { once: true });
+    Promise.resolve(promise).then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Choose the agent's option id for a hilos reply ("once"|"always"|"reject").
+ * Matches on the ACP option `kind` first (allow_once / allow_always /
+ * reject_once / reject_always), then falls back to id/name heuristics. A
+ * reject reply with no recognizable option returns null — the caller answers
+ * with a protocol-level cancel, which the agent must treat as not-allowed.
+ */
+export function pickAcpPermissionOption(options, reply) {
+  const list = Array.isArray(options) ? options.filter(isObject) : [];
+  const byKind = (kind) => list.find((o) => o.kind === kind);
+  const byPattern = (re) =>
+    list.find((o) => re.test(`${o.optionId ?? ""} ${o.name ?? ""}`));
+  if (reply === "always") {
+    // The name fallback must never land on "Reject always" — a human's
+    // allow-always answered with a rejection would invert the decision.
+    return (
+      byKind("allow_always") ??
+      list.find(
+        (o) =>
+          !String(o.kind ?? "").startsWith("reject") &&
+          /always/i.test(`${o.optionId ?? ""} ${o.name ?? ""}`) &&
+          !/reject|deny|\bno\b/i.test(`${o.optionId ?? ""} ${o.name ?? ""}`),
+      ) ??
+      null
+    );
+  }
+  if (reply === "once") {
+    // Never widen a single-use approval into a persistent one: an allow_once
+    // option is required; allow_always is NOT an acceptable stand-in.
+    return (
+      byKind("allow_once") ??
+      list.find(
+        (o) =>
+          o.kind !== "allow_always" &&
+          /\bonce\b|allow/i.test(`${o.optionId ?? ""} ${o.name ?? ""}`) &&
+          !/always/i.test(`${o.optionId ?? ""} ${o.name ?? ""}`),
+      ) ??
+      null
+    );
+  }
+  return (
+    byKind("reject_once") ??
+    byKind("reject_always") ??
+    byPattern(/reject|deny|no\b/i) ??
+    null
+  );
+}
+
+/**
+ * Shape an ACP session/request_permission into the vendor-neutral request the
+ * hilos permission callbacks expect (the same fields the SSE relay produces).
+ */
+export function normalizeAcpPermissionRequest(params, fallbackId, vendor = "opencode") {
+  const toolCall = isObject(params?.toolCall) ? params.toolCall : {};
+  const rawInput = isObject(toolCall.rawInput) ? toolCall.rawInput : {};
+  const locations = Array.isArray(toolCall.locations)
+    ? toolCall.locations
+        .map((l) => (isObject(l) && typeof l.path === "string" ? l.path : null))
+        .filter(Boolean)
+    : [];
+  const command = typeof rawInput.command === "string" ? rawInput.command : null;
+  const resources = locations.length ? locations : command ? [command] : [];
+  const vendorRequestId =
+    typeof toolCall.toolCallId === "string" && toolCall.toolCallId
+      ? toolCall.toolCallId
+      : `acp_${fallbackId}`;
+  return {
+    vendor,
+    vendorRequestId,
+    sessionId: typeof params?.sessionId === "string" ? params.sessionId : "",
+    action: typeof toolCall.kind === "string" && toolCall.kind ? toolCall.kind : "tool",
+    resources,
+    suggestedSave: undefined,
+    metadata: {
+      ...(typeof toolCall.title === "string" && toolCall.title
+        ? { title: toolCall.title }
+        : {}),
+      ...(command ? { command } : {}),
+      transport: "acp",
+    },
+    source: { type: "tool", ...(typeof toolCall.title === "string" ? { name: toolCall.title } : {}) },
+  };
+}
+
+/** Split a stdout stream into newline-delimited JSON-RPC messages. */
+export function createNdjsonParser() {
+  let buffer = "";
+  return {
+    push(chunk) {
+      buffer += String(chunk);
+      if (buffer.length > MAX_LINE_BYTES) {
+        // A frame this large is not a protocol message; drop it rather than
+        // letting a runaway agent grow the daemon's heap without bound.
+        buffer = "";
+        return [];
+      }
+      const messages = [];
+      let idx;
+      while ((idx = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, idx).trim();
+        buffer = buffer.slice(idx + 1);
+        if (!line) continue;
+        try {
+          const parsed = JSON.parse(line);
+          if (isObject(parsed)) messages.push(parsed);
+        } catch {
+          // Non-JSON stdout noise (banners, stray logs) is not a frame.
+        }
+      }
+      return messages;
+    },
+  };
+}
+
+/**
+ * Run one prompt against an ACP agent subprocess.
+ *
+ * Slice 1 (0759) intentionally mirrors the HTTP runner's text mode: stdout
+ * collects the agent's completed message text, tool activity stays off the
+ * transcript, and the session id is returned for the caller's records.
+ *
+ * @param {{
+ *   cmd?: string,
+ *   acpArgs?: string[],
+ *   vendor?: string,
+ *   cwd?: string,
+ *   prompt?: string,
+ *   env?: Record<string, string | undefined>,
+ *   timeoutMs?: number,
+ *   pollIntervalMs?: number,
+ *   signal?: AbortSignal,
+ *   onData?: (chunk: string) => void,
+ *   onEvent?: (event: object) => void,
+ *   requestPermission?: (request: object, context: object) => Promise<unknown>,
+ *   getPermissionDecision?: (handle: unknown, context: object) => Promise<unknown>,
+ *   mcpServers?: object[],
+ *   spawnImpl?: (cmd: string, args: string[], options: object) => import("node:child_process").ChildProcess,
+ *   setTimer?: typeof setTimeout,
+ *   clearTimer?: typeof clearTimeout,
+ *   sleep?: (ms: number) => Promise<void>,
+ *   now?: () => number,
+ *   log?: { error?: (message: string) => void },
+ * }} [options]
+ * @returns {Promise<{ status: number | null, stdout: string, stderr: string, error?: Error | null, sessionId?: string | null, aborted?: boolean }>}
+ */
+export async function runAcpSession({
+  cmd = "opencode",
+  acpArgs = ["acp"],
+  vendor = "opencode",
+  cwd,
+  prompt,
+  env,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  pollIntervalMs = DEFAULT_POLL_MS,
+  signal,
+  onData,
+  onEvent,
+  requestPermission,
+  getPermissionDecision,
+  /** Session to continue (0778); null starts a fresh one. */
+  resumeSessionId = null,
+  mcpServers = [],
+  spawnImpl = spawn,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  now = () => Date.now(),
+  log = console,
+} = {}) {
+  if (!cwd) {
+    return { status: null, stdout: "", stderr: "", error: new Error("ACP requires cwd") };
+  }
+  if (typeof requestPermission !== "function" || typeof getPermissionDecision !== "function") {
+    // Without the hilos gate there is no one to answer asks; refuse to start
+    // rather than run a session whose permissions would dead-end.
+    return {
+      status: null,
+      stdout: "",
+      stderr: "",
+      error: new Error("ACP transport requires the hilos permission callbacks"),
+    };
+  }
+
+  const controller = new AbortController();
+  let abortKind = null;
+  const abort = (kind, reason) => {
+    if (controller.signal.aborted) return;
+    abortKind = kind;
+    controller.abort(reason);
+  };
+  const onParentAbort = () => abort("cancelled", signal?.reason ?? "cancelled");
+  if (signal?.aborted) onParentAbort();
+  else signal?.addEventListener?.("abort", onParentAbort, { once: true });
+  const timeout =
+    timeoutMs > 0
+      ? setTimer(() => abort("timeout", `ACP session timed out after ${timeoutMs}ms`), timeoutMs)
+      : null;
+  timeout?.unref?.();
+
+  let child = null;
+  let sessionId = null;
+  let stdout = "";
+  let stderr = "";
+  let nextId = 0;
+  const pending = new Map();
+  const permissionTasks = new Set();
+  let currentMessageId = null;
+  let messageBuffer = "";
+  const eventMapper = createAcpEventMapper();
+
+  const emitOutput = (text) => {
+    try {
+      onData?.(`${text}\n`);
+    } catch {
+      // Output observers never own session correctness.
+    }
+  };
+  const flushMessage = () => {
+    const text = messageBuffer.trim();
+    messageBuffer = "";
+    currentMessageId = null;
+    if (!text) return;
+    stdout += `${text}\n`;
+    emitOutput(text);
+  };
+
+  const writeFrame = (frame) => {
+    if (!child || child.stdin.destroyed) return false;
+    try {
+      child.stdin.write(`${JSON.stringify(frame)}\n`);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const rpc = (method, params) => {
+    const id = ++nextId;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject, method });
+      if (!writeFrame({ jsonrpc: "2.0", id, method, params })) {
+        pending.delete(id);
+        reject(new Error(`ACP agent is not accepting frames (${method})`));
+      }
+    });
+  };
+  const respond = (id, result, error) => {
+    writeFrame(
+      error
+        ? { jsonrpc: "2.0", id, error }
+        : { jsonrpc: "2.0", id, result },
+    );
+  };
+  const failPending = (reason) => {
+    for (const [, entry] of pending) entry.reject(new Error(reason));
+    pending.clear();
+  };
+
+  async function settlePermission(msg) {
+    const request = normalizeAcpPermissionRequest(msg.params, msg.id, vendor);
+    const receivedAt = now();
+    const deadlineAt = receivedAt + Math.max(1, timeoutMs || DEFAULT_TIMEOUT_MS);
+    // The shared gate (0777): the identical raise → poll → fail-closed loop
+    // claude_code and codex now run, so no transport can drift into being the
+    // lenient one.
+    const { reply } = await resolveHilosPermissionReply({
+      request,
+      requestPermission,
+      getPermissionDecision,
+      signal: controller.signal,
+      deadlineAt,
+      pollIntervalMs,
+      sleep,
+      now,
+      log,
+      label: "acp permission",
+    });
+    const option = pickAcpPermissionOption(msg.params?.options, reply);
+    if (option && (reply !== "reject" || option.kind?.startsWith("reject"))) {
+      respond(msg.id, { outcome: { outcome: "selected", optionId: option.optionId } });
+    } else if (reply === "reject") {
+      // No recognizable reject option: cancel the ask at the protocol level.
+      respond(msg.id, { outcome: { outcome: "cancelled" } });
+    } else {
+      // An approval we cannot express in the agent's options must not become
+      // an implicit rejection card-side; the wire still gets a cancel.
+      log?.error?.("acp permission: no matching option for reply, cancelling");
+      respond(msg.id, { outcome: { outcome: "cancelled" } });
+    }
+  }
+
+  function handleUpdate(update) {
+    if (!isObject(update)) return;
+    const kind = update.sessionUpdate;
+    if (kind === "agent_message_chunk") {
+      const messageId = typeof update.messageId === "string" ? update.messageId : null;
+      if (currentMessageId !== null && messageId !== currentMessageId) flushMessage();
+      currentMessageId = messageId;
+      const text =
+        isObject(update.content) && typeof update.content.text === "string"
+          ? update.content.text
+          : "";
+      messageBuffer += text;
+      return;
+    }
+    // Tool calls narrate the activity feed (0759 slice 3): the mapper's
+    // emit-once discipline turns the raw update stream into AgentEvents.
+    if (onEvent && (kind === "tool_call" || kind === "tool_call_update")) {
+      try {
+        const event = eventMapper.push(update);
+        if (event) onEvent(event);
+      } catch {
+        // Narration must never break the run.
+      }
+      return;
+    }
+    // Thoughts, usage, command lists: structurally received, not activity.
+  }
+
+  function handleMessage(msg) {
+    if (msg.id !== undefined && (msg.result !== undefined || msg.error !== undefined)) {
+      const entry = pending.get(msg.id);
+      if (!entry) return;
+      pending.delete(msg.id);
+      if (msg.error) {
+        entry.reject(
+          new Error(
+            `ACP ${entry.method} failed: ${msg.error.message ?? JSON.stringify(msg.error)}`,
+          ),
+        );
+      } else {
+        entry.resolve(msg.result);
+      }
+      return;
+    }
+    if (msg.method === "session/update") {
+      if (isObject(msg.params) && msg.params.sessionId === sessionId) {
+        handleUpdate(msg.params.update);
+      }
+      return;
+    }
+    if (msg.method === "session/request_permission" && msg.id !== undefined) {
+      const task = settlePermission(msg).finally(() => permissionTasks.delete(task));
+      permissionTasks.add(task);
+      return;
+    }
+    if (msg.id !== undefined && msg.method) {
+      // fs/terminal requests should never arrive (capabilities declared off);
+      // refuse anything unexpected instead of guessing.
+      respond(msg.id, undefined, {
+        code: -32601,
+        message: `hilos does not implement ${msg.method}`,
+      });
+    }
+  }
+
+  try {
+    child = spawnImpl(cmd, acpArgs, { cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+    const spawned = new Promise((resolve, reject) => {
+      child.once("spawn", resolve);
+      child.once("error", reject);
+    });
+    child.once("exit", (code) => {
+      failPending(`ACP agent exited (${code ?? "signal"}) before replying`);
+    });
+    const parser = createNdjsonParser();
+    child.stdout.on("data", (chunk) => {
+      for (const msg of parser.push(chunk)) {
+        try {
+          handleMessage(msg);
+        } catch (error) {
+          log?.error?.(`acp frame handling: ${error?.message ?? error}`);
+        }
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+      if (stderr.length > MAX_LINE_BYTES) stderr = stderr.slice(-MAX_LINE_BYTES);
+    });
+    await raceWithAbort(spawned, controller.signal);
+
+    const init = await raceWithAbort(
+      rpc("initialize", {
+        protocolVersion: PROTOCOL_VERSION,
+        clientCapabilities: {
+          fs: { readTextFile: false, writeTextFile: false },
+          terminal: false,
+        },
+      }),
+      controller.signal,
+    );
+    if (isObject(init) && init.protocolVersion !== undefined && init.protocolVersion !== PROTOCOL_VERSION) {
+      throw new Error(`ACP agent speaks protocol ${init.protocolVersion}, expected ${PROTOCOL_VERSION}`);
+    }
+
+    // Resume over ACP (0778). The 0759 slice-1 exclusion — ACP runs could never
+    // be resumed runs — was deferred work, not an incompatibility: BOTH live
+    // vendors advertise `loadSession: true` in this very handshake (verified
+    // against opencode 1.18.5 and cursor-agent). So a resumed run now loads its
+    // session and keeps raising cards, instead of trading approvals for
+    // continuity. A load that fails (an id from another machine, vendor, or
+    // transport) falls back to a fresh session — never-worse, the same rule the
+    // argv `--resume` retry follows — and says so.
+    const canLoad = isObject(init) && init.agentCapabilities?.loadSession === true;
+    if (resumeSessionId && canLoad) {
+      try {
+        await raceWithAbort(
+          rpc("session/load", { sessionId: resumeSessionId, cwd, mcpServers }),
+          controller.signal,
+        );
+        sessionId = resumeSessionId;
+      } catch (error) {
+        if (controller.signal.aborted) throw error;
+        log?.error?.(
+          `acp session/load failed for ${resumeSessionId}; starting a fresh session: ${error?.message ?? error}`,
+        );
+      }
+    } else if (resumeSessionId) {
+      log?.error?.(
+        `acp agent does not advertise loadSession; starting a fresh session instead of resuming ${resumeSessionId}`,
+      );
+    }
+    if (!sessionId) {
+      const session = await raceWithAbort(
+        rpc("session/new", { cwd, mcpServers }),
+        controller.signal,
+      );
+      sessionId = isObject(session) && typeof session.sessionId === "string" ? session.sessionId : null;
+      if (!sessionId) throw new Error("ACP agent created a session without an id");
+    }
+
+    const turn = await raceWithAbort(
+      rpc("session/prompt", {
+        sessionId,
+        prompt: [{ type: "text", text: String(prompt ?? "") }],
+      }),
+      controller.signal,
+    );
+    flushMessage();
+    // Every in-flight permission has been answered or is being failed closed by
+    // its own error path; give those settlements a bounded chance to finish.
+    await Promise.allSettled([...permissionTasks]);
+
+    const stopReason = isObject(turn) && typeof turn.stopReason === "string" ? turn.stopReason : null;
+    const clean = stopReason === "end_turn" || stopReason == null;
+    return {
+      status: clean ? 0 : 1,
+      stdout: stdout.trimEnd(),
+      stderr: stderr.trimEnd(),
+      error: clean ? null : new Error(`ACP turn stopped: ${stopReason}`),
+      sessionId,
+    };
+  } catch (error) {
+    flushMessage();
+    const aborted = abortKind === "cancelled";
+    const timedOut = abortKind === "timeout";
+    return {
+      status: null,
+      stdout: stdout.trimEnd(),
+      stderr: stderr.trimEnd(),
+      ...(aborted ? { aborted: true } : {}),
+      ...(sessionId ? { sessionId } : {}),
+      error:
+        error instanceof Error && !timedOut
+          ? error
+          : new Error(timedOut ? "ACP session timed out" : String(error)),
+    };
+  } finally {
+    if (timeout != null) clearTimer(timeout);
+    signal?.removeEventListener?.("abort", onParentAbort);
+    if (child && child.exitCode === null && !child.killed) {
+      // Ask for a graceful stop first (the agent may flush state), then kill.
+      if (sessionId) {
+        writeFrame({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } });
+      }
+      try {
+        child.stdin.end();
+      } catch {
+        // Already gone.
+      }
+      const grace = setTimer(() => {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+          // Already gone.
+        }
+      }, SHUTDOWN_GRACE_MS);
+      grace?.unref?.();
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        // Already gone.
+      }
+    }
+    failPending("ACP session finished");
+  }
+}