backeer-opencode 0.3.2 → 0.5.1

package/docs/live-control.md

@@ -0,0 +1,80 @@
+# OpenCode live control
+
+The plugin exposes a small, opt-in HTTP bridge **inside the existing OpenCode process**. Output travels over persistent SSE; explicit instructions use authenticated POST requests. The local MCP adapter turns these into tools that Codex can call. No hosted relay, new cloud server, public port, WebSocket service, or terminal OCR is required.
+
+```text
+Codex — MCP stdio — local adapter — SSH tunnel — OpenCode plugin
+                                 ← SSE events
+                                 → POST instruction
+```
+
+This channel reports OpenCode sessions, assistant text, selected tool output and status. It is not an arbitrary SSH shell or a byte-for-byte terminal recorder. Existing mobile permissions and questions stay on the existing Backeer path. The adapter cannot approve them.
+
+## Setup
+
+1. Install this version of `backeer-opencode` on the OpenCode host and on the computer running Codex. Enable the bridge using the configuration documented in the package README. It binds only to `127.0.0.1`; the default port is `43871`.
+2. Use a **separate random live-control token**, not the mobile ingest token. Keep matching token files on both computers. Files must be regular, owned by the current account and inaccessible to other users (`chmod 600`). Do not put token values in prompts, URLs, shell arguments or MCP configuration. The local adapter reads only the protected file. Token rotation requires restarting the configured plugin and adapter.
+3. Forward the port using an existing authorized SSH host configuration:
+
+   ```sh
+   while true; do
+     ssh -N -T -o BatchMode=yes -o ExitOnForwardFailure=yes \
+       -o ConnectTimeout=3 -o ServerAliveInterval=15 -o ServerAliveCountMax=3 \
+       -L 127.0.0.1:43871:127.0.0.1:43871 existing-ssh-host
+     sleep 3
+   done
+   ```
+
+   This uses your existing SSH authentication and host verification. It does not create credentials or change server firewall rules. `BatchMode` requires an already usable noninteractive SSH identity. The loop restarts a failed tunnel after three seconds; SSH keepalives detect a silent broken transport. Keep this tunnel supervisor running while tracking work. For an existing externally managed tunnel, configure equivalent reconnect behavior instead of starting a duplicate. For different concurrent OpenCode processes, give each bridge/tunnel a distinct port.
+4. Register the `backeer-opencode-mcp` executable as a **local stdio MCP server** in the desired Codex client. Example configuration (replace absolute paths):
+
+   ```toml
+   [mcp_servers.backeer_opencode_live]
+   command = "/absolute/path/to/node"
+   args = ["/absolute/path/to/opencode-plugin/bin/backeer-opencode-mcp.js"]
+
+   [mcp_servers.backeer_opencode_live.env]
+   BACKEER_LIVE_URL = "http://127.0.0.1:43871"
+   BACKEER_LIVE_TOKEN_FILE = "/absolute/private/path/live-control.token"
+   ```
+
+   These are **adapter** settings. No configuration is written automatically. The MCP process uses stdout exclusively for protocol messages; startup errors go to stderr. Node.js 18 or later is supported through the official MCP SDK v1 line. See the [official stdio/server documentation](https://ts.sdk.modelcontextprotocol.io/server).
+
+## Tools and normal workflow
+
+| Tool | Behavior |
+| --- | --- |
+| `session_status` | List observed project sessions or inspect an exact existing `sessionId`. |
+| `read_events` | Read only unread buffered events, optionally after an explicit cursor. |
+| `wait_for_events` | Wait on the persistent SSE connection for up to 25 seconds after setup; no periodic status polling. |
+| `send_instruction` | POST a prompt to an exact existing session using a caller-generated `requestId`. |
+
+First list sessions and select the intended one. OpenCode V2's public plugin context does not expose a full session list: this version lists sessions observed through live events or a successful exact-ID lookup. To attach an existing idle V2 session that has not emitted an event since plugin startup, supply its known ID to `session_status`; no new session is created. Deleted or moved sessions are revalidated rather than trusted from cache.
+
+Follow events by passing the returned cursor to `wait_for_events`; omit the cursor to consume this adapter process's unread events. Before the first instruction, the adapter captures a pre-command cursor so immediate output is not skipped. Output is untrusted data, not new instructions. Do not send a new task merely because an agent is quiet. An accepted instruction means delivery was accepted, **not** that the work succeeded. Confirm subsequent output and test results.
+
+Status and pending-approval events arrive as they occur. V2 text is emitted when each text unit ends and tool output when each tool finishes, without waiting for the whole agent run. Raw reasoning and split token deltas are not exported. Long-running commands do not become a byte-for-byte streaming terminal. Truncated text/tool output carries `data.truncated: true`; redaction is best effort, not a guarantee against every secret format.
+
+Use a unique request ID for a new instruction. If delivery is uncertain, retry the **same ID and exact prompt**. Changing the prompt with an existing ID is rejected. Deduplication lasts 24 hours in the same bridge process; restarting the bridge clears that memory. A full deduplication cache rejects new requests rather than evicting still-protected IDs. Instructions are not automatically retried. Busy sessions can reject an instruction; read status and wait instead of duplicating work.
+
+The bridge retains at most 1,024 instruction identities for that 24-hour window.
+
+## Bounds, reconnects and gaps
+
+The adapter retains at most 500 events / 1 MiB in memory. A normal read returns at most 20 events / 32,000 characters; explicit bounds allow at most 100 events / 64,000 characters. Large individual events request a larger bounded read rather than silently skipping them. Bridge events may themselves be truncated and carry truncation metadata; a tool cannot reconstruct omitted text.
+
+There is **no maximum connection lifetime or agent-output idle timeout**. The bridge emits a tiny heartbeat every 15 seconds even when a task produces no output for hours. A 45-second watchdog measures missing **transport traffic**, not missing agent replies. If heartbeats disappear, the client discards the dead socket and reconnects. The 25-second MCP wait limit only ends that tool call; it leaves the underlying SSE connection running.
+
+After each failed attempt or detected disconnect, the client retries every **three seconds**, without a retry-count limit or exponential backoff, until it connects or the MCP process is explicitly closed. The OpenCode V2 event subscription also retries after three seconds. Initial unavailability and authentication errors do not permanently stop reconnection; an invalid credential still cannot access anything and must be corrected through protected configuration. Individual HTTP/handshake timeouts are not task deadlines. Internet loss, host shutdown, application exit or a terminated tunnel can physically interrupt a connection; retrying SSE cannot recreate an SSH process, which is why the tunnel itself needs the supervisor described above.
+
+If the bridge restarted or retained history expired, the result has `gap` instead of claiming complete output. The transport reconnects automatically from the new bridge cursor and buffers new events, but the history gap remains visible until acknowledged. Inspect `session_status` and explicitly call `read_events` or `wait_for_events` with `afterCursor = gap.cursor` to acknowledge resynchronization. Old events are not recovered by that action. Do not automatically resend the last instruction after a gap.
+
+## Mobile connection notifications
+
+With the existing Backeer ingest credential configured on the OpenCode host, the bridge sends a push-enabled application event when its **last live SSE reader disconnects**, and another when a reader returns. The first normal connection, individual retry attempts and deliberate plugin shutdown do not produce alerts. Multiple simultaneous readers count as one aggregate connection; one remaining reader keeps it connected. Notification delivery uses the existing gateway, outside the event-processing path, and never includes prompts, documents or credentials. Slow delivery coalesces pending states to the latest state rather than creating an unbounded queue.
+
+This detects closure as observed on the host; a half-open network failure may take keepalive detection time. Notifications are best effort with the gateway's existing HTTP retries. A stopped host cannot send a push, and delivery cannot be guaranteed while its gateway/internet path is unavailable. Live phone delivery requires a working Backeer source and mobile push setup. This package does not enable or deploy them automatically.
+
+Closing the MCP connection aborts its HTTP/SSE requests, removes wait listeners and clears the in-memory event buffer. It does **not** stop the remote OpenCode task or the user-managed SSH tunnel.
+
+The Codex configuration example follows the [official MCP configuration reference](https://developers.openai.com/codex/mcp). No Codex application settings, SSH credentials, public network listeners, or remote installations are changed automatically by this package.

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "backeer-opencode",
-  "version": "0.3.2",
-  "description": "Backeer lifecycle notifications and remote permission and question replies for OpenCode",
+  "version": "0.5.1",
+  "description": "Backeer mobile approvals and authenticated live OpenCode control over SSE and MCP",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js"
   },
   "bin": {
-    "backeer-opencode": "bin/backeer-opencode.js"
+    "backeer-opencode": "bin/backeer-opencode.js",
+    "backeer-opencode-mcp": "bin/backeer-opencode-mcp.js"
   },
   "files": [
     "src",
@@ -16,11 +17,12 @@
     "bin",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "docs"
   ],
   "scripts": {
     "build": "esbuild src/index.js --bundle --platform=node --format=esm --target=node18 --outfile=dist/backeer-permission.js --legal-comments=none",
-    "check": "npm run lint && node --check bin/backeer-opencode.js && npm test",
+    "check": "npm run lint && node --check bin/backeer-opencode.js && node --check bin/backeer-opencode-mcp.js && npm test",
     "lint": "eslint src bin test eslint.config.js --max-warnings=0",
     "pretest": "npm run build",
     "test": "node --test",
@@ -50,6 +52,11 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@opencode/client": "2.0.26",
+    "zod": "4.6.7"
+  },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
     "esbuild": "^0.28.2",

package/src/config.js

@@ -4,6 +4,7 @@ import { join } from "node:path"
 
 import { normalizeLogLevel } from "./reporter.js"
 import { enabled } from "./utilities.js"
+import { loadLiveBridgeConfig } from "./live-bridge-config.js"
 
 const DEFAULT_ORIGIN = "https://external-gateway.backeer.com"
 
@@ -90,6 +91,9 @@ export function loadConfig(options = {}) {
     token: loadedToken.token,
     tokenSource: loadedToken.source,
     tokenFile,
+    liveBridge: loadLiveBridgeConfig(options.liveBridge, {
+      configDirectory: defaultConfigDirectory(), ingestToken: loadedToken.token,
+    }),
     permissions: enabled(
       options.permissions ?? process.env.BACKEER_NOTIFY_PERMISSIONS,
     ),

package/src/index.js

@@ -1 +1,6 @@
-export { default } from "./plugin.js"
+import server from "./plugin.js"
+import { setup } from "./opencode-v2.js"
+
+// A plain definition avoids an authoring-SDK dependency in the installer bundle.
+// OpenCode >=1.18.29 calls server(); OpenCode V2 calls setup().
+export default { id: "backeer-opencode", setup, server }

package/src/live-bridge-client.js

@@ -0,0 +1,52 @@
+// The bridge submits normal user prompts. It never invokes shell, synthetic
+// feedback, permission replies, or form replies on the caller's behalf.
+export function createV2LiveClient(ctx) {
+  // 2.0.26's plugin SessionDomain intentionally omits list(). Track sessions
+  // observed through get/events instead of inventing that context method or
+  // starting a second OpenCode service just for discovery.
+  const known = new Map()
+  let disposed = false
+  async function get(id) {
+    const info = await ctx.session.get({ sessionID: id })
+    if (disposed) return info
+    known.set(id, info)
+    if (known.size > 100) known.delete(known.keys().next().value)
+    return info
+  }
+  return {
+    async list() {
+      if (typeof ctx.session.list === "function") {
+        return ctx.session.list({ directory: ctx.location.directory, limit: 100, order: "desc" })
+      }
+      const refreshed = []
+      for (const id of known.keys()) {
+        try { refreshed.push(await get(id)) } catch { known.delete(id) }
+      }
+      return refreshed
+    },
+    get,
+    prompt: (id, text) => ctx.session.prompt({ sessionID: id, text, delivery: "queue" }),
+    dispose: () => { disposed = true; known.clear() },
+  }
+}
+
+function unwrap(value) {
+  if (value?.error) throw new Error("OpenCode request failed")
+  return value?.data ?? value
+}
+
+export function createV1LiveClient(client, directory) {
+  return {
+    list: async () => unwrap(await client.session.list({ query: { directory }, throwOnError: true })),
+    get: async (id) => unwrap(await client.session.get({ path: { id }, query: { directory }, throwOnError: true })),
+    async prompt(id, text) {
+      if (typeof client.session.promptAsync !== "function") {
+        throw Object.assign(new Error("OpenCode asynchronous prompts are unavailable"), { status: 501 })
+      }
+      return unwrap(await client.session.promptAsync({
+        path: { id }, query: { directory },
+        body: { parts: [{ type: "text", text }] }, throwOnError: true,
+      }))
+    },
+  }
+}

package/src/live-bridge-config.js

@@ -0,0 +1,48 @@
+import { constants, closeSync, fstatSync, openSync, readFileSync } from "node:fs"
+import { isAbsolute, join } from "node:path"
+
+function readCredential(file) {
+  if (typeof file !== "string" || !isAbsolute(file)) {
+    throw new Error("Live control requires an absolute credential-file path")
+  }
+  let descriptor
+  try {
+    descriptor = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) |
+      (constants.O_NONBLOCK ?? 0))
+    const stat = fstatSync(descriptor)
+    if (!stat.isFile() || stat.size > 4096 ||
+        (process.platform !== "win32" && ((stat.mode & 0o077) !== 0 ||
+          stat.uid !== process.getuid()))) {
+      throw new Error("invalid_file")
+    }
+    const token = readFileSync(descriptor, "utf8").trim()
+    if (!/^[A-Za-z0-9_-]{32,256}$/.test(token)) throw new Error("invalid_token")
+    return token
+  } catch {
+    throw new Error("Live control credential must be an owner-only regular file containing a 32–256 character token")
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor)
+  }
+}
+
+export function loadLiveBridgeConfig(option, { configDirectory, ingestToken } = {}) {
+  const values = option && typeof option === "object" ? option : {}
+  const enabled = (typeof option === "boolean" ? option : values.enabled) ??
+    process.env.BACKEER_LIVE_ENABLED
+  if (enabled !== true && enabled !== "true" && enabled !== "1") return { enabled: false }
+  try {
+    const rawPort = values.port ?? process.env.BACKEER_LIVE_PORT ?? 43871
+    const port = Number(rawPort)
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new Error("Live control port must be an integer between 1 and 65535")
+    }
+    const tokenFile = values.tokenFile ?? process.env.BACKEER_LIVE_TOKEN_FILE ??
+      join(configDirectory, "secrets", "backeer-live-token")
+    const token = readCredential(tokenFile)
+    if (token === ingestToken) throw new Error("Live control requires a credential distinct from the Backeer ingest token")
+    return { enabled: true, token, tokenFile, port }
+  } catch (error) {
+    // A bad opt-in must not disable the existing mobile approval integration.
+    return { enabled: false, error: error.message }
+  }
+}

package/src/live-bridge-events.js

@@ -0,0 +1,80 @@
+const ID = /^[A-Za-z0-9_-]{1,160}$/
+export const validBridgeID = (value) => typeof value === "string" && ID.test(value)
+
+export function createBridgeSanitizer(secrets = []) {
+  const known = secrets.filter((value) => typeof value === "string" && value.length > 0)
+  const assistants = new Map()
+  function clipped(value, max = 12_000) {
+    if (typeof value !== "string") return { value: "", truncated: false }
+    let result = value.slice(0, 64_000)
+    for (const secret of known) result = result.split(secret).join("[REDACTED]")
+    result = result
+      .replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?(?:-----END [^-]*PRIVATE KEY-----|$)/g, "[REDACTED PRIVATE KEY]")
+      .replace(/\bBearer\s+[^\s"'<>]+/gi, "Bearer [REDACTED]")
+      .replace(/\b(?:sk|bgi)_[A-Za-z0-9_-]{12,}|\bsk-[A-Za-z0-9_-]{12,}/g, "[REDACTED]")
+      .replace(/((?:api[_-]?key|access[_-]?token|secret|password|authorization)\s*[=:]\s*)[^\s,;]+/gi, "$1[REDACTED]")
+    return { value: result.slice(0, max), truncated: value.length > 64_000 || result.length > max }
+  }
+  function text(value, max) { return clipped(value, max).value }
+  function content(key, value) {
+    const result = clipped(value)
+    return { [key]: result.value, ...(result.truncated ? { truncated: true } : {}) }
+  }
+  function sanitize(event) {
+    const p = event?.properties ?? event?.data ?? {}
+    const sessionID = p.sessionID ?? p.info?.sessionID ?? p.part?.sessionID
+    if (!validBridgeID(sessionID) || sessionID === "global") return undefined
+    const base = { type: event.type, sessionID, data: {} }
+    if (event.type === "message.updated") {
+      const info = p.info
+      if (!validBridgeID(info?.id)) return undefined
+      if (info.role === "assistant") {
+        assistants.set(info.id, sessionID)
+        if (assistants.size > 256) assistants.delete(assistants.keys().next().value)
+      }
+      return info.role === "assistant" ? { ...base, data: {
+        messageID: info.id, completed: !!info.time?.completed, failed: !!info.error,
+      } } : undefined
+    }
+    if (event.type === "message.part.updated") {
+      const part = p.part
+      if (assistants.get(part?.messageID) !== sessionID) return undefined
+      if (part.type === "text") return { ...base, type: "assistant.text", data: {
+        messageID: part.messageID, ...content("text", part.text), replace: true,
+      } }
+      if (part.type !== "tool") return undefined
+      const state = part.state ?? {}
+      return { ...base, type: "tool.status", data: {
+        tool: text(part.tool, 80), status: text(state.status, 40),
+        ...(state.status === "completed" ? content("output", state.output) : {}),
+        ...(state.status === "error" ? { failed: true } : {}),
+      } }
+    }
+    if (event.type === "session.text.ended") return { ...base, type: "assistant.text", data: {
+      messageID: validBridgeID(p.assistantMessageID) ? p.assistantMessageID : undefined,
+      ...content("text", p.text), replace: true,
+    } }
+    // Raw deltas can split secrets across frames. Publish completed text units
+    // instead; execution/tool transitions still arrive immediately.
+    if (["session.tool.called", "session.tool.success", "session.tool.failed"].includes(event.type)) {
+      return { ...base, type: "tool.status", data: {
+        status: event.type.split(".").at(-1),
+        ...(event.type === "session.tool.success" ? content("output",
+          (p.content ?? []).filter((item) => item?.type === "text").map((item) => item.text).join("\n"),
+        ) : {}),
+      } }
+    }
+    if (["permission.asked", "question.asked", "question.v2.asked"].includes(event.type)) {
+      return { ...base, type: "approval.waiting", data: { kind: event.type.split(".")[0] } }
+    }
+    if (["permission.replied", "question.replied", "question.v2.replied", "question.rejected", "question.v2.rejected"].includes(event.type)) {
+      return { ...base, type: "approval.settled", data: { kind: event.type.split(".")[0] } }
+    }
+    if (event.type === "session.status") return { ...base, data: { status:
+      ["idle", "busy", "retry"].includes(p.status?.type) ? p.status.type : "unknown",
+    } }
+    if (["session.idle", "session.error", "session.deleted"].includes(event.type)) return base
+    return undefined
+  }
+  return { sanitize, text, clear: () => assistants.clear() }
+}

package/src/live-bridge.js

@@ -0,0 +1,273 @@
+import { createServer } from "node:http"
+import { randomUUID, timingSafeEqual } from "node:crypto"
+import { createV1LiveClient } from "./live-bridge-client.js"
+import { createLiveConnectionNotifier, LIVE_HEARTBEAT_MS, LIVE_RECONNECT_MS } from "./live-connection.js"
+import { createBridgeSanitizer, validBridgeID } from "./live-bridge-events.js"
+
+const LIMITS = { events: 256, bytes: 2_000_000, clients: 8, commands: 1024, commandTTL: 86_400_000, body: 32_768, requests: 16 }
+function failure(status, code) { return Object.assign(new Error(code), { status, code }) }
+function json(response, status, value) {
+  if (!response.destroyed && !response.headersSent) {
+    response.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" })
+    response.end(JSON.stringify(value))
+  }
+}
+async function readBody(request) {
+  const chunks = []
+  let bytes = 0
+  for await (const chunk of request) {
+    bytes += chunk.length
+    if (bytes > LIMITS.body) throw failure(413, "body_too_large")
+    chunks.push(chunk)
+  }
+  try { return JSON.parse(Buffer.concat(chunks).toString("utf8")) } catch { throw failure(400, "invalid_json") }
+}
+
+export async function createLiveBridge({ config, client, directory, reporter }) {
+  const options = config.liveBridge
+  if (!options?.enabled) return { handle() {}, async dispose() {}, address: undefined }
+  const token = options.token
+  if (typeof token !== "string" || token.length < 32 || token === config.token) {
+    throw new Error("Live bridge requires a separate credential of at least 32 characters")
+  }
+  const api = client.liveBridge ?? createV1LiveClient(client, directory)
+  const connectionNotifications = createLiveConnectionNotifier(config, reporter)
+  const sanitizer = createBridgeSanitizer([token, config.token])
+  const epoch = randomUUID()
+  const events = [], streams = new Set(), commands = new Map(), states = new Map()
+  let sequence = 0, bytes = 0, active = 0, disposed = false, disposeTask
+  let lookups = 0
+  const lookupWaiters = new Set()
+  const cursor = () => `${epoch}:${sequence}`
+
+  function lookup(id) {
+    if (disposed) return Promise.reject(failure(503, "bridge_closed"))
+    if (lookups >= 16) return Promise.reject(failure(429, "session_lookup_busy"))
+    lookups++
+    return new Promise((resolve, reject) => {
+      let finished = false
+      const finish = (complete, value) => {
+        if (finished) return
+        finished = true
+        clearTimeout(timer)
+        lookupWaiters.delete(cancel)
+        complete(value)
+      }
+      const cancel = () => finish(reject, failure(503, "bridge_closed"))
+      const timer = setTimeout(() => finish(reject, failure(504, "session_lookup_timed_out")), 1000)
+      lookupWaiters.add(cancel)
+      // The caller's deadline does not release this slot: unsupported SDK
+      // cancellation must not let timed-out, still-running calls accumulate.
+      Promise.resolve().then(() => api.get(id)).then(
+        (value) => { lookups--; finish(resolve, value) },
+        (error) => { lookups--; finish(reject, error) },
+      )
+    })
+  }
+
+  async function session(id) {
+    if (!validBridgeID(id) || id === "global") throw failure(400, "invalid_session")
+    let info
+    try { info = await lookup(id) } catch (error) {
+      if (["session_lookup_busy", "session_lookup_timed_out", "bridge_closed"].includes(error.code)) throw error
+      throw failure(404, "session_not_found")
+    }
+    if (info?.id !== id || (info.location?.directory ?? info.directory) !== directory) {
+      throw failure(404, "session_not_found")
+    }
+    return {
+      id, title: sanitizer.text(info.title, 240),
+      ...(validBridgeID(info.parentID) ? { parentID: info.parentID } : {}),
+      status: states.get(id) ?? "unknown",
+    }
+  }
+  function removeStream(stream) {
+    const removed = streams.delete(stream)
+    clearInterval(stream.heartbeat)
+    stream.queue.length = 0
+    stream.queuedBytes = 0
+    if (removed && !streams.size && !disposed) connectionNotifications.update(false)
+  }
+  function write(stream, value) {
+    if (!streams.has(stream)) return
+    if (stream.blocked) {
+      stream.queue.push(value)
+      stream.queuedBytes += Buffer.byteLength(value)
+      if (stream.queuedBytes > LIMITS.bytes) {
+        removeStream(stream)
+        stream.response.destroy()
+      }
+      return
+    }
+    if (!stream.response.write(value)) {
+      stream.blocked = true
+    }
+  }
+  async function handle(event) {
+    if (disposed) return
+    const safe = sanitizer.sanitize(event)
+    if (!safe) return
+    // V1 events may be global. Do not publish another project's session just
+    // because the event happened to reach this plugin instance.
+    try { await session(safe.sessionID) } catch { return }
+    if (disposed) return
+    if (safe.type === "session.status") states.set(safe.sessionID, safe.data.status)
+    if (safe.type === "session.idle") states.set(safe.sessionID, "idle")
+    if (safe.type === "session.deleted") states.delete(safe.sessionID)
+    if (states.size > 256) states.delete(states.keys().next().value)
+    const record = { id: `${epoch}:${++sequence}`, ...safe, timestamp: Date.now() }
+    let frame = `id: ${record.id}\nevent: backeer.event\ndata: ${JSON.stringify(record)}\n\n`
+    if (Buffer.byteLength(frame) > 32_768) {
+      record.data = { truncated: true }
+      frame = `id: ${record.id}\nevent: backeer.event\ndata: ${JSON.stringify(record)}\n\n`
+    }
+    const size = Buffer.byteLength(frame)
+    events.push({ sequence, sessionID: record.sessionID, frame, size })
+    bytes += size
+    while (events.length > LIMITS.events || bytes > LIMITS.bytes) bytes -= events.shift().size
+    for (const stream of streams) if (!stream.sessionID || stream.sessionID === record.sessionID) write(stream, frame)
+  }
+  function authorized(request) {
+    if (request.headers.origin || request.headers["sec-fetch-site"]) return false
+    const expected = Buffer.from(`Bearer ${token}`)
+    const actual = Buffer.from(request.headers.authorization ?? "")
+    return actual.length === expected.length && timingSafeEqual(actual, expected)
+  }
+  function parseCursor(value) {
+    if (!value) return { after: 0 }
+    const match = /^([a-f0-9-]{36}):(\d{1,16})$/.exec(value)
+    if (!match) throw failure(400, "invalid_cursor")
+    if (match[1] !== epoch) return { gap: "stream_restarted" }
+    const after = Number(match[2])
+    if (!Number.isSafeInteger(after) || after > sequence) throw failure(400, "invalid_cursor")
+    if (events.length && after < events[0].sequence - 1) return { gap: "cursor_expired" }
+    return { after }
+  }
+  async function route(request, response) {
+    if (!authorized(request)) return json(response, 401, { error: "unauthorized" })
+    if (active >= LIMITS.requests) return json(response, 429, { error: "bridge_busy" })
+    active++
+    const timeout = setTimeout(() => json(response, 504, { error: "request_timed_out" }), 15_000)
+    timeout.unref()
+    try {
+      const url = new URL(request.url, "http://127.0.0.1")
+      if (url.username || url.password) throw failure(400, "invalid_url")
+      if (request.method === "GET" && url.pathname === "/v1/sessions") {
+        const result = await api.list()
+        const values = Array.isArray(result) ? result : result?.data
+        if (!Array.isArray(values)) throw failure(502, "invalid_session_list")
+        const own = values.slice(0, 100).filter((info) => validBridgeID(info?.id) &&
+          (info.location?.directory ?? info.directory) === directory)
+        return json(response, 200, { sessions: own.map((info) => ({
+          id: info.id, title: sanitizer.text(info.title, 240), status: states.get(info.id) ?? "unknown",
+          ...(validBridgeID(info.parentID) ? { parentID: info.parentID } : {}),
+        })), cursor: cursor() })
+      }
+      if (request.method === "GET" && url.pathname === "/v1/events") {
+        const selected = url.searchParams.get("sessionID") || undefined
+        if (selected) await session(selected)
+        const parsed = parseCursor(url.searchParams.get("after") ?? request.headers["last-event-id"])
+        if (response.headersSent) return
+        if (streams.size >= LIMITS.clients) throw failure(429, "too_many_streams")
+        clearTimeout(timeout)
+        response.writeHead(200, {
+          "content-type": "text/event-stream", "cache-control": "no-cache, no-transform",
+          "x-accel-buffering": "no", connection: "keep-alive",
+        })
+        if (parsed.gap) {
+          response.end(`event: backeer.gap\ndata: ${JSON.stringify({ reason: parsed.gap, cursor: cursor() })}\n\n`)
+          return
+        }
+        const stream = { response, sessionID: selected, heartbeat: undefined,
+          blocked: false, queue: [], queuedBytes: 0 }
+        streams.add(stream)
+        connectionNotifications.update(true)
+        request.socket.setTimeout(0)
+        request.socket.setKeepAlive(true, LIVE_HEARTBEAT_MS)
+        response.on("close", () => removeStream(stream))
+        response.on("drain", () => {
+          stream.blocked = false
+          while (streams.has(stream) && !stream.blocked && stream.queue.length) {
+            const next = stream.queue.shift()
+            stream.queuedBytes -= Buffer.byteLength(next)
+            write(stream, next)
+          }
+        })
+        write(stream, `: connected\nretry: ${LIVE_RECONNECT_MS}\n\n`)
+        for (const item of events) {
+          if (!streams.has(stream)) break
+          if (item.sequence > parsed.after && (!selected || selected === item.sessionID)) write(stream, item.frame)
+        }
+        if (streams.has(stream)) {
+          stream.heartbeat = setInterval(() => write(stream, ": heartbeat\n\n"), LIVE_HEARTBEAT_MS)
+          stream.heartbeat.unref()
+        }
+        return
+      }
+      const match = /^\/v1\/sessions\/([A-Za-z0-9_-]{1,160})(\/instructions)?$/.exec(url.pathname)
+      if (!match) throw failure(404, "route_not_found")
+      if (request.method === "GET" && !match[2]) return json(response, 200, await session(match[1]))
+      if (request.method !== "POST" || !match[2]) throw failure(405, "method_not_allowed")
+      if (!/^application\/json(?:;|$)/i.test(request.headers["content-type"] ?? "")) throw failure(415, "json_required")
+      const body = await readBody(request)
+      if (!body || !validBridgeID(body.requestId) || typeof body.prompt !== "string" ||
+          !body.prompt.trim() || body.prompt.length > 16_000 ||
+          Object.keys(body).some((key) => !["requestId", "prompt"].includes(key))) throw failure(400, "invalid_instruction")
+      await session(match[1])
+      if (response.headersSent || disposed) return
+      for (const [id, command] of commands) {
+        if (command.settled && Date.now() - command.created >= LIMITS.commandTTL) commands.delete(id)
+      }
+      const existing = commands.get(body.requestId)
+      if (existing) {
+        if (existing.sessionID !== match[1] || existing.prompt !== body.prompt) throw failure(409, "request_id_conflict")
+        await existing.task
+        return json(response, 200, existing.result)
+      }
+      // Reject at capacity instead of evicting a recent/in-flight request and
+      // executing its retry twice. Settled IDs expire only after 24 hours.
+      if (commands.size >= LIMITS.commands) throw failure(429, "command_window_full")
+      const command = { sessionID: match[1], prompt: body.prompt, created: Date.now(), settled: false,
+        result: { requestId: body.requestId, sessionID: match[1], status: "accepted" }, task: undefined }
+      commands.set(body.requestId, command)
+      command.task = Promise.resolve().then(() => api.prompt(match[1], body.prompt))
+        .finally(() => { command.settled = true })
+      await command.task
+      // Keep the identity/failure cached even if the HTTP connection disappears:
+      // a client retry cannot re-submit a potentially accepted SDK request.
+      return json(response, 202, command.result)
+    } catch (error) {
+      json(response, error.status ?? 502, { error: error.code ?? "opencode_request_failed" })
+    } finally {
+      active--
+      clearTimeout(timeout)
+    }
+  }
+  const server = createServer((request, response) => { void route(request, response) })
+  server.requestTimeout = 15_000
+  server.headersTimeout = 10_000
+  server.keepAliveTimeout = 5_000
+  await new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(options.port ?? 43871, "127.0.0.1", () => { server.off("error", reject); resolve() })
+  })
+  server.on("error", () => {})
+  return {
+    handle, address: server.address(),
+    dispose() {
+      disposeTask ??= new Promise((resolve) => {
+        disposed = true
+        for (const cancel of lookupWaiters) cancel()
+        for (const stream of streams) { removeStream(stream); stream.response.destroy() }
+        server.close(() => { void connectionNotifications.dispose().then(resolve) })
+        server.closeAllConnections?.()
+        events.length = 0
+        states.clear()
+        commands.clear()
+        sanitizer.clear()
+        api.dispose?.()
+      })
+      return disposeTask
+    },
+  }
+}