hilos-agent 0.6.0 → 0.9.0

package/src/opencode-permissions.mjs

@@ -0,0 +1,654 @@
+// OpenCode runtime-permission relay (0593).
+//
+// This module is deliberately dependency-light and handler-agnostic. It owns
+// only the vendor boundary:
+//   1. parse OpenCode's SSE stream without assuming chunk == event;
+//   2. normalize both permission.asked generations into one hilos-shaped ask;
+//   3. serialize asks within a session while allowing different sessions to
+//      wait independently;
+//   4. poll injected hilos callbacks under a hard, abort-aware deadline; and
+//   5. always answer OpenCode once/always/reject, with reject as every failure
+//      mode's fail-closed result.
+//
+// handler.mjs intentionally does not import this yet. Its later integration can
+// create one relay per attached OpenCode server and feed response-body chunks
+// into relay.push().
+
+const TERMINAL_REPLIES = new Map([
+  ["allowed_once", "once"],
+  ["allowed_always", "always"],
+  ["denied", "reject"],
+  ["expired", "reject"],
+  ["revoked", "reject"],
+]);
+
+const DEFAULT_TIMEOUT_MS = 30 * 60_000;
+const DEFAULT_POLL_MS = 1_000;
+const DEFAULT_REPLY_TIMEOUT_MS = 5_000;
+const DEFAULT_REPLY_ATTEMPTS = 2;
+const DEFAULT_SEEN_LIMIT = 1_000;
+
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function exactArray(value, { optional = false } = {}) {
+  // Preserve the source payload exactly. The hilos MCP boundary validates type,
+  // size, and secret safety and rejects the whole ask when it cannot render it
+  // verbatim; filtering here could hide authority-bearing entries.
+  if (Array.isArray(value)) return [...value];
+  return optional && value == null ? [] : value;
+}
+
+function parseJson(value) {
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+function basicAuthorization(username, password) {
+  const token = Buffer.from(`${username}:${password ?? ""}`, "utf8").toString("base64");
+  return `Basic ${token}`;
+}
+
+function abortError(reason = "aborted") {
+  const error = new Error(String(reason || "aborted"));
+  error.name = "AbortError";
+  return error;
+}
+
+function raceWithAbort(value, signal) {
+  if (!signal) return Promise.resolve(value);
+  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(value).then(
+      (result) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(result);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+function defaultSleep(ms, signal) {
+  if (signal?.aborted) return Promise.reject(abortError(signal.reason));
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(done, Math.max(0, ms));
+    function done() {
+      signal?.removeEventListener("abort", cancelled);
+      resolve();
+    }
+    function cancelled() {
+      clearTimeout(timer);
+      reject(abortError(signal?.reason));
+    }
+    signal?.addEventListener("abort", cancelled, { once: true });
+  });
+}
+
+/**
+ * Parse an SSE byte/string stream. `push()` and `flush()` return complete SSE
+ * messages shaped as `{ event, data, id? }`; data remains a string so callers
+ * can decide their own JSON/error policy.
+ */
+export function createSseParser() {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let eventName = "";
+  let data = [];
+  let lastEventId = "";
+
+  function dispatch(out) {
+    if (data.length === 0) {
+      eventName = "";
+      return;
+    }
+    out.push({
+      event: eventName || "message",
+      data: data.join("\n"),
+      ...(lastEventId ? { id: lastEventId } : {}),
+    });
+    eventName = "";
+    data = [];
+  }
+
+  function consumeLine(line, out) {
+    if (line === "") {
+      dispatch(out);
+      return;
+    }
+    if (line.startsWith(":")) return;
+    const colon = line.indexOf(":");
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let value = colon === -1 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "event") eventName = value;
+    else if (field === "data") data.push(value);
+    else if (field === "id" && !value.includes("\0")) lastEventId = value;
+  }
+
+  function drain(final) {
+    const out = [];
+    let start = 0;
+    for (let i = 0; i < buffer.length; i++) {
+      const char = buffer[i];
+      if (char !== "\n" && char !== "\r") continue;
+      // A CR at the end of a non-final chunk may be the first half of CRLF.
+      if (char === "\r" && i === buffer.length - 1 && !final) break;
+      consumeLine(buffer.slice(start, i), out);
+      if (char === "\r" && buffer[i + 1] === "\n") i++;
+      start = i + 1;
+    }
+    buffer = buffer.slice(start);
+    if (final && buffer) {
+      consumeLine(buffer, out);
+      buffer = "";
+    }
+    if (final) dispatch(out);
+    return out;
+  }
+
+  return {
+    push(chunk) {
+      if (chunk instanceof Uint8Array) buffer += decoder.decode(chunk, { stream: true });
+      else buffer += String(chunk ?? "");
+      return drain(false);
+    },
+    flush() {
+      buffer += decoder.decode();
+      return drain(true);
+    },
+  };
+}
+
+/**
+ * Normalize a raw OpenCode SSE message/event into the vendor-neutral request
+ * consumed by hilos. Returns null for every non-permission or malformed event.
+ *
+ * Supports all observed envelopes:
+ *   { event:"permission.asked", data:"{...request}" }
+ *   { data:"{\"type\":\"permission.asked\",\"properties\":{...}}" }
+ *   { directory, payload:{ type, properties } } (OpenCode global event stream)
+ *   { type:"permission.v2.asked", properties:{...} }
+ */
+export function normalizeOpenCodePermissionEvent(input) {
+  if (!isObject(input)) return null;
+  const sseType = typeof input.event === "string" ? input.event : null;
+  let envelope = "data" in input ? parseJson(input.data) : input;
+  if (!isObject(envelope)) return null;
+  if (isObject(envelope.payload)) envelope = envelope.payload;
+  const eventType =
+    typeof envelope.type === "string" ? envelope.type : sseType === "message" ? null : sseType;
+  if (eventType !== "permission.asked" && eventType !== "permission.v2.asked") return null;
+  const request = isObject(envelope.properties) ? envelope.properties : envelope;
+  const vendorRequestId = typeof request.id === "string" ? request.id : null;
+  const sessionId = typeof request.sessionID === "string" ? request.sessionID : null;
+  if (!vendorRequestId || !sessionId) return null;
+
+  const legacy = eventType === "permission.asked";
+  const action = legacy ? request.permission : request.action;
+  if (typeof action !== "string" || !action) return null;
+  const rawSource = legacy ? request.tool : request.source;
+  const source = isObject(rawSource)
+    ? legacy && rawSource.type == null
+      ? { type: "tool", ...rawSource }
+      : { ...rawSource }
+    : null;
+
+  return {
+    vendor: "opencode",
+    vendorRequestId,
+    sessionId,
+    action,
+    resources: exactArray(legacy ? request.patterns : request.resources),
+    suggestedSave: exactArray(legacy ? request.always : request.save, {
+      optional: true,
+    }),
+    metadata: isObject(request.metadata) ? { ...request.metadata } : {},
+    source,
+    eventType,
+  };
+}
+
+function decisionState(value) {
+  if (typeof value === "string") return value;
+  if (!isObject(value)) return null;
+  if (typeof value.state === "string") return value.state;
+  if (isObject(value.request) && typeof value.request.state === "string") {
+    return value.request.state;
+  }
+  if (isObject(value.permission) && typeof value.permission.state === "string") {
+    return value.permission.state;
+  }
+  if (isObject(value.data)) return decisionState(value.data);
+  return null;
+}
+
+/**
+ * Map a hilos permission row/decision to OpenCode's reply enum.
+ * Pending/unknown values return null so the relay keeps polling.
+ */
+export function mapOpenCodePermissionDecision(value) {
+  const state = decisionState(value);
+  // A prior hilos rule may auto-resolve a new ask. That authorizes this one
+  // execution only; replying `always` would let OpenCode persist the new ask's
+  // unapproved save suggestions. Only an explicit human Always decision may
+  // produce the vendor's persistent reply.
+  if (state === "allowed_always" && isObject(value) && value.autoAllowed === true) {
+    return "once";
+  }
+  return state ? TERMINAL_REPLIES.get(state) ?? null : null;
+}
+
+/**
+ * POST one terminal reply to OpenCode's legacy/current permission endpoint.
+ * @param {{
+ *   baseUrl: string,
+ *   directory: string,
+ *   requestId: string,
+ *   reply: string,
+ *   password: string,
+ *   username?: string,
+ *   fetchImpl?: typeof globalThis.fetch,
+ *   signal?: AbortSignal,
+ * }} options
+ */
+export async function postOpenCodePermissionReply({
+  baseUrl,
+  directory,
+  requestId,
+  reply,
+  password,
+  username = "opencode",
+  fetchImpl = globalThis.fetch,
+  signal,
+}) {
+  if (typeof fetchImpl !== "function") throw new Error("OpenCode permission reply requires fetch");
+  if (!baseUrl) throw new Error("OpenCode permission reply requires baseUrl");
+  if (!directory) throw new Error("OpenCode permission reply requires directory");
+  if (!requestId) throw new Error("OpenCode permission reply requires requestId");
+  if (!["once", "always", "reject"].includes(reply)) {
+    throw new Error("Invalid OpenCode permission reply");
+  }
+  const url = new URL(`/permission/${encodeURIComponent(requestId)}/reply`, baseUrl);
+  url.searchParams.set("directory", directory);
+  const response = await fetchImpl(url, {
+    method: "POST",
+    headers: {
+      authorization: basicAuthorization(username, password),
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({ reply }),
+    signal,
+  });
+  if (!response?.ok) {
+    throw new Error(`OpenCode permission reply failed (${response?.status ?? "transport"})`);
+  }
+  return response;
+}
+
+/**
+ * Subscribe to OpenCode's instance SSE stream and feed it into a relay.
+ *
+ * `directory` is not optional at the protocol boundary: OpenCode uses it to
+ * route the request to the correct project instance. The caller should run
+ * this concurrently with its HTTP session runner and abort the supplied signal
+ * during teardown. This helper deliberately does not launch `opencode run
+ * --attach`: that CLI is itself a permission responder and would race hilos.
+ * @param {{
+ *   baseUrl: string,
+ *   directory: string,
+ *   password: string,
+ *   username?: string,
+ *   relay: {push: (value: Uint8Array) => unknown[], flush: () => unknown[]},
+ *   fetchImpl?: typeof globalThis.fetch,
+ *   signal?: AbortSignal,
+ * }} options
+ */
+export async function consumeOpenCodePermissionEvents({
+  baseUrl,
+  directory,
+  password,
+  username = "opencode",
+  relay,
+  fetchImpl = globalThis.fetch,
+  signal,
+}) {
+  if (typeof fetchImpl !== "function") throw new Error("OpenCode event stream requires fetch");
+  if (!baseUrl) throw new Error("OpenCode event stream requires baseUrl");
+  if (!directory) throw new Error("OpenCode event stream requires directory");
+  if (!relay || typeof relay.push !== "function" || typeof relay.flush !== "function") {
+    throw new Error("OpenCode event stream requires a permission relay");
+  }
+  const url = new URL("/event", baseUrl);
+  url.searchParams.set("directory", directory);
+  const response = await fetchImpl(url, {
+    method: "GET",
+    headers: {
+      accept: "text/event-stream",
+      authorization: basicAuthorization(username, password),
+    },
+    signal,
+  });
+  if (!response?.ok) {
+    throw new Error(`OpenCode event subscription failed (${response?.status ?? "transport"})`);
+  }
+  if (!response.body) throw new Error("OpenCode event subscription returned no body");
+
+  const reader = response.body.getReader();
+  let requests = 0;
+  try {
+    for (;;) {
+      const { done, value } = await raceWithAbort(reader.read(), signal);
+      if (done) break;
+      requests += relay.push(value).length;
+    }
+    requests += relay.flush().length;
+    return { requests };
+  } finally {
+    if (signal?.aborted) await reader.cancel(signal.reason).catch(() => {});
+    reader.releaseLock();
+  }
+}
+
+/**
+ * Create a bounded permission relay.
+ *
+ * Callback contract:
+ *   requestPermission(request, { signal, deadlineAt })
+ *     Creates (or idempotently returns) the durable hilos permission request.
+ *   getPermissionDecision(handle, { request, signal, deadlineAt, failClosed })
+ *     Returns a row/state. Pending/unknown values are polled again; terminal
+ *     states are mapped by mapOpenCodePermissionDecision(). On a relay failure,
+ *     one source-bound call with failClosed:true expires the durable card.
+ */
+export function createOpenCodePermissionRelay(options = {}) {
+  const {
+    baseUrl,
+    directory,
+    password,
+    username = "opencode",
+    requestPermission,
+    getPermissionDecision,
+    fetchImpl = globalThis.fetch,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    pollIntervalMs = DEFAULT_POLL_MS,
+    replyTimeoutMs = DEFAULT_REPLY_TIMEOUT_MS,
+    replyAttempts = DEFAULT_REPLY_ATTEMPTS,
+    seenLimit = DEFAULT_SEEN_LIMIT,
+    now = () => Date.now(),
+    sleep = defaultSleep,
+    setTimer = (fn, ms) => setTimeout(fn, ms),
+    clearTimer = (timer) => clearTimeout(timer),
+    signal,
+    onError,
+    onResult,
+  } = options;
+  if (typeof requestPermission !== "function") {
+    throw new Error("OpenCode permission relay requires requestPermission");
+  }
+  if (typeof getPermissionDecision !== "function") {
+    throw new Error("OpenCode permission relay requires getPermissionDecision");
+  }
+
+  const parser = createSseParser();
+  const relayController = new AbortController();
+  const seen = new Map();
+  const sessionTails = new Map();
+  let closed = false;
+
+  const forwardAbort = () => relayController.abort(signal?.reason ?? "aborted");
+  if (signal?.aborted) forwardAbort();
+  else signal?.addEventListener("abort", forwardAbort, { once: true });
+
+  function reportError(error, context) {
+    try {
+      onError?.(error, context);
+    } catch {
+      // Observability must never break the mechanical permission gate.
+    }
+  }
+
+  async function sendReply(request, reply) {
+    let lastError = null;
+    const attempts = Math.max(1, Math.floor(replyAttempts));
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimer(
+        () => controller.abort("reply-timeout"),
+        Math.max(1, replyTimeoutMs),
+      );
+      try {
+        await raceWithAbort(
+          postOpenCodePermissionReply({
+            baseUrl,
+            directory,
+            requestId: request.vendorRequestId,
+            reply,
+            password,
+            username,
+            fetchImpl,
+            signal: controller.signal,
+          }),
+          controller.signal,
+        );
+        return { replied: true, replyAttempts: attempt };
+      } catch (error) {
+        lastError = error;
+        reportError(error, { phase: "reply", request, reply, attempt });
+      } finally {
+        clearTimer(timer);
+      }
+    }
+    return { replied: false, replyAttempts: attempts, replyError: lastError };
+  }
+
+  async function processRequest(request, receivedAt) {
+    const deadlineAt = receivedAt + Math.max(0, timeoutMs);
+    const controller = new AbortController();
+    let abortKind = null;
+    let decision = null;
+    let handle = null;
+    let reply = "reject";
+    let outcome = "transport-error";
+    const onRelayAbort = () => {
+      abortKind = "aborted";
+      controller.abort(relayController.signal.reason ?? "aborted");
+    };
+    if (relayController.signal.aborted) onRelayAbort();
+    else relayController.signal.addEventListener("abort", onRelayAbort, { once: true });
+    const remaining = deadlineAt - now();
+    const deadlineTimer =
+      remaining > 0
+        ? setTimer(() => {
+            abortKind = "timeout";
+            controller.abort("timeout");
+          }, remaining)
+        : null;
+    if (remaining <= 0) {
+      abortKind = "timeout";
+      controller.abort("timeout");
+    }
+
+    try {
+      if (controller.signal.aborted) throw abortError(controller.signal.reason);
+      handle = await raceWithAbort(
+        requestPermission(request, { signal: controller.signal, deadlineAt }),
+        controller.signal,
+      );
+      decision = handle;
+      reply = mapOpenCodePermissionDecision(handle);
+      while (!reply) {
+        if (now() >= deadlineAt) {
+          abortKind = "timeout";
+          controller.abort("timeout");
+          throw abortError("timeout");
+        }
+        decision = await raceWithAbort(
+          getPermissionDecision(handle, {
+            request,
+            signal: controller.signal,
+            deadlineAt,
+          }),
+          controller.signal,
+        );
+        reply = mapOpenCodePermissionDecision(decision);
+        if (reply) break;
+        const waitMs = Math.min(Math.max(1, pollIntervalMs), Math.max(1, deadlineAt - now()));
+        await raceWithAbort(sleep(waitMs, controller.signal), controller.signal);
+      }
+      outcome = decisionState(decision) ?? "resolved";
+    } catch (error) {
+      reply = "reject";
+      outcome = abortKind === "timeout" ? "timeout" : abortKind === "aborted" ? "aborted" : "transport-error";
+      reportError(error, { phase: "decision", request, outcome });
+      // OpenCode has already been failed closed. Settle the matching durable
+      // card too, using a fresh bounded signal: the run/deadline signal is
+      // necessarily aborted here and must not strand visible state as pending.
+      if (handle) {
+        const settlementController = new AbortController();
+        const settlementTimer = setTimer(
+          () => settlementController.abort("settlement-timeout"),
+          Math.max(1, replyTimeoutMs),
+        );
+        try {
+          await raceWithAbort(
+            getPermissionDecision(handle, {
+              request,
+              signal: settlementController.signal,
+              deadlineAt,
+              failClosed: true,
+            }),
+            settlementController.signal,
+          );
+        } catch (settlementError) {
+          reportError(settlementError, {
+            phase: "settlement",
+            request,
+            outcome,
+          });
+        } finally {
+          clearTimer(settlementTimer);
+        }
+      }
+    } finally {
+      if (deadlineTimer != null) clearTimer(deadlineTimer);
+      relayController.signal.removeEventListener("abort", onRelayAbort);
+    }
+
+    // Do not reuse the run/deadline signal here: even cancellation and timeout
+    // must get one bounded chance to close the pending OpenCode tool call.
+    const delivery = await sendReply(request, reply);
+    const result = {
+      vendorRequestId: request.vendorRequestId,
+      sessionId: request.sessionId,
+      reply,
+      outcome,
+      ...delivery,
+    };
+    try {
+      onResult?.(result, request);
+    } catch {
+      // Result observers are optional and non-authoritative.
+    }
+    return result;
+  }
+
+  function trimSeen() {
+    if (seen.size <= Math.max(1, seenLimit)) return;
+    for (const [id, record] of seen) {
+      if (!record.done) continue;
+      seen.delete(id);
+      if (seen.size <= seenLimit) break;
+    }
+  }
+
+  function handleRequest(request) {
+    if (!request?.vendorRequestId || !request?.sessionId) return null;
+    const duplicate = seen.get(request.vendorRequestId);
+    if (duplicate) return duplicate.promise;
+    const receivedAt = now();
+    const previous = sessionTails.get(request.sessionId) ?? Promise.resolve();
+    const record = { done: false, promise: null };
+    const task = previous
+      .catch(() => {})
+      .then(() => processRequest(request, receivedAt));
+    record.promise = task;
+    seen.set(request.vendorRequestId, record);
+    const tail = task
+      .then(
+        () => {},
+        () => {},
+      )
+      .finally(() => {
+        record.done = true;
+        if (sessionTails.get(request.sessionId) === tail) {
+          sessionTails.delete(request.sessionId);
+        }
+        trimSeen();
+      });
+    sessionTails.set(request.sessionId, tail);
+    return task;
+  }
+
+  function handleEvent(event) {
+    const request = normalizeOpenCodePermissionEvent(event);
+    return request ? handleRequest(request) : null;
+  }
+
+  function schedule(messages) {
+    const requests = [];
+    for (const message of messages) {
+      const request = normalizeOpenCodePermissionEvent(message);
+      if (!request) continue;
+      requests.push(request);
+      void handleRequest(request);
+    }
+    return requests;
+  }
+
+  async function idle() {
+    while (sessionTails.size) {
+      await Promise.all([...sessionTails.values()]);
+    }
+  }
+
+  return {
+    push(chunk) {
+      if (closed) return [];
+      return schedule(parser.push(chunk));
+    },
+    flush() {
+      if (closed) return [];
+      return schedule(parser.flush());
+    },
+    handleEvent,
+    handleRequest,
+    result(requestId) {
+      return seen.get(requestId)?.promise ?? null;
+    },
+    pendingCount() {
+      let count = 0;
+      for (const record of seen.values()) if (!record.done) count++;
+      return count;
+    },
+    idle,
+    async close(reason = "relay-closed") {
+      if (closed) return idle();
+      schedule(parser.flush());
+      closed = true;
+      relayController.abort(reason);
+      signal?.removeEventListener("abort", forwardAbort);
+      await idle();
+    },
+  };
+}