hilos-agent 0.6.0 → 0.7.0

package/src/opencode-session.mjs

@@ -0,0 +1,770 @@
+// Authenticated OpenCode HTTP session runner (0593).
+//
+// `opencode run --attach` cannot be used for hilos runtime approvals: that CLI
+// subscribes to `permission.asked` itself and immediately replies `reject`
+// unless `--auto` is enabled. A second hilos subscriber would race a built-in
+// responder, so this module owns the one event stream and is the only component
+// allowed to answer permission asks.
+//
+// The public runner returns the same small shape as runCli so handler.mjs can
+// preserve its report/progress/error paths:
+//   { status, stdout, stderr, error?, sessionId?, aborted? }
+
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { realpathSync } from "node:fs";
+import {
+  createOpenCodePermissionRelay,
+  createSseParser,
+} from "./opencode-permissions.mjs";
+import { envForCwd } from "./cli.mjs";
+
+const STARTUP_TIMEOUT_MS = 15_000;
+const SHUTDOWN_GRACE_MS = 750;
+const OPENCODE_SESSION_RE = /^ses_[A-Za-z0-9_-]+$/;
+
+function abortError(reason = "cancelled") {
+  const error = new Error(String(reason || "cancelled"));
+  error.name = "AbortError";
+  return error;
+}
+
+function basicAuthorization(username, password) {
+  return `Basic ${Buffer.from(`${username}:${password}`, "utf8").toString("base64")}`;
+}
+
+function withDirectory(baseUrl, pathname, directory) {
+  const url = new URL(pathname, baseUrl);
+  url.searchParams.set("directory", directory);
+  return url;
+}
+
+function optionValue(args, index, long, short) {
+  const value = args[index];
+  if (value === long || value === short) {
+    if (typeof args[index + 1] !== "string" || !args[index + 1]) {
+      throw new Error(`${long} requires a value`);
+    }
+    return { value: args[index + 1], consumed: 2 };
+  }
+  if (value.startsWith(`${long}=`)) {
+    return { value: value.slice(long.length + 1), consumed: 1 };
+  }
+  return null;
+}
+
+/**
+ * Parse only the OpenCode run options the HTTP API can preserve exactly.
+ * Unknown options fail closed instead of silently dropping a user's runtime
+ * policy or falling back to the CLI that auto-rejects permission asks.
+ */
+export function parseOpenCodeRunArgs(rawArgs = []) {
+  const args = [...rawArgs];
+  if (args[0] === "run") args.shift();
+  const parsed = {
+    auto: false,
+    serverArgs: [],
+    model: null,
+    agent: null,
+    variant: null,
+    title: null,
+    directory: null,
+    format: "default",
+    sessionId: null,
+  };
+
+  for (let i = 0; i < args.length; ) {
+    const arg = args[i];
+    if (arg === "--auto") {
+      parsed.auto = true;
+      i++;
+      continue;
+    }
+    if (arg === "--pure" || arg === "--print-logs") {
+      parsed.serverArgs.push(arg);
+      i++;
+      continue;
+    }
+    const logLevel = optionValue(args, i, "--log-level", "");
+    if (logLevel) {
+      parsed.serverArgs.push("--log-level", logLevel.value);
+      i += logLevel.consumed;
+      continue;
+    }
+    const model = optionValue(args, i, "--model", "-m");
+    if (model) {
+      parsed.model = model.value;
+      i += model.consumed;
+      continue;
+    }
+    const agent = optionValue(args, i, "--agent", "");
+    if (agent) {
+      parsed.agent = agent.value;
+      i += agent.consumed;
+      continue;
+    }
+    const variant = optionValue(args, i, "--variant", "");
+    if (variant) {
+      parsed.variant = variant.value;
+      i += variant.consumed;
+      continue;
+    }
+    const title = optionValue(args, i, "--title", "");
+    if (title) {
+      parsed.title = title.value;
+      i += title.consumed;
+      continue;
+    }
+    const directory = optionValue(args, i, "--dir", "");
+    if (directory) {
+      parsed.directory = directory.value;
+      i += directory.consumed;
+      continue;
+    }
+    const session = optionValue(args, i, "--session", "-s");
+    if (session) {
+      if (!OPENCODE_SESSION_RE.test(session.value)) {
+        throw new Error("OpenCode --session must use a ses_ identifier");
+      }
+      parsed.sessionId = session.value;
+      i += session.consumed;
+      continue;
+    }
+    const format = optionValue(args, i, "--format", "");
+    if (format) {
+      if (format.value !== "default" && format.value !== "json") {
+        throw new Error("OpenCode --format must be default or json");
+      }
+      parsed.format = format.value;
+      i += format.consumed;
+      continue;
+    }
+    if (arg === "--format=default" || arg === "--format=json") {
+      parsed.format = arg.slice("--format=".length);
+      i++;
+      continue;
+    }
+    // These affect display only; hilos already consumes the event stream.
+    if (arg === "--thinking" || arg === "--share") {
+      i++;
+      continue;
+    }
+    throw new Error(
+      `OpenCode runtime permissions do not support ${arg || "an empty run argument"} yet`,
+    );
+  }
+  return parsed;
+}
+
+export function openCodeModel(value) {
+  if (!value) return null;
+  const slash = value.indexOf("/");
+  if (slash <= 0 || slash === value.length - 1) {
+    throw new Error("OpenCode --model must use provider/model");
+  }
+  return {
+    providerID: value.slice(0, slash),
+    modelID: value.slice(slash + 1),
+  };
+}
+
+function messageError(event) {
+  const error = event?.properties?.error;
+  if (!error) return "OpenCode session failed";
+  if (typeof error === "string") return error;
+  if (typeof error?.data?.message === "string") return error.data.message;
+  if (typeof error?.message === "string") return error.message;
+  if (typeof error?.name === "string") return error.name;
+  return "OpenCode session failed";
+}
+
+function terminateProcessGroup(child, {
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  kill = process.kill,
+} = {}) {
+  if (!child || child.exitCode != null || child.signalCode != null) return Promise.resolve();
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer = null;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      if (timer != null) clearTimer(timer);
+      child.removeListener?.("exit", done);
+      resolve();
+    };
+    child.once?.("exit", done);
+    try {
+      if (child.pid) kill(-child.pid, "SIGTERM");
+      else child.kill?.("SIGTERM");
+    } catch {
+      child.kill?.("SIGTERM");
+    }
+    timer = setTimer(() => {
+      try {
+        if (child.pid) kill(-child.pid, "SIGKILL");
+        else child.kill?.("SIGKILL");
+      } catch {
+        child.kill?.("SIGKILL");
+      }
+      done();
+    }, SHUTDOWN_GRACE_MS);
+    timer?.unref?.();
+  });
+}
+
+/**
+ * Launch a loopback-only, password-protected OpenCode server and resolve only
+ * after its exact listening line is observed.
+ * @param {any} [options]
+ * @returns {Promise<any>}
+ */
+export function startOpenCodeServer({
+  cmd = "opencode",
+  cwd,
+  env,
+  serverArgs = [],
+  password = randomBytes(24).toString("base64url"),
+  username = "opencode",
+  signal,
+  spawnImpl = spawn,
+  kill = process.kill,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  startupTimeoutMs = STARTUP_TIMEOUT_MS,
+} = {}) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(abortError(signal.reason));
+    let child;
+    try {
+      child = spawnImpl(
+        cmd,
+        [
+          "serve",
+          "--hostname",
+          "127.0.0.1",
+          "--port",
+          "0",
+          ...serverArgs,
+        ],
+        {
+          cwd,
+          detached: true,
+          stdio: ["ignore", "pipe", "pipe"],
+          // PWD follows cwd (0615): opencode resolves its project from the
+          // environment, so an inherited PWD would serve a project from the
+          // daemon's launch directory instead of the repo we're running on.
+          env: {
+            ...envForCwd(env ?? {}, cwd),
+            OPENCODE_SERVER_PASSWORD: password,
+            OPENCODE_SERVER_USERNAME: username,
+          },
+        },
+      );
+    } catch (error) {
+      reject(error);
+      return;
+    }
+
+    let settled = false;
+    let timer = null;
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.setEncoding?.("utf8");
+    child.stderr?.setEncoding?.("utf8");
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      if (timer != null) clearTimer(timer);
+      signal?.removeEventListener?.("abort", onAbort);
+      child.removeListener?.("error", onError);
+      child.removeListener?.("exit", onExit);
+      if (error) {
+        void terminateProcessGroup(child, { setTimer, clearTimer, kill });
+        reject(error);
+      } else {
+        resolve(value);
+      }
+    };
+    const inspect = () => {
+      const match = /opencode server listening on (http:\/\/127\.0\.0\.1:\d+)/.exec(stdout);
+      if (!match) return;
+      finish(null, {
+        child,
+        baseUrl: match[1],
+        password,
+        username,
+        stderr: () => stderr,
+        close: () => terminateProcessGroup(child, { setTimer, clearTimer, kill }),
+      });
+    };
+    const onError = (error) => finish(error);
+    const onExit = (code, exitSignal) =>
+      finish(
+        new Error(
+          `OpenCode server exited before startup (${code ?? exitSignal ?? "unknown"}): ${stderr.trim().slice(-500)}`,
+        ),
+      );
+    const onAbort = () => finish(abortError(signal?.reason));
+    child.stdout?.on?.("data", (chunk) => {
+      stdout = (stdout + String(chunk)).slice(-8_192);
+      inspect();
+    });
+    child.stderr?.on?.("data", (chunk) => {
+      stderr = (stderr + String(chunk)).slice(-32_768);
+    });
+    child.once?.("error", onError);
+    child.once?.("exit", onExit);
+    signal?.addEventListener?.("abort", onAbort, { once: true });
+    timer = setTimer(
+      () => finish(new Error("OpenCode server did not become ready in time")),
+      startupTimeoutMs,
+    );
+    timer?.unref?.();
+  });
+}
+
+async function jsonRequest({
+  baseUrl,
+  directory,
+  pathname,
+  method = "GET",
+  body,
+  password,
+  username,
+  fetchImpl,
+  signal,
+  expected = [200],
+}) {
+  const response = await fetchImpl(withDirectory(baseUrl, pathname, directory), {
+    method,
+    headers: {
+      authorization: basicAuthorization(username, password),
+      ...(body === undefined ? {} : { "content-type": "application/json" }),
+    },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    signal,
+  });
+  if (!expected.includes(response.status)) {
+    const detail = await response.text().catch(() => "");
+    throw new Error(
+      `OpenCode ${method} ${pathname} failed (${response.status}): ${detail.slice(0, 300)}`,
+    );
+  }
+  if (response.status === 204) return null;
+  return response.json();
+}
+
+/**
+ * Execute one OpenCode prompt while hilos owns every permission response.
+ * @param {any} [options]
+ * @returns {Promise<{
+ *   status: number | null,
+ *   stdout: string,
+ *   stderr: string,
+ *   error: Error | null,
+ *   sessionId?: string,
+ *   aborted?: boolean,
+ * }>}
+ */
+export async function runOpenCodeHttpSession({
+  cmd = "opencode",
+  args = ["run"],
+  cwd,
+  prompt,
+  env,
+  timeoutMs = 30 * 60_000,
+  signal,
+  onData,
+  requestPermission,
+  getPermissionDecision,
+  fetchImpl = globalThis.fetch,
+  spawnImpl = spawn,
+  kill = process.kill,
+  randomPassword = () => randomBytes(24).toString("base64url"),
+  realpathImpl = realpathSync,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+  log = console,
+} = {}) {
+  if (!cwd) {
+    return { status: null, stdout: "", stderr: "", error: new Error("OpenCode requires cwd") };
+  }
+  if (typeof fetchImpl !== "function") {
+    return { status: null, stdout: "", stderr: "", error: new Error("OpenCode requires fetch") };
+  }
+  let parsed;
+  let canonicalCwd;
+  try {
+    parsed = parseOpenCodeRunArgs(args);
+    if (parsed.auto) {
+      throw new Error("The HTTP permission bridge must not run with --auto");
+    }
+    canonicalCwd = realpathImpl(cwd);
+    if (
+      parsed.directory != null &&
+      realpathImpl(parsed.directory) !== canonicalCwd
+    ) {
+      throw new Error(
+        "OpenCode --dir must match the runtime permission checkout",
+      );
+    }
+  } catch (error) {
+    return {
+      status: null,
+      stdout: "",
+      stderr: "",
+      error: error instanceof Error ? error : new Error(String(error)),
+    };
+  }
+
+  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", `OpenCode timed out after ${timeoutMs}ms`), timeoutMs)
+      : null;
+  timeout?.unref?.();
+
+  let server = null;
+  let relay = null;
+  let reader = null;
+  let sessionId = null;
+  let stdout = "";
+  let stderr = "";
+  let streamTask = null;
+  const completedTextParts = new Set();
+  let sawStopPart = false;
+  /** @type {(outcome: "idle" | "error") => void} */
+  let resolveDone = () => {};
+  const donePromise = new Promise((resolve) => {
+    resolveDone = resolve;
+  });
+  let promptSent = false;
+  const emitOutput = (value) => {
+    try {
+      onData?.(
+        parsed.format === "json"
+          ? `${JSON.stringify(value)}\n`
+          : `${String(value ?? "")}\n`,
+      );
+    } catch {
+      // Output observers never own session correctness.
+    }
+  };
+
+  try {
+    server = await startOpenCodeServer({
+      cmd,
+      cwd,
+      env,
+      serverArgs: parsed.serverArgs,
+      password: randomPassword(),
+      signal: controller.signal,
+      spawnImpl,
+      kill,
+      setTimer,
+      clearTimer,
+    });
+    const auth = {
+      baseUrl: server.baseUrl,
+      directory: cwd,
+      password: server.password,
+      username: server.username,
+      fetchImpl,
+      signal: controller.signal,
+    };
+    if (parsed.sessionId) {
+      const candidateSessionId = parsed.sessionId;
+      const session = await jsonRequest({
+        ...auth,
+        pathname: `/session/${encodeURIComponent(candidateSessionId)}`,
+        method: "GET",
+        expected: [200],
+      });
+      if (session?.id !== candidateSessionId) {
+        throw new Error("OpenCode resumed a different session than requested");
+      }
+      if (
+        typeof session?.directory !== "string" ||
+        realpathImpl(session.directory) !== canonicalCwd
+      ) {
+        throw new Error(
+          "OpenCode refused to resume a session from another project directory",
+        );
+      }
+      sessionId = candidateSessionId;
+    } else {
+      const session = await jsonRequest({
+        ...auth,
+        pathname: "/session",
+        method: "POST",
+        body: parsed.title ? { title: parsed.title } : {},
+        expected: [200],
+      });
+      const candidateSessionId = session?.id;
+      if (!candidateSessionId) {
+        throw new Error("OpenCode created a session without an id");
+      }
+      if (
+        typeof session?.directory !== "string" ||
+        realpathImpl(session.directory) !== canonicalCwd
+      ) {
+        throw new Error(
+          "OpenCode created the session in another project directory",
+        );
+      }
+      sessionId = candidateSessionId;
+    }
+    if (parsed.format === "json") {
+      emitOutput({
+        type: "step_start",
+        sessionID: sessionId,
+        part: {
+          id: `hilos_${sessionId}`,
+          sessionID: sessionId,
+          type: "step-start",
+        },
+      });
+    }
+
+    relay = createOpenCodePermissionRelay({
+      baseUrl: server.baseUrl,
+      directory: cwd,
+      password: server.password,
+      username: server.username,
+      requestPermission,
+      getPermissionDecision,
+      fetchImpl,
+      timeoutMs: Math.max(1, timeoutMs || 30 * 60_000),
+      signal: controller.signal,
+      onError: (error, context) => {
+        log?.error?.(`opencode permission ${context?.phase ?? "relay"}: ${error?.message ?? error}`);
+      },
+    });
+
+    const eventResponse = await fetchImpl(withDirectory(server.baseUrl, "/event", cwd), {
+      method: "GET",
+      headers: {
+        accept: "text/event-stream",
+        authorization: basicAuthorization(server.username, server.password),
+      },
+      signal: controller.signal,
+    });
+    if (!eventResponse.ok || !eventResponse.body) {
+      throw new Error(`OpenCode event subscription failed (${eventResponse.status})`);
+    }
+    reader = eventResponse.body.getReader();
+    const outputParser = createSseParser();
+    streamTask = (async () => {
+      for (;;) {
+        const { done: ended, value } = await reader.read();
+        if (ended) throw new Error("OpenCode event stream ended before the session became idle");
+        relay.push(value);
+        for (const message of outputParser.push(value)) {
+          let event;
+          try {
+            event = JSON.parse(message.data);
+          } catch {
+            continue;
+          }
+          const props = event?.properties;
+          if (event?.type === "message.part.updated") {
+            const part = props?.part;
+            if (part?.sessionID !== sessionId) continue;
+            const partType =
+              part?.type === "tool"
+                ? "tool_use"
+                : typeof part?.type === "string"
+                  ? part.type.replaceAll("-", "_")
+                  : null;
+            if (part?.type === "text") {
+              if (
+                !part?.time?.end ||
+                part?.synthetic ||
+                completedTextParts.has(part.id)
+              ) {
+                continue;
+              }
+              completedTextParts.add(part.id);
+              const text = String(part.text ?? "").trim();
+              if (text) {
+                stdout += `${text}\n`;
+                if (parsed.format === "json") {
+                  emitOutput({
+                    type: "text",
+                    sessionID: sessionId,
+                    part,
+                  });
+                } else {
+                  emitOutput(text);
+                }
+              }
+            } else if (
+              parsed.format === "json" &&
+              ["tool_use", "step_start", "step_finish"].includes(partType)
+            ) {
+              if (partType === "step_finish" && part?.reason === "stop") {
+                sawStopPart = true;
+              }
+              emitOutput({
+                type: partType,
+                sessionID: sessionId,
+                part,
+              });
+            }
+          } else if (event?.type === "session.error" && props?.sessionID === sessionId) {
+            const errorMessage = messageError(event);
+            stderr += `${errorMessage}\n`;
+            if (parsed.format === "json") {
+              emitOutput({
+                type: "error",
+                sessionID: sessionId,
+                error: {
+                  name: "SessionError",
+                  data: { message: errorMessage },
+                },
+              });
+            }
+            if (promptSent) resolveDone("error");
+          } else if (
+            event?.type === "session.status" &&
+            props?.sessionID === sessionId &&
+            props?.status?.type === "idle" &&
+            promptSent
+          ) {
+            if (parsed.format === "json" && !sawStopPart) {
+              sawStopPart = true;
+              emitOutput({
+                type: "step_finish",
+                sessionID: sessionId,
+                part: {
+                  id: `hilos_stop_${sessionId}`,
+                  sessionID: sessionId,
+                  type: "step-finish",
+                  reason: "stop",
+                },
+              });
+            }
+            resolveDone("idle");
+          } else if (
+            event?.type === "session.idle" &&
+            props?.sessionID === sessionId &&
+            promptSent
+          ) {
+            if (parsed.format === "json" && !sawStopPart) {
+              sawStopPart = true;
+              emitOutput({
+                type: "step_finish",
+                sessionID: sessionId,
+                part: {
+                  id: `hilos_stop_${sessionId}`,
+                  sessionID: sessionId,
+                  type: "step-finish",
+                  reason: "stop",
+                },
+              });
+            }
+            resolveDone("idle");
+          }
+        }
+      }
+    })().catch((error) => {
+      if (!controller.signal.aborted) {
+        stderr += `${error?.message ?? error}\n`;
+        resolveDone("error");
+      }
+    });
+
+    const model = openCodeModel(parsed.model);
+    promptSent = true;
+    await jsonRequest({
+      ...auth,
+      pathname: `/session/${encodeURIComponent(sessionId)}/prompt_async`,
+      method: "POST",
+      body: {
+        parts: [{ type: "text", text: String(prompt ?? "") }],
+        ...(model ? { model } : {}),
+        ...(parsed.agent ? { agent: parsed.agent } : {}),
+        ...(parsed.variant ? { variant: parsed.variant } : {}),
+      },
+      expected: [204],
+    });
+
+    const outcome = await Promise.race([
+      donePromise,
+      new Promise((_, reject) => {
+        if (controller.signal.aborted) reject(abortError(controller.signal.reason));
+        else {
+          controller.signal.addEventListener(
+            "abort",
+            () => reject(abortError(controller.signal.reason)),
+            { once: true },
+          );
+        }
+      }),
+    ]);
+    if (outcome === "error") {
+      // A terminal session/stream failure cannot wait behind a human decision:
+      // stop the run first, then close the relay so every pending ask receives a
+      // bounded reject and its durable hilos card settles fail closed.
+      abort("session-error", stderr.trim() || "OpenCode session failed");
+      await relay.close("session-error");
+    } else {
+      await relay.idle();
+    }
+    return {
+      status: outcome === "idle" && !stderr.trim() ? 0 : 1,
+      stdout: stdout.trimEnd(),
+      stderr: stderr.trimEnd(),
+      error: outcome === "error" ? new Error(stderr.trim() || "OpenCode session failed") : null,
+      sessionId,
+    };
+  } catch (error) {
+    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
+          ? error
+          : new Error(timedOut ? "OpenCode timed out" : String(error)),
+    };
+  } finally {
+    if (timeout != null) clearTimer(timeout);
+    signal?.removeEventListener?.("abort", onParentAbort);
+    if (sessionId && server && controller.signal.aborted) {
+      await jsonRequest({
+        baseUrl: server.baseUrl,
+        directory: cwd,
+        pathname: `/session/${encodeURIComponent(sessionId)}/abort`,
+        method: "POST",
+        password: server.password,
+        username: server.username,
+        fetchImpl,
+        signal: undefined,
+        expected: [200],
+      }).catch(() => {});
+    }
+    // Closing the relay fails any unresolved permission ask closed, then the
+    // stream and local server are torn down. No child survives this function.
+    await relay?.close("session-finished").catch(() => {});
+    controller.abort("session-finished");
+    await reader?.cancel("session-finished").catch(() => {});
+    await streamTask?.catch(() => {});
+    await server?.close().catch(() => {});
+  }
+}