backeer-opencode 0.1.1 → 0.1.3

package/src/permission-controller.js

@@ -0,0 +1,183 @@
+import { HttpError, postJsonWithRetry } from "./http.js"
+import { runCommandStream } from "./sse.js"
+import { rememberBounded } from "./utilities.js"
+
+const ALLOWED_DECISIONS = new Set(["once", "always", "reject"])
+const DECISION_LABELS = {
+  once: "Allow once",
+  always: "Always allow",
+  reject: "Reject",
+}
+
+async function replyToOpenCode(client, pending, decision) {
+  const result = await client.postSessionIdPermissionsPermissionId({
+    path: { id: pending.sessionID, permissionID: pending.requestID },
+    query: { directory: pending.directory },
+    body: { response: decision },
+    throwOnError: true,
+  })
+
+  if (result?.data === false || result === false) {
+    throw new HttpError("OpenCode did not apply the permission reply", 409)
+  }
+}
+
+async function acknowledgeCommand(config, commandID, acknowledgement) {
+  const url = new URL(
+    `/v1/commands/${encodeURIComponent(commandID)}/ack`,
+    config.origin,
+  )
+  await postJsonWithRetry(config, url, acknowledgement)
+}
+
+export function createPermissionController({
+  config,
+  reporter,
+  client,
+  directory,
+}) {
+  const pendingByExternalID = new Map()
+  const externalIDByRequestID = new Map()
+  const processingCommands = new Set()
+  const completedCommands = new Map()
+  const publishedPermissions = new Map()
+  let commandStream
+  let disposed = false
+
+  function removePendingByRequestID(requestID) {
+    const externalId = externalIDByRequestID.get(requestID)
+    if (!externalId) return
+    externalIDByRequestID.delete(requestID)
+    pendingByExternalID.delete(externalId)
+  }
+
+  function stopCommandStreamIfIdle() {
+    if (pendingByExternalID.size === 0) commandStream?.controller.abort()
+  }
+
+  async function handleCommand(command) {
+    if (!command || typeof command !== "object") return
+    if (command.type !== "opencode_permission_reply") return
+    if (typeof command.id !== "string" || command.id.length > 200) return
+
+    const previousAcknowledgement = completedCommands.get(command.id)
+    if (previousAcknowledgement) {
+      await acknowledgeCommand(config, command.id, previousAcknowledgement)
+        .catch((error) => reporter.warning("Decision receipt retry failed", error))
+      return
+    }
+    if (processingCommands.has(command.id)) return
+    if (typeof command.externalId !== "string") return
+
+    const pending = pendingByExternalID.get(command.externalId)
+    if (!pending) return
+
+    processingCommands.add(command.id)
+    let acknowledgement
+    try {
+      if (!ALLOWED_DECISIONS.has(command.decision)) {
+        acknowledgement = { status: "rejected", errorCode: "invalid_decision" }
+      } else {
+        const expiresAt = Date.parse(command.expiresAt)
+        if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) {
+          acknowledgement = { status: "expired", decision: command.decision }
+        } else if (command.decision === "always" && command.confirmed !== true) {
+          acknowledgement = {
+            status: "rejected",
+            decision: command.decision,
+            errorCode: "confirmation_required",
+          }
+        } else {
+          await replyToOpenCode(client, pending, command.decision)
+          acknowledgement = { status: "applied", decision: command.decision }
+          removePendingByRequestID(pending.requestID)
+        }
+      }
+    } catch (error) {
+      const stale = error instanceof HttpError && error.status === 404
+      acknowledgement = {
+        status: stale ? "stale" : "failed",
+        decision: ALLOWED_DECISIONS.has(command.decision)
+          ? command.decision
+          : undefined,
+        errorCode: stale ? "permission_not_found" : "opencode_reply_failed",
+      }
+      if (stale) removePendingByRequestID(pending.requestID)
+      reporter.error("Decision could not be applied", error)
+    } finally {
+      processingCommands.delete(command.id)
+    }
+
+    acknowledgement = {
+      ...acknowledgement,
+      type: "opencode_permission_reply_ack",
+      externalId: command.externalId,
+      processedAt: new Date().toISOString(),
+    }
+    rememberBounded(completedCommands, command.id, acknowledgement)
+
+    if (acknowledgement.status === "applied") {
+      reporter.applied(
+        `Decision applied: ${DECISION_LABELS[acknowledgement.decision]}`,
+      )
+    } else if (acknowledgement.status === "expired") {
+      reporter.warning("Decision expired before it could be applied")
+    } else if (acknowledgement.status === "stale") {
+      reporter.warning("Permission was already answered locally")
+    } else if (acknowledgement.status === "rejected") {
+      reporter.warning("Decision was rejected by validation")
+    }
+
+    await acknowledgeCommand(config, command.id, acknowledgement).catch((error) => {
+      reporter.warning("Decision receipt could not be sent", error)
+    })
+    stopCommandStreamIfIdle()
+  }
+
+  function ensureCommandStream() {
+    if (disposed || commandStream || pendingByExternalID.size === 0) return
+
+    const controller = new AbortController()
+    const current = {
+      controller,
+      task: runCommandStream(config, reporter, {
+        signal: controller.signal,
+        hasPending: () => pendingByExternalID.size > 0,
+        onCommand: handleCommand,
+      }),
+    }
+    commandStream = current
+    void current.task.finally(() => {
+      if (commandStream === current) commandStream = undefined
+      if (!disposed && pendingByExternalID.size > 0) ensureCommandStream()
+    })
+  }
+
+  return {
+    register(identity) {
+      pendingByExternalID.set(identity.externalId, { ...identity, directory })
+      externalIDByRequestID.set(identity.requestID, identity.externalId)
+      ensureCommandStream()
+
+      if (publishedPermissions.has(identity.externalId)) return false
+      rememberBounded(publishedPermissions, identity.externalId, true)
+      return true
+    },
+
+    resolveLocally(requestID) {
+      removePendingByRequestID(requestID)
+      stopCommandStreamIfIdle()
+    },
+
+    async dispose() {
+      disposed = true
+      commandStream?.controller.abort()
+      await commandStream?.task.catch(() => {})
+      pendingByExternalID.clear()
+      externalIDByRequestID.clear()
+      processingCommands.clear()
+      completedCommands.clear()
+      publishedPermissions.clear()
+    },
+  }
+}

package/src/plugin.js

@@ -0,0 +1,143 @@
+import { loadConfig } from "./config.js"
+import {
+  permissionIdentity,
+  publishPermission,
+  publishQuestion,
+  publishTodoCompletion,
+  questionIdentity,
+} from "./event-publishers.js"
+import { createPermissionController } from "./permission-controller.js"
+import { createConsoleReporter } from "./reporter.js"
+import { rememberBounded } from "./utilities.js"
+
+/**
+ * OpenCode server plugin entrypoint.
+ *
+ * Supported options: origin, tokenFile, permissions, questions, todos, logLevel.
+ * The ingest token is intentionally accepted only through the environment or a
+ * protected file so it cannot accidentally be committed in opencode.json.
+ */
+export default async function BackeerPlugin({ client, directory }, options = {}) {
+  const bootstrapReporter = createConsoleReporter(
+    options.logLevel ?? process.env.BACKEER_LOG_LEVEL,
+  )
+  let config
+  try {
+    config = loadConfig(options)
+  } catch (error) {
+    bootstrapReporter.error("Plugin disabled — invalid configuration", error)
+    return {}
+  }
+
+  const reporter = createConsoleReporter(config.logLevel)
+
+  if (!config.token) {
+    reporter.error(
+      "Plugin disabled — run: npx backeer-opencode@latest configure",
+      `Token not found at ${config.tokenFile}`,
+    )
+    return {}
+  }
+
+  const permissionController = createPermissionController({
+    config,
+    reporter,
+    client,
+    directory,
+  })
+  const todoCompletionBySessionID = new Map()
+  const publishedQuestions = new Map()
+
+  async function handlePermissionAsked(event) {
+    const identity = permissionIdentity(event.properties)
+    if (!identity) {
+      reporter.error("Permission event is missing correlation IDs")
+      return
+    }
+    if (!permissionController.register(identity)) return
+
+    void publishPermission(
+      config,
+      reporter,
+      event.properties,
+      directory,
+      identity,
+    ).catch((error) => reporter.error("Permission request could not be sent", error))
+  }
+
+  async function handleTodoUpdated(event) {
+    const { sessionID, todos } = event.properties
+    if (typeof sessionID !== "string" || !Array.isArray(todos)) {
+      reporter.error("Todo event is missing a valid session or list")
+      return
+    }
+
+    const isComplete = todos.length > 0 &&
+      todos.every((todo) => todo?.status === "completed")
+    const wasComplete = todoCompletionBySessionID.get(sessionID) === true
+    rememberBounded(todoCompletionBySessionID, sessionID, isComplete)
+    if (!isComplete || wasComplete) return
+
+    void publishTodoCompletion(
+      config,
+      reporter,
+      event.properties,
+      event.id,
+      client,
+      directory,
+    ).catch((error) => reporter.error("Todo completion could not be sent", error))
+  }
+
+  async function handleQuestionAsked(event) {
+    const identity = questionIdentity(event.properties)
+    if (!identity) {
+      reporter.error("Question event is missing correlation IDs")
+      return
+    }
+    if (publishedQuestions.has(identity.externalId)) return
+    rememberBounded(publishedQuestions, identity.externalId, true)
+
+    void publishQuestion(
+      config,
+      reporter,
+      event.properties,
+      identity,
+      client,
+      directory,
+    ).catch((error) => reporter.error("Question could not be sent", error))
+  }
+
+  return {
+    event: async ({ event }) => {
+      if (config.permissions && event.type === "permission.asked") {
+        await handlePermissionAsked(event)
+        return
+      }
+
+      if (config.permissions && event.type === "permission.replied") {
+        permissionController.resolveLocally(
+          event.properties.requestID ?? event.properties.id,
+        )
+        return
+      }
+
+      if (config.todos && event.type === "todo.updated") {
+        await handleTodoUpdated(event)
+        return
+      }
+
+      if (
+        config.questions &&
+        (event.type === "question.asked" || event.type === "question.v2.asked")
+      ) {
+        await handleQuestionAsked(event)
+      }
+    },
+
+    dispose: async () => {
+      await permissionController.dispose()
+      todoCompletionBySessionID.clear()
+      publishedQuestions.clear()
+    },
+  }
+}

package/src/reporter.js

@@ -0,0 +1,60 @@
+import { limit } from "./utilities.js"
+
+const LOG_LEVELS = new Set(["silent", "error", "info", "debug"])
+const LOG_RANK = { silent: 0, error: 1, info: 2, debug: 3 }
+const LOG_DEDUPLICATION_MS = 30_000
+
+export function normalizeLogLevel(value) {
+  const level = String(value ?? "info").trim().toLowerCase()
+  return LOG_LEVELS.has(level) ? level : "info"
+}
+
+export function createConsoleReporter(levelValue) {
+  const level = normalizeLogLevel(levelValue)
+  const useColor = Boolean(process.stdout?.isTTY) &&
+    !("NO_COLOR" in process.env) && process.env.TERM !== "dumb"
+  const recentlyEmitted = new Map()
+
+  const decorate = (code, text) => useColor ? `\u001b[${code}m${text}\u001b[0m` : text
+  const symbols = {
+    info: decorate("36", "◆"),
+    success: decorate("32", "◆"),
+    applied: decorate("32", "✓"),
+    warning: decorate("33", "!"),
+    error: decorate("31", "×"),
+    debug: decorate("2", "·"),
+  }
+  const brand = decorate("1", "Backeer")
+
+  function emit(requiredLevel, kind, message, detail, deduplicate = false) {
+    if (LOG_RANK[level] < LOG_RANK[requiredLevel]) return
+
+    const key = `${kind}:${message}`
+    const now = Date.now()
+    if (deduplicate) {
+      const previous = recentlyEmitted.get(key)
+      if (previous && now - previous < LOG_DEDUPLICATION_MS) return
+      recentlyEmitted.delete(key)
+      recentlyEmitted.set(key, now)
+      while (recentlyEmitted.size > 100) {
+        recentlyEmitted.delete(recentlyEmitted.keys().next().value)
+      }
+    }
+
+    const technical = level === "debug" && detail
+      ? decorate("2", ` · ${limit(detail, 500)}`)
+      : ""
+    const line = `${symbols[kind]} ${brand}  ${message}${technical}`
+    if (kind === "error" || kind === "warning") console.error(line)
+    else console.log(line)
+  }
+
+  return {
+    info: (message, detail) => emit("info", "info", message, detail),
+    success: (message, detail) => emit("info", "success", message, detail),
+    applied: (message, detail) => emit("info", "applied", message, detail),
+    warning: (message, detail) => emit("error", "warning", message, detail, true),
+    error: (message, detail) => emit("error", "error", message, detail, true),
+    debug: (message, detail) => emit("debug", "debug", message, detail),
+  }
+}

package/src/sse.js

@@ -0,0 +1,139 @@
+import { HttpError, isAbortError, sleep } from "./http.js"
+import { limit } from "./utilities.js"
+
+export function parseSseFrame(frame) {
+  const data = []
+  let event = "message"
+  let id
+
+  for (const line of frame.split(/\r?\n/)) {
+    if (!line || line.startsWith(":")) continue
+    const separator = line.indexOf(":")
+    const field = separator === -1 ? line : line.slice(0, separator)
+    let value = separator === -1 ? "" : line.slice(separator + 1)
+    if (value.startsWith(" ")) value = value.slice(1)
+
+    if (field === "event") event = value
+    if (field === "id") id = value
+    if (field === "data") data.push(value)
+  }
+
+  if (data.length === 0) return
+  return { event, id, data: data.join("\n") }
+}
+
+export function nextSseFrame(buffer) {
+  const lfIndex = buffer.indexOf("\n\n")
+  const crlfIndex = buffer.indexOf("\r\n\r\n")
+  if (lfIndex === -1 && crlfIndex === -1) return
+
+  if (crlfIndex !== -1 && (lfIndex === -1 || crlfIndex < lfIndex)) {
+    return {
+      frame: buffer.slice(0, crlfIndex),
+      rest: buffer.slice(crlfIndex + 4),
+    }
+  }
+  return { frame: buffer.slice(0, lfIndex), rest: buffer.slice(lfIndex + 2) }
+}
+
+export async function consumeSse(response, state, onCommand, signal, reporter) {
+  if (!response.body) throw new Error("Backeer command stream has no body")
+
+  const reader = response.body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ""
+
+  try {
+    while (!signal.aborted) {
+      const item = await reader.read()
+      if (item.done) break
+      buffer += decoder.decode(item.value, { stream: true })
+
+      for (;;) {
+        const next = nextSseFrame(buffer)
+        if (!next) break
+        buffer = next.rest
+        const message = parseSseFrame(next.frame)
+        if (!message) continue
+        if (message.id) state.lastEventID = message.id
+        if (message.event !== "message" && message.event !== "command") continue
+
+        try {
+          await onCommand(JSON.parse(message.data))
+        } catch (error) {
+          if (error instanceof SyntaxError) {
+            reporter.error("Invalid command received", "SSE data is not valid JSON")
+            continue
+          }
+          throw error
+        }
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => {})
+  }
+}
+
+export async function runCommandStream(
+  config,
+  reporter,
+  { signal, hasPending, onCommand },
+) {
+  const state = { lastEventID: "" }
+  let reconnectDelay = 1000
+  let lastLoggedError = ""
+
+  while (!signal.aborted && hasPending()) {
+    try {
+      const headers = {
+        Accept: "text/event-stream",
+        Authorization: `Bearer ${config.token}`,
+      }
+      if (state.lastEventID) headers["Last-Event-ID"] = state.lastEventID
+
+      const response = await fetch(config.commandStreamEndpoint, {
+        headers,
+        signal,
+      })
+      if (!response.ok) {
+        const responseBody = limit(await response.text(), 500)
+        throw new HttpError(
+          `Backeer command stream failed with status ${response.status}`,
+          response.status,
+          responseBody,
+        )
+      }
+      if (!response.headers.get("content-type")?.includes("text/event-stream")) {
+        throw new Error("Backeer command stream returned an invalid content type")
+      }
+
+      reconnectDelay = 1000
+      lastLoggedError = ""
+      await consumeSse(response, state, onCommand, signal, reporter)
+    } catch (error) {
+      if (signal.aborted || isAbortError(error)) return
+      const message = error instanceof HttpError
+        ? `${error.message}: ${error.responseBody}`
+        : limit(error, 500)
+      if (message !== lastLoggedError) {
+        const authenticationFailure = error instanceof HttpError &&
+          [401, 403].includes(error.status)
+        reporter.error(
+          authenticationFailure
+            ? "Authentication failed — run: npx backeer-opencode@latest configure"
+            : "Connection interrupted — retrying",
+          message,
+        )
+        lastLoggedError = message
+      }
+      if (error instanceof HttpError && [401, 403, 404].includes(error.status)) {
+        reconnectDelay = 60_000
+      }
+    }
+
+    if (!signal.aborted && hasPending()) {
+      await sleep(reconnectDelay, signal)
+      reconnectDelay = Math.min(reconnectDelay * 2, 60_000)
+    }
+  }
+}

package/src/utilities.js

@@ -0,0 +1,25 @@
+const MAX_TRACKED_ITEMS = 500
+
+export const limit = (value, length = 1000) =>
+  String(value ?? "").slice(0, length)
+
+export function enabled(value, fallback = true) {
+  if (typeof value === "boolean") return value
+  if (typeof value !== "string") return fallback
+  return !["0", "false", "no", "off"].includes(value.trim().toLowerCase())
+}
+
+export function stableHash(value) {
+  let hash = 2166136261
+  for (let index = 0; index < value.length; index++) {
+    hash ^= value.charCodeAt(index)
+    hash = Math.imul(hash, 16777619)
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0")
+}
+
+export function rememberBounded(map, key, value) {
+  map.delete(key)
+  map.set(key, value)
+  while (map.size > MAX_TRACKED_ITEMS) map.delete(map.keys().next().value)
+}