backeer-opencode 0.3.2 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to `backeer-opencode` are documented here.
 
+## 0.5.1 - 2026-11-03
+
+- Keep live tracking active during hours of agent silence; retain 15-second
+  heartbeats and detect dead transport only after 45 seconds without traffic.
+- Retry live SSE and native V2 subscriptions every three seconds indefinitely,
+  including initial unavailability and authentication failures. Preserve explicit
+  history-gap reporting while reconnecting the transport automatically.
+- Send disconnect/reconnect application notifications through the existing
+  Backeer mobile gateway once per aggregate connection transition. Keep pending
+  delivery bounded and avoid notifications on deliberate plugin disposal.
+- Document a reconnecting SSH tunnel and the distinction between tool waits,
+  transport timeouts and long-running agent jobs.
+
+## 0.5.0 - 2026-11-03
+
+- Add optional authenticated loopback live control inside the existing OpenCode
+  process: bounded SSE replay, reconnect/gap signaling, exact-session normal
+  prompts and 24-hour instruction idempotency.
+- Add a local stdio MCP adapter for session status, incremental reads, bounded
+  SSE waits and explicit instructions over an existing SSH tunnel.
+- Preserve mobile approvals/questions, reject cross-project access, and keep
+  live credentials separate and owner-readable. No remote deployment or public
+  listener is enabled automatically.
+- Document supported V1/V2 output events and observed-session discovery limits.
+
+## 0.4.0 - 2026-10-11
+
+- Add a V2 default definition with a stable ID, setup, event subscription,
+  command transform, prompt hook, and abortable cleanup; retain the V1 server
+  entrypoint for OpenCode 1.18.29 and newer.
+- Adapt native V2 permission replies, question forms, and execution lifecycle
+  events, with location isolation and reconnect handling.
+- Use the V2 plugin installation command for explicitly requested updates.
+- Keep automatic delivery feedback in server logs on V2 rather than injecting
+  it into model context. Native V2 no longer provides ignored conversation
+  entries or todo.updated events; todo notifications remain available on V1.
+- Rebuild the dependency-free installer bundle and add V2 regression tests.
+- Verification: `npm run check` passes all 49 tests; `npm audit --omit=dev`
+  reports no vulnerabilities. The packed installer loads as active on an isolated
+  OpenCode 2.0.26 service, `/backeer token` executes without an agent turn, and
+  native question answer/cancel calls pass through authenticated discovery.
+
 ## 0.3.2 - 2026-09-02
 
 - Synchronize the plugin's reported runtime version with the published package

package/README.md

@@ -8,12 +8,66 @@ command stream. An authorized user can choose **Allow once**, **Always allow**,
 or **Reject** for permissions and can answer or reject AI questions from the
 Backeer iOS application.
 
-The plugin uses outbound HTTPS only. It does not start a server or require an
-inbound firewall rule.
+Mobile notifications and approvals use outbound HTTPS only. The optional live
+control feature adds an authenticated loopback-only listener inside OpenCode;
+it needs no public port, inbound firewall rule, or separately hosted server.
+See [Live control setup](docs/live-control.md) for the SSE/MCP connection.
+
+## Live output and instructions
+
+The opt-in live channel lets a local MCP client send an instruction to an exact
+OpenCode session and follow assistant text, tool results, status and pending
+approval metadata over SSE. It does not record the whole terminal, export
+reasoning or authentication forms, or approve permissions. Mobile approval and
+question replies continue through Backeer as before.
+
+Create a separate protected live-control credential file on the OpenCode host;
+use the same credential in an owner-only file on the MCP computer. Do not reuse
+the Backeer ingest token. Values never belong in plugin options or chat text.
+For example, generate a file without printing its contents:
+
+```sh
+install -d -m 700 "$HOME/.config/opencode/secrets"
+(set -C; umask 077; openssl rand -hex 32 > "$HOME/.config/opencode/secrets/backeer-live-token")
+```
+
+This refuses to overwrite an existing live-control file; generate it once for
+initial setup, not during a running session. Enable the plugin with non-secret
+options (use an actual absolute path):
+
+```json
+{
+  "plugins": [{
+    "package": "backeer-opencode",
+    "options": {
+      "liveBridge": {
+        "enabled": true,
+        "port": 43871,
+        "tokenFile": "/absolute/private/path/backeer-live-token"
+      }
+    }
+  }]
+}
+```
+
+For side-loaded installations, the equivalent environment variables are
+`BACKEER_LIVE_ENABLED=true`, `BACKEER_LIVE_PORT=43871`, and
+`BACKEER_LIVE_TOKEN_FILE=/absolute/private/path/backeer-live-token`. Defaults:
+disabled; port `43871`; token file under the existing OpenCode configuration
+directory at `secrets/backeer-live-token`. An invalid live configuration disables
+only the live channel, leaving existing mobile integration available. Restart
+the intended OpenCode process after explicitly installing/enabling this version;
+existing running sessions are not modified by this source checkout.
+
+The matching `backeer-opencode-mcp` executable is provided in the package.
+Connect through an existing SSH tunnel and register the local stdio executable
+as described in [the complete setup guide](docs/live-control.md). Version 0.5.1
+in this checkout must be installed from its built package or installer bundle
+until it has been separately published; do not assume npm `latest` contains it.
 
 ## Requirements
 
-- OpenCode with server plugin support
+- OpenCode V2 (tested against 2.0.26), or V1 1.18.29 and newer
 - 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
@@ -24,7 +78,7 @@ 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
+The local installer copies a single self-contained plugin file into OpenCode's
 global plugin directory. OpenCode discovers it automatically.
 
 ```sh
@@ -54,7 +108,7 @@ Restart OpenCode after installation or update.
 Install the package in OpenCode's global configuration:
 
 ```sh
-opencode plugin backeer-opencode -g
+opencode plugin add backeer-opencode
 npx backeer-opencode@latest configure
 ```
 
@@ -67,7 +121,7 @@ Alternatively, add it to `~/.config/opencode/opencode.json` manually:
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["backeer-opencode"]
+  "plugins": ["backeer-opencode"]
 }
 ```
 
@@ -121,14 +175,14 @@ environment variables are supported:
 | `BACKEER_LOG_LEVEL` | `info` (default), `error`, `debug`, or `silent` |
 
 For npm installations, non-secret options can also be supplied through the
-OpenCode plugin tuple syntax:
+OpenCode V2 plugin options syntax:
 
 ```json
 {
-  "plugin": [
-    [
-      "backeer-opencode",
-      {
+  "plugins": [
+    {
+      "package": "backeer-opencode",
+      "options": {
         "permissions": true,
         "questions": true,
         "todos": true,
@@ -142,18 +196,18 @@ OpenCode plugin tuple syntax:
           "retryAttemptThreshold": 3
         }
       }
-    ]
+    }
   ]
 }
 ```
 
 Supported options are `origin`, `tokenFile`, `permissions`, `questions`,
-`todos`, `lifecycle`, and `logLevel`. Use `"lifecycle": false` to disable the
+`todos`, `lifecycle`, `liveBridge`, and `logLevel`. Use `"lifecycle": false` to disable the
 entire lifecycle group. The token itself is deliberately not a plugin option.
 
 ## Conversation feedback
 
-User-facing status messages appear as compact Backeer entries in the OpenCode
+On OpenCode V1, user-facing status messages appear as compact Backeer entries in the OpenCode
 conversation:
 
 ```text
@@ -170,8 +224,13 @@ an agent is active, a permission prompt is open, or a question is awaiting an
 answer remains queued until the interaction closes and the session becomes idle.
 It never writes to the user's input field or replaces interactive OpenCode UI.
 
-Technical diagnostics use OpenCode's structured application log API instead of
-stdout. Normal `info` logging omits HTTP details; set
+On V2, automatic delivery feedback stays in server logs: the V1 ignored/noReply
+conversation API no longer exists. `/backeer` command results use a synthetic
+entry with `resume: false`, so they do not start an agent turn, but they can be
+included in later model context. No credentials are displayed.
+
+Technical diagnostics use V1's structured application log API or V2's captured
+server stderr, never stdout. Normal `info` logging omits HTTP details; set
 `BACKEER_LOG_LEVEL=debug` when technical details are needed. Set it to `error`
 for failures only or `silent` to disable structured logs.
 
@@ -228,7 +287,22 @@ package caches.
 
 ## Events and decisions
 
-The plugin publishes:
+On V2, native `form.created` question forms are adapted to Backeer question
+cards, replies use `session.form.reply/cancel`, and
+`session.execution.started/succeeded/failed/interrupted` drive lifecycle
+notifications. Only forms marked `metadata.kind: "question"` are forwarded;
+authentication and other forms are never exported. Events from other locations
+are ignored. V2 has no native `todo.updated` event, so todo notifications are
+disabled there regardless of the `todos` option.
+
+V2 remote question replies require the managed shared service. OpenCode 2.0.26
+does not expose forms on the plugin context, so the plugin uses the official
+client's authenticated service discovery and verifies session location before
+answering. It never starts another service. Notifications work in standalone
+mode, but remote question replies fail explicitly there rather than contacting
+a different session.
+
+The V1 event mappings are:
 
 | OpenCode event | Backeer behavior |
 |---|---|

package/bin/backeer-opencode-mcp.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runLiveControlMcp } from "../src/live-control-mcp.js"
+
+try {
+  await runLiveControlMcp()
+} catch {
+  console.error("Backeer live-control MCP failed to start. Check BACKEER_LIVE_TOKEN_FILE, its owner-only permissions, and BACKEER_LIVE_URL.")
+  process.exitCode = 1
+}