backeer-opencode 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to `backeer-opencode` are documented here.
+
+## 0.1.0 - 2026-09-01
+
+- Publish OpenCode permission requests to Backeer.
+- Apply `once`, `always`, and `reject` decisions received from Backeer.
+- Publish `question.asked` and `question.v2.asked` notifications.
+- Publish one notification when a todo list transitions to fully completed.
+- Support environment, protected-file, XDG, npm, and side-loaded configuration.
+- Add idempotent command acknowledgement and duplicate notification protection.

package/LICENSE

@@ -0,0 +1,58 @@
+Backeer No-Derivatives Software License 1.0
+
+Copyright (c) 2026 Backeer. All rights reserved.
+
+1. Permission
+
+Subject to the terms of this license, Backeer grants you a limited,
+non-exclusive, non-transferable, non-sublicensable, royalty-free license to
+download, install, and execute exact, unmodified copies of the Software for the
+purpose of using Backeer services.
+
+You may reproduce and redistribute exact, unmodified copies of the Software
+solely when the complete package, this license, and all copyright, attribution,
+and proprietary notices are preserved intact. You may not charge a separate fee
+for the Software.
+
+2. No Modifications or Derivative Works
+
+You may not modify, adapt, translate, patch, merge, alter, or create derivative
+works based on the Software. You may not distribute, publish, sublicense, sell,
+or otherwise make available a modified version of the Software.
+
+3. No Reverse Engineering
+
+Except to the limited extent that applicable law expressly prohibits this
+restriction, you may not reverse engineer, decompile, disassemble, or otherwise
+attempt to derive non-public implementation details from the Software.
+
+4. Ownership and Trademarks
+
+The Software is licensed, not sold. Backeer retains all right, title, and
+interest in and to the Software. This license does not grant permission to use
+Backeer names, logos, or trademarks except as necessary to identify the
+unmodified Software.
+
+5. Termination
+
+This license terminates automatically if you breach any of its terms. Upon
+termination, you must stop using the Software and delete all copies in your
+possession or control.
+
+6. Disclaimer of Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, TITLE, AND NON-INFRINGEMENT.
+
+7. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, BACKEER WILL NOT BE LIABLE FOR ANY
+INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR FOR ANY
+LOSS OF DATA, PROFITS, REVENUE, OR BUSINESS, ARISING FROM OR RELATED TO THE
+SOFTWARE OR THIS LICENSE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+8. Entire License
+
+This license is the complete agreement governing the Software unless Backeer
+and you enter into a separate written agreement signed by Backeer.

package/README.md

@@ -0,0 +1,186 @@
+# Backeer for OpenCode
+
+`backeer-opencode` connects OpenCode to Backeer. It sends mobile notifications
+for permission requests, questions, and completed todo lists. While a permission
+is pending, it also consumes an authenticated Backeer command stream so an
+authorized user can answer **Allow once**, **Always allow**, or **Reject** from
+the Backeer iOS application.
+
+The plugin uses outbound HTTPS only. It does not start a server or require an
+inbound firewall rule.
+
+## Requirements
+
+- OpenCode with server plugin support
+- Node.js 18 or newer for the local installer and tests
+- Outbound HTTPS access to `external-gateway.backeer.com:443`
+- A Backeer source ingest token
+
+Create a separate Backeer source and ingest token for every server. Sharing a
+token causes permission commands to be broadcast to every OpenCode process that
+uses that token and weakens host-level auditing and revocation.
+
+## Local installation
+
+The local installer copies a single dependency-free plugin file into OpenCode's
+global plugin directory. OpenCode discovers it automatically.
+
+```sh
+cd opencode-plugin
+node bin/backeer-opencode.js --token-file /path/from/your/secret-manager/backeer-token
+```
+
+The resulting files are:
+
+```text
+~/.config/opencode/plugins/backeer-permission.js
+~/.config/opencode/secrets/backeer-ingest-token
+```
+
+The token file is written with mode `0600`. When `XDG_CONFIG_HOME` is set, the
+installer and plugin use `$XDG_CONFIG_HOME/opencode` instead. To update only the
+plugin while preserving the existing token, run:
+
+```sh
+node bin/backeer-opencode.js
+```
+
+Restart OpenCode after installation or update.
+
+## Installation from npm
+
+Install the package in OpenCode's global configuration:
+
+```sh
+opencode plugin backeer-opencode -g
+```
+
+Alternatively, add it to `~/.config/opencode/opencode.json` manually:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["backeer-opencode"]
+}
+```
+
+OpenCode installs configured npm plugins automatically. Restart OpenCode after
+installation. The npm package never contains a token; provide the token using
+one of the methods below.
+
+If npm package loading is not available in a particular OpenCode installation,
+install the package as a side-loaded plugin instead:
+
+```sh
+npx backeer-opencode@latest --token-file /path/from/your/secret-manager/backeer-token
+```
+
+Use either the configured npm plugin or the side-loaded form, not both. Loading
+both forms would register the integration twice.
+
+## Authentication
+
+The plugin checks these locations in order:
+
+1. `BACKEER_INGEST_TOKEN`
+2. `BACKEER_TOKEN_FILE`
+3. `~/.config/opencode/secrets/backeer-ingest-token`
+
+Do not commit the token to an OpenCode configuration file, shell script, plugin
+file, or repository. Do not reuse an application-session token; this plugin
+requires a source ingest token.
+
+## Configuration
+
+The default gateway origin is `https://external-gateway.backeer.com`. These
+environment variables are supported:
+
+| Variable | Purpose |
+|---|---|
+| `BACKEER_INGEST_TOKEN` | Source credential; takes precedence over a token file |
+| `BACKEER_TOKEN_FILE` | Absolute path to a protected token file |
+| `BACKEER_ORIGIN` | Gateway origin; HTTPS is required |
+| `BACKEER_NOTIFY_PERMISSIONS` | Set to `false` to disable permission notifications and remote replies |
+| `BACKEER_NOTIFY_QUESTIONS` | Set to `false` to disable question notifications |
+| `BACKEER_NOTIFY_TODOS` | Set to `false` to disable todo-completion notifications |
+
+For npm installations, non-secret options can also be supplied through the
+OpenCode plugin tuple syntax:
+
+```json
+{
+  "plugin": [
+    [
+      "backeer-opencode",
+      {
+        "permissions": true,
+        "questions": true,
+        "todos": true
+      }
+    ]
+  ]
+}
+```
+
+Supported options are `origin`, `tokenFile`, `permissions`, `questions`, and
+`todos`. The token itself is deliberately not a plugin option.
+
+## Events and decisions
+
+The plugin publishes:
+
+| OpenCode event | Backeer behavior |
+|---|---|
+| `permission.asked` | Notification plus remote decision support |
+| `question.asked` | Notification-only question card |
+| `question.v2.asked` | Notification-only question card, including plan-mode questions |
+| `todo.updated` | One notification when a non-empty list transitions to fully completed |
+
+Permission commands are delivered at least once. The plugin caches terminal
+acknowledgements and resends the same acknowledgement on redelivery without
+applying the OpenCode decision twice. Duplicate event callbacks are suppressed
+within the plugin process and Backeer uses the stable `externalId` as the
+cross-process idempotency key.
+
+## Verification
+
+```sh
+npm run check
+npm run pack:check
+npm run publish:check
+```
+
+## Publishing
+
+Maintainers can publish a release after authenticating the `Backeer` npm
+account:
+
+```sh
+npm login
+npm whoami
+npm run publish:check
+npm publish --access public
+```
+
+Increment `version` before every later release. npm does not allow an existing
+name and version pair to be overwritten.
+
+For support, contact [hello@backeer.com](mailto:hello@backeer.com).
+
+## License
+
+Copyright © 2026 Backeer. The package may be installed and used in its
+unmodified form. Modification, adaptation, derivative works, reverse
+engineering, and distribution of modified versions are prohibited. See
+[`LICENSE`](LICENSE) for the complete terms.
+
+After restarting OpenCode, trigger a harmless permission such as `git status`.
+Verify that one Backeer notification arrives, answer it from iOS, and confirm
+that OpenCode receives the selected decision.
+
+## Upgrade behavior
+
+Normal OpenCode upgrades do not remove locally installed plugins because they
+live in the OpenCode configuration directory. Re-run the installer to deploy a
+new Backeer plugin version. Preserve the token file and run the test suite after
+OpenCode upgrades that change plugin events or the generated API client.

package/bin/backeer-opencode.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+import {
+  chmodSync,
+  copyFileSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+function usage(exitCode = 0) {
+  console.log(`Usage: backeer-opencode [options]
+
+Options:
+  --config-dir PATH   OpenCode config directory (default: XDG_CONFIG_HOME/opencode)
+  --token-file PATH   Read the Backeer ingest token from PATH
+  --token-stdin       Read the Backeer ingest token from standard input
+  --help              Show this help
+
+If no token option is supplied, an existing token is preserved.`)
+  process.exit(exitCode)
+}
+
+function parseArguments(arguments_) {
+  const result = {}
+  for (let index = 0; index < arguments_.length; index++) {
+    const argument = arguments_[index]
+    if (argument === "--help") usage()
+    if (argument === "--token-stdin") {
+      result.tokenStdin = true
+      continue
+    }
+    if (argument === "--config-dir" || argument === "--token-file") {
+      const value = arguments_[++index]
+      if (!value) usage(1)
+      result[argument === "--config-dir" ? "configDir" : "tokenFile"] = value
+      continue
+    }
+    console.error(`Unknown option: ${argument}`)
+    usage(1)
+  }
+  if (result.tokenStdin && result.tokenFile) {
+    throw new Error("Use either --token-stdin or --token-file, not both")
+  }
+  return result
+}
+
+function defaultConfigDirectory() {
+  const base = process.env.XDG_CONFIG_HOME?.trim()
+  return base ? join(base, "opencode") : join(homedir(), ".config", "opencode")
+}
+
+function writeSecretAtomically(path, token) {
+  if (!token) throw new Error("The Backeer ingest token is empty")
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+  const temporaryPath = `${path}.${process.pid}.tmp`
+  writeFileSync(temporaryPath, `${token}\n`, { encoding: "utf8", mode: 0o600 })
+  chmodSync(temporaryPath, 0o600)
+  renameSync(temporaryPath, path)
+}
+
+const arguments_ = parseArguments(process.argv.slice(2))
+const configDirectory = resolve(arguments_.configDir ?? defaultConfigDirectory())
+const pluginDirectory = join(configDirectory, "plugins")
+const secretPath = join(configDirectory, "secrets", "backeer-ingest-token")
+const packageDirectory = resolve(dirname(fileURLToPath(import.meta.url)), "..")
+const sourcePath = join(packageDirectory, "src", "index.js")
+// Keep the legacy filename so upgrading an existing Backeer installation
+// replaces it instead of loading two copies of the same plugin.
+const installedPath = join(pluginDirectory, "backeer-permission.js")
+
+mkdirSync(pluginDirectory, { recursive: true })
+copyFileSync(sourcePath, installedPath)
+chmodSync(installedPath, 0o644)
+
+if (arguments_.tokenFile) {
+  writeSecretAtomically(secretPath, readFileSync(resolve(arguments_.tokenFile), "utf8").trim())
+} else if (arguments_.tokenStdin) {
+  writeSecretAtomically(secretPath, readFileSync(0, "utf8").trim())
+}
+
+console.log(`Installed Backeer OpenCode plugin: ${installedPath}`)
+console.log(
+  arguments_.tokenFile || arguments_.tokenStdin
+    ? `Installed protected ingest token: ${secretPath}`
+    : `Token unchanged; expected at ${secretPath} or in BACKEER_INGEST_TOKEN`,
+)
+console.log("Restart OpenCode to load the plugin.")

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "backeer-opencode",
+  "version": "0.1.0",
+  "description": "Backeer notifications and remote permission decisions for OpenCode",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "backeer-opencode": "bin/backeer-opencode.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "node --check src/index.js && node --check bin/backeer-opencode.js && node --test",
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run",
+    "publish:check": "npm publish --dry-run --access public",
+    "prepublishOnly": "npm run check"
+  },
+  "keywords": [
+    "backeer",
+    "opencode",
+    "plugin",
+    "notifications"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": {
+    "name": "Backeer",
+    "email": "hello@backeer.com",
+    "url": "https://backeer.com/"
+  },
+  "homepage": "https://backeer.com/",
+  "bugs": {
+    "email": "hello@backeer.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "SEE LICENSE IN LICENSE"
+}

package/src/index.js

@@ -0,0 +1,716 @@
+import { readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+const DEFAULT_ORIGIN = "https://external-gateway.backeer.com"
+const ACTION_PROTOCOL = "opencode-permission/v1"
+const RETRY_DELAYS_MS = [0, 500, 1500]
+const MAX_COMPLETED_COMMANDS = 500
+const MAX_TRACKED_ITEMS = 500
+const ALLOWED_DECISIONS = new Set(["once", "always", "reject"])
+
+class HttpError extends Error {
+  constructor(message, status, responseBody = "") {
+    super(message)
+    this.name = "HttpError"
+    this.status = status
+    this.responseBody = responseBody
+  }
+}
+
+const limit = (value, length = 1000) =>
+  String(value ?? "").slice(0, length)
+
+function defaultConfigDirectory() {
+  const base = process.env.XDG_CONFIG_HOME?.trim()
+  return base ? join(base, "opencode") : join(homedir(), ".config", "opencode")
+}
+
+function loadToken(tokenFile) {
+  const environmentToken = process.env.BACKEER_INGEST_TOKEN?.trim()
+  if (environmentToken) return environmentToken
+
+  try {
+    return readFileSync(tokenFile, "utf8").trim()
+  } catch {
+    return ""
+  }
+}
+
+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())
+}
+
+function loadConfig(options = {}) {
+  const origin = new URL(
+    options.origin ?? process.env.BACKEER_ORIGIN ?? DEFAULT_ORIGIN,
+  )
+  if (origin.protocol !== "https:") {
+    throw new Error("Backeer origin must use HTTPS")
+  }
+
+  const tokenFile =
+    options.tokenFile ??
+    process.env.BACKEER_TOKEN_FILE ??
+    join(defaultConfigDirectory(), "secrets", "backeer-ingest-token")
+
+  return {
+    origin,
+    eventsEndpoint: new URL("/v1/events", origin),
+    commandStreamEndpoint: new URL("/v1/commands/stream", origin),
+    token: loadToken(tokenFile),
+    tokenFile,
+    permissions: enabled(
+      options.permissions ?? process.env.BACKEER_NOTIFY_PERMISSIONS,
+    ),
+    questions: enabled(
+      options.questions ?? process.env.BACKEER_NOTIFY_QUESTIONS,
+    ),
+    todos: enabled(options.todos ?? process.env.BACKEER_NOTIFY_TODOS),
+  }
+}
+
+function isRetryable(status) {
+  return status === 429 || status >= 500
+}
+
+function isAbortError(error) {
+  return error instanceof Error && error.name === "AbortError"
+}
+
+function sleep(milliseconds, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve()
+      return
+    }
+
+    const timeout = setTimeout(done, milliseconds)
+
+    function done() {
+      clearTimeout(timeout)
+      signal?.removeEventListener("abort", done)
+      resolve()
+    }
+
+    signal?.addEventListener("abort", done, { once: true })
+  })
+}
+
+async function postJsonWithRetry(config, url, body, options = {}) {
+  const retryDelays = options.retryDelays ?? RETRY_DELAYS_MS
+
+  for (let attempt = 0; attempt < retryDelays.length; attempt++) {
+    if (retryDelays[attempt] > 0) {
+      await sleep(retryDelays[attempt], options.signal)
+    }
+    if (options.signal?.aborted) throw new DOMException("Aborted", "AbortError")
+
+    const controller = new AbortController()
+    const abort = () => controller.abort()
+    const timeout = setTimeout(abort, options.timeoutMs ?? 5000)
+    options.signal?.addEventListener("abort", abort, { once: true })
+
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${config.token}`,
+          "Content-Type": "application/json",
+          ...options.headers,
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      })
+      const responseBody = limit(await response.text(), 1000)
+
+      if (response.ok) return { status: response.status, responseBody }
+      if (!isRetryable(response.status) || attempt === retryDelays.length - 1) {
+        throw new HttpError(
+          `HTTP request failed with status ${response.status}`,
+          response.status,
+          responseBody,
+        )
+      }
+    } catch (error) {
+      if (options.signal?.aborted) throw new DOMException("Aborted", "AbortError")
+      if (error instanceof HttpError) throw error
+      if (attempt === retryDelays.length - 1) throw error
+    } finally {
+      clearTimeout(timeout)
+      options.signal?.removeEventListener("abort", abort)
+    }
+  }
+
+  throw new Error("HTTP retry loop ended unexpectedly")
+}
+
+function permissionIdentity(request) {
+  const requestID = request.id ?? request.requestID
+  const sessionID = request.sessionID
+  if (typeof requestID !== "string" || typeof sessionID !== "string") return
+
+  return {
+    requestID,
+    sessionID,
+    externalId: `opencode:${sessionID}:${requestID}`,
+  }
+}
+
+async function publishPermission(config, request, directory, identity) {
+  const permissionType = request.permission ?? request.action ?? "unknown"
+  const resources = Array.isArray(request.patterns)
+    ? request.patterns.join(", ")
+    : Array.isArray(request.resources)
+      ? request.resources.join(", ")
+      : ""
+
+  const payload = [
+    { key: "Permission", value: limit(permissionType) },
+    { key: "Session", value: limit(identity.sessionID) },
+    { key: "Request ID", value: limit(identity.requestID) },
+    { key: "Patterns", value: limit(resources) },
+    { key: "Working directory", value: limit(directory) },
+    { key: "Action protocol", value: ACTION_PROTOCOL },
+    { key: "Available decisions", value: "once, always, reject" },
+  ].filter((item) => item.value.length > 0)
+
+  const result = await postJsonWithRetry(config, config.eventsEndpoint, {
+    type: "application",
+    severity: "warning",
+    title: `OpenCode permission required: ${limit(permissionType, 200)}`,
+    body: resources
+      ? `OpenCode is waiting for approval to access: ${limit(resources, 500)}`
+      : `OpenCode is waiting for approval for: ${limit(permissionType, 500)}`,
+    payload,
+    externalId: identity.externalId,
+    timestamp: new Date().toISOString(),
+    notify: true,
+    direction: "in",
+  })
+  console.log(`[backeer] permission event accepted (${result.status})`)
+}
+
+function questionIdentity(request) {
+  const requestID = request.id ?? request.requestID
+  const sessionID = request.sessionID
+  if (typeof requestID !== "string" || typeof sessionID !== "string") return
+
+  return {
+    requestID,
+    sessionID,
+    externalId: `opencode-question:${sessionID}:${requestID}`,
+  }
+}
+
+function formatQuestionOptions(options) {
+  if (!Array.isArray(options)) return ""
+
+  return options
+    .map((option) => {
+      const label = limit(option?.label, 200)
+      const description = limit(option?.description, 500)
+      if (!label) return ""
+      return description ? `${label} — ${description}` : label
+    })
+    .filter(Boolean)
+    .join(" | ")
+}
+
+async function resolveSessionTitle(client, directory, sessionID) {
+  if (typeof client?.session?.get !== "function") return ""
+
+  try {
+    const result = await client.session.get({
+      path: { id: sessionID },
+      query: { directory },
+      throwOnError: true,
+    })
+    return limit((result?.data ?? result)?.title)
+  } catch (error) {
+    console.error(`[backeer] could not resolve session title: ${limit(error, 500)}`)
+    return ""
+  }
+}
+
+async function publishQuestion(config, request, identity, client, directory) {
+  const questions = Array.isArray(request.questions) ? request.questions : []
+  if (questions.length === 0) return
+
+  const sessionTitle = await resolveSessionTitle(
+    client,
+    directory,
+    identity.sessionID,
+  )
+  const payload = [
+    { key: "OpenCode session", value: sessionTitle },
+    ...questions.flatMap((question, index) => {
+      const suffix = questions.length > 1 ? ` ${index + 1}` : ""
+      return [
+        { key: `Question title${suffix}`, value: limit(question?.header) },
+        { key: `Question${suffix}`, value: limit(question?.question) },
+        {
+          key: `Options${suffix}`,
+          value: limit(formatQuestionOptions(question?.options)),
+        },
+      ]
+    }),
+  ].filter((item) => item.value.length > 0)
+
+  const firstQuestion = questions[0]
+  const body = questions
+    .map((question) => {
+      const header = limit(question?.header, 200)
+      const text = limit(question?.question, 500)
+      const options = limit(formatQuestionOptions(question?.options), 500)
+      return [header, text, options ? `Options: ${options}` : ""]
+        .filter(Boolean)
+        .join("\n")
+    })
+    .join("\n\n")
+
+  const result = await postJsonWithRetry(config, config.eventsEndpoint, {
+    type: "application",
+    severity: "info",
+    title: `OpenCode question: ${limit(firstQuestion?.header, 200) || "Question"}`,
+    body: limit(body, 2000),
+    payload,
+    externalId: identity.externalId,
+    timestamp: new Date().toISOString(),
+    notify: true,
+    direction: "in",
+  })
+  console.log(`[backeer] question event accepted (${result.status})`)
+}
+
+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")
+}
+
+async function publishTodoCompletion(config, request, eventID, client, directory) {
+  const todos = request.todos
+  const sessionTitle = await resolveSessionTitle(
+    client,
+    directory,
+    request.sessionID,
+  )
+  const correlation =
+    typeof eventID === "string" && eventID.length > 0
+      ? limit(eventID, 200)
+      : stableHash(JSON.stringify(todos))
+  const externalId = `opencode-todo:${request.sessionID}:${correlation}`
+  const visibleTodos = todos.slice(0, 20)
+  const payload = [
+    { key: "OpenCode session", value: sessionTitle },
+    { key: "Completed tasks", value: String(todos.length) },
+    ...visibleTodos.flatMap((todo, index) => [
+      { key: `Task ${index + 1}`, value: limit(todo?.content) },
+      { key: `Priority ${index + 1}`, value: limit(todo?.priority, 100) },
+    ]),
+    ...(todos.length > visibleTodos.length
+      ? [{ key: "Additional tasks", value: String(todos.length - visibleTodos.length) }]
+      : []),
+  ].filter((item) => item.value.length > 0)
+
+  const summary = todos
+    .slice(0, 5)
+    .map((todo) => limit(todo?.content, 200))
+    .filter(Boolean)
+    .join(" • ")
+  const location = sessionTitle ? ` in ${sessionTitle}` : ""
+  const body = [
+    `All ${todos.length} OpenCode tasks completed${location}.`,
+    summary,
+  ].filter(Boolean).join("\n")
+
+  const result = await postJsonWithRetry(config, config.eventsEndpoint, {
+    type: "application",
+    severity: "info",
+    title: "OpenCode todo list completed",
+    body: limit(body, 2000),
+    payload,
+    externalId,
+    timestamp: new Date().toISOString(),
+    notify: true,
+    direction: "in",
+  })
+  console.log(`[backeer] todo completion accepted (${result.status})`)
+}
+
+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") }
+}
+
+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) }
+}
+
+async function consumeSse(response, state, onCommand, signal) {
+  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) {
+            console.error("[backeer] command stream returned invalid JSON")
+            continue
+          }
+          throw error
+        }
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => {})
+  }
+}
+
+async function runCommandStream(config, { 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)
+    } catch (error) {
+      if (signal.aborted || isAbortError(error)) return
+      const message = error instanceof HttpError
+        ? `${error.message}: ${error.responseBody}`
+        : limit(error, 500)
+      if (message !== lastLoggedError) {
+        console.error(`[backeer] ${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)
+    }
+  }
+}
+
+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)
+}
+
+function rememberBounded(map, key, value) {
+  map.delete(key)
+  map.set(key, value)
+  while (map.size > MAX_TRACKED_ITEMS) map.delete(map.keys().next().value)
+}
+
+/**
+ * OpenCode server plugin entrypoint.
+ *
+ * Supported options: origin, tokenFile, permissions, questions, todos.
+ * 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 = {}) {
+  let config
+  try {
+    config = loadConfig(options)
+  } catch (error) {
+    console.error(`[backeer] plugin disabled: ${limit(error, 500)}`)
+    return {}
+  }
+
+  if (!config.token) {
+    console.error(
+      `[backeer] plugin disabled: set BACKEER_INGEST_TOKEN or create ${config.tokenFile}`,
+    )
+    return {}
+  }
+
+  const pendingByExternalID = new Map()
+  const externalIDByRequestID = new Map()
+  const processingCommands = new Set()
+  const completedCommands = new Map()
+  const todoCompletionBySessionID = new Map()
+  const publishedPermissions = new Map()
+  const publishedQuestions = 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) => console.error(`[backeer] command ACK retry failed: ${limit(error, 500)}`),
+      )
+      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)
+      console.error(`[backeer] permission command failed: ${limit(error, 500)}`)
+    } finally {
+      processingCommands.delete(command.id)
+    }
+
+    acknowledgement = {
+      ...acknowledgement,
+      type: "opencode_permission_reply_ack",
+      externalId: command.externalId,
+      processedAt: new Date().toISOString(),
+    }
+    rememberBounded(completedCommands, command.id, acknowledgement)
+    await acknowledgeCommand(config, command.id, acknowledgement).catch((error) => {
+      console.error(`[backeer] command ACK failed: ${limit(error, 500)}`)
+    })
+    stopCommandStreamIfIdle()
+  }
+
+  function ensureCommandStream() {
+    if (disposed || commandStream || pendingByExternalID.size === 0) return
+
+    const controller = new AbortController()
+    const current = {
+      controller,
+      task: runCommandStream(config, {
+        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 {
+    event: async ({ event }) => {
+      if (config.permissions && event.type === "permission.asked") {
+        const identity = permissionIdentity(event.properties)
+        if (!identity) {
+          console.error("[backeer] permission event is missing IDs")
+          return
+        }
+
+        pendingByExternalID.set(identity.externalId, { ...identity, directory })
+        externalIDByRequestID.set(identity.requestID, identity.externalId)
+        ensureCommandStream()
+
+        if (publishedPermissions.has(identity.externalId)) return
+        rememberBounded(publishedPermissions, identity.externalId, true)
+        void publishPermission(config, event.properties, directory, identity).catch(
+          (error) => console.error(`[backeer] permission webhook failed: ${limit(error, 500)}`),
+        )
+        return
+      }
+
+      if (config.permissions && event.type === "permission.replied") {
+        removePendingByRequestID(event.properties.requestID ?? event.properties.id)
+        stopCommandStreamIfIdle()
+        return
+      }
+
+      if (config.todos && event.type === "todo.updated") {
+        const { sessionID, todos } = event.properties
+        if (typeof sessionID !== "string" || !Array.isArray(todos)) {
+          console.error("[backeer] 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,
+          event.properties,
+          event.id,
+          client,
+          directory,
+        ).catch(
+          (error) => console.error(`[backeer] todo webhook failed: ${limit(error, 500)}`),
+        )
+        return
+      }
+
+      if (
+        config.questions &&
+        (event.type === "question.asked" || event.type === "question.v2.asked")
+      ) {
+        const identity = questionIdentity(event.properties)
+        if (!identity) {
+          console.error("[backeer] question event is missing IDs")
+          return
+        }
+        if (publishedQuestions.has(identity.externalId)) return
+        rememberBounded(publishedQuestions, identity.externalId, true)
+
+        void publishQuestion(
+          config,
+          event.properties,
+          identity,
+          client,
+          directory,
+        ).catch(
+          (error) => console.error(`[backeer] question webhook failed: ${limit(error, 500)}`),
+        )
+      }
+    },
+    dispose: async () => {
+      disposed = true
+      commandStream?.controller.abort()
+      await commandStream?.task.catch(() => {})
+      pendingByExternalID.clear()
+      externalIDByRequestID.clear()
+      todoCompletionBySessionID.clear()
+      publishedPermissions.clear()
+      publishedQuestions.clear()
+    },
+  }
+}