opencode-agent-flow 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2026-10-17
+
+### Added
+
+- Actionable HTTP 401 error reporting without exposing upstream credentials.
+- Connected OpenCode version in backend logs.
+- Cyclic demo activity: tools, working states and bounded events every 1.5 seconds.
+- Animated GIF and MP4 README demos, excluded from the npm package.
+- CI for Node.js 20/22/24 on Linux and Node.js 22 on macOS/Windows.
+- Bug report, feature request and pull request templates, plus security/discussion links.
+
+### Changed
+
+- Verified compatibility with a clean OpenCode 2.0.32 installation.
+- Documented local/remote setup and generated or explicit server passwords.
+- Normalized package.json metadata with `npm pkg fix`.
+- CLI help reads the release version from package.json.
+
+## [0.1.0] - 2026-10-16
+
+### Added
+
+- Initial release: read-only OpenCode V2 dashboard over public HTTP and SSE.
+- WebGL agent trees, grouped parallel calls, tools, approval waits, tokens and estimated costs.
+- Local/remote upstream support, fictional demo data and zero runtime npm dependencies.
+
+[0.1.1]: https://github.com/orybakov/opencode-agent-flow/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/orybakov/opencode-agent-flow/releases/tag/v0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+
+Open an issue to discuss substantial changes. Keep pull requests focused, add regression tests, and run `node --test` on Node 20 and a current Node release. Never commit credentials or real session data. See SECURITY.md for private vulnerability reports.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orybakov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,182 @@
-# Temporary Holding Version
+# opencode-agent-flow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/opencode-agent-flow)](https://www.npmjs.com/package/opencode-agent-flow)
+[![CI](https://github.com/orybakov/opencode-agent-flow/actions/workflows/ci.yml/badge.svg)](https://github.com/orybakov/opencode-agent-flow/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/node/v/opencode-agent-flow)](https://nodejs.org/)
+
+**Watch your agents work, not just their logs.**
+
+A live, read-only visualization of OpenCode V2 orchestration. See agent trees,
+grouped parallel calls, current tools, approval waits, token usage and estimated
+costs in one WebGL dashboard. Connect to a local or remote OpenCode server using
+only its public HTTP API and SSE—no database access required.
+
+Zero runtime npm dependencies. Node.js 20+; no frontend build step.
+
+![Live Agent Flow demo: session tree, active tools and animated token transport](https://raw.githubusercontent.com/orybakov/opencode-agent-flow/main/docs/demo.gif)
+
+[Watch the MP4 demo](https://github.com/orybakov/opencode-agent-flow/raw/refs/heads/main/docs/demo.mp4) · fictional data; no credentials or private sessions.
+
+## Quick start
+
+### Local OpenCode server
+
+Start OpenCode V2 in one terminal:
+
+```sh
+opencode serve --hostname 127.0.0.1 --port 4096
+```
+
+In another terminal, set `OPENCODE_SERVER_PASSWORD` to the password printed by
+that server (see below), then run:
+
+```sh
+npx opencode-agent-flow --open
+```
+
+### Remote OpenCode server
+
+Set `OPENCODE_SERVER_PASSWORD` in your local terminal to the remote server's
+password, then connect over HTTPS:
+
+```sh
+npx opencode-agent-flow --server https://opencode.example.org --open
+```
+
+The dashboard itself stays on loopback. The remote server must expose the V2
+HTTP API and SSE; no database access or browser-side credentials are needed.
+
+For a preview without any OpenCode server: `npx opencode-agent-flow --demo --open`.
+Demo tools, agent states and events cycle every 1.5 seconds.
+
+Open <http://127.0.0.1:3340>. For an unpublished local checkout:
+`node bin/cli.mjs --demo`.
+
+## Where do I get the password?
+
+On a clean **OpenCode 2.0.32**, `opencode serve` generates a password when none
+is configured and prints it in the launching terminal on the **`server password`**
+line, after the listening URL. Copy that value privately into the
+`OPENCODE_SERVER_PASSWORD` environment variable of the Agent Flow process.
+The default HTTP Basic username is **`opencode`**; use `--username` or
+`OPENCODE_SERVER_USERNAME` if yours differs.
+
+Alternatively, choose a strong password yourself and set
+`OPENCODE_SERVER_PASSWORD` **before starting `opencode serve`**, then supply the
+same value to Agent Flow. For example, after loading it from your secret manager
+into a shell variable (POSIX shell):
+
+```sh
+export OPENCODE_SERVER_PASSWORD="$YOUR_OPENCODE_PASSWORD"
+opencode serve --hostname 127.0.0.1 --port 4096
+# In another terminal, export the same environment variable, then:
+npx opencode-agent-flow --open
+```
+
+In PowerShell, set an environment variable with
+`$env:OPENCODE_SERVER_PASSWORD = $YourOpenCodePassword` instead. Do not put the
+password in a URL, CLI flag, screenshot, issue or committed config. Agent Flow
+does not discover credentials from the OpenCode database or managed service.
+An already-running server does not inherit environment changes: set the value
+when launching it, not only when launching this dashboard.
+
+The generated-password output and explicit environment password were verified
+against an isolated 2.0.32 installation. Current V2 docs describe the
+[client/server model](https://opencode.ai/v2/docs/cli) and
+[foreground server environment](https://opencode.ai/v2/docs/network#foreground);
+`opencode serve` is distinct from the automatically managed background service.
+
+## Options
+
+| Flag | Environment fallback | Default |
+| --- | --- | --- |
+| `--server URL` | `OPENCODE_URL` | `http://127.0.0.1:4096` |
+| `--username NAME` | `OPENCODE_SERVER_USERNAME` | `opencode` |
+| `--port NUMBER` | `PORT` | `3340` |
+| `--host ADDRESS` | — | `127.0.0.1` |
+| `--allowed-host HOST` (repeatable) | — | Additional allowed hostname |
+| `--window HOURS` | `WINDOW_HOURS` | `4` |
+| `--open` | — | Open the browser |
+| `--demo` | — | Built-in fictional data |
+| `--help` | — | Show usage |
+
+`OPENCODE_SERVER_PASSWORD` is accepted **only through the environment**. Without
+it the BFF tries unauthenticated access; rejected access leaves the UI connecting
+while the backend retries.
+
+## How it works
+
+A thin Node backend-for-frontend (BFF) loads paginated session/message history,
+keeps one global upstream SSE subscription, and sends aggregated snapshots to
+the browser. Reconnects use exponential backoff (1–30 seconds), reset only after
+a connection lasts at least 30 seconds. Full resynchronization is limited to
+once per 10 seconds; initial connection failures retry with the same backoff.
+A periodic reconciliation (every 60 seconds) catches missed events. Permissions and forms are
+polled for each active location. All/session modes, grouped `×N` agents and
+individual-call popovers preserve the orchestration hierarchy.
+
+`N agents · M calls` counts visible groups and all sessions respectively, each
+including the root. The recent activity window applies to root selection; explicit
+session mode loads the complete selected tree, including dormant children.
+
+## Compatibility
+
+- Verified with **OpenCode 2.0.30 and 2.0.32** on Linux (official V2 npm package:
+  `@opencode/cli`, not the V1 `opencode-ai` package).
+- Tests pass locally on Linux with **Node.js 20, 22 and 24**.
+- CI runs the test suite, syntax checks and package dry-run on Linux with Node
+  20/22/24, plus **macOS and Windows with Node 22**. Those platforms are covered
+  by CI tests only, not a verified live OpenCode/browser deployment; the first
+  hosted run happens after push.
+- The V2 HTTP API is **experimental**; future changes may require adapter updates.
+  Non-V2 servers remain in connecting state.
+
+## Security and limitations
+
+- Loopback binding by default. **The UI has no authentication**; exposing it on
+  another interface reveals session titles, paths and activity. Use an authenticated
+  reverse proxy for shared deployments.
+- The upstream password stays in Node, never in browser responses or URLs.
+  Use HTTPS to protect Basic authentication to remote servers.
+- Host/Origin checks reject unapproved hostnames (DNS-rebinding protection).
+  Extra hostnames require `--allowed-host`; the configured port is enforced.
+- The UI displays session titles, commands and paths. Secret redaction is
+  **best-effort**, not a guarantee. Do not expose it to a network without a
+  reverse proxy providing authentication. Report vulnerabilities via
+  [GitHub Security Advisories](https://github.com/orybakov/opencode-agent-flow/security/advisories/new).
+- SSE is live-only, without replay. Reconciliation recovers durable snapshots,
+  not every transient event. No historical permission-decision journal is available.
+- Token/cost panels use available history (at least 12 hours/current day for
+  default aggregates). Context size is approximate, not an exact provider meter.
+
+## Cost estimates
+
+`prices.json` supplies editable USD-per-million input/output/cache-read rates and
+context limits. The UI labels costs **`≈ est.`**: pricing may be outdated, provider
+subscriptions may differ, and these figures are not billing statements.
+
+## Development
+
+```sh
+node bin/cli.mjs --demo
+node scripts/check-syntax.mjs
+npm test
+npm pack --dry-run
+```
+
+See [architecture](docs/architecture.md) and
+[public API notes](docs/opencode-v2-api-notes.md). Vendored browser modules avoid
+CDN/network dependencies; there is no install or bundling step.
+
+## Roadmap
+
+- Ensemble team views and richer orchestration context.
+- Memory and rendering performance for thousands of sessions.
+- A small, ready-to-run Docker image.
+- Additional themes and visual customization.
+
+## License and acknowledgements
+
+MIT © 2026 orybakov. WebGL rendering uses [three.js](https://threejs.org/),
+vendored under its MIT license in `public/vendor/three/LICENSE`.

package/SECURITY.md

@@ -0,0 +1,3 @@
+# Security policy
+
+Please report vulnerabilities privately using [GitHub Security Advisories](https://github.com/orybakov/opencode-agent-flow/security/advisories/new). Include reproduction steps and the affected version. Do not include credentials or private session data in public issues.

package/bin/cli.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { start } from '../server.mjs';
+process.on('unhandledRejection', error => console.error('Unhandled rejection:', error?.name || 'Error'));
+process.on('uncaughtException', error => console.error('Uncaught exception:', error?.name || 'Error'));
+
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const help = `opencode-agent-flow ${version} — live OpenCode V2 agent visualization
+
+Usage: npx opencode-agent-flow [options]
+  --server URL      OpenCode V2 URL (OPENCODE_URL; http://127.0.0.1:4096)
+  --username NAME   Basic auth username (OPENCODE_SERVER_USERNAME; opencode)
+  --port NUMBER     UI port (PORT; 3340)
+  --host ADDRESS    UI bind address (127.0.0.1)
+  --allowed-host HOST Allow an additional Host hostname (repeatable)
+  --window HOURS    Recent activity window (WINDOW_HOURS; 4)
+  --open            Open the UI in your default browser
+  --demo            Use built-in fictional data; no upstream connection
+  --help, -h        Show this help
+
+Password: OPENCODE_SERVER_PASSWORD environment variable only.
+The UI has no authentication. Keep the default loopback bind address.`;
+
+try {
+  const config = { server: process.env.OPENCODE_URL || 'http://127.0.0.1:4096', username: process.env.OPENCODE_SERVER_USERNAME || 'opencode', password: process.env.OPENCODE_SERVER_PASSWORD, port: process.env.PORT || 3340, host: '127.0.0.1', window: process.env.WINDOW_HOURS || 4, open: false, demo: false };
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    const [flag, inline] = args[i].split(/=(.*)/s);
+    if (['--help', '-h'].includes(flag)) { console.log(help); process.exit(0); }
+    if (['--open', '--demo'].includes(flag)) { if (inline !== undefined) throw new Error(`${flag} does not take a value.`); config[flag.slice(2)] = true; continue; }
+    if (!['--server', '--username', '--port', '--host', '--window', '--allowed-host'].includes(flag)) throw new Error('Unknown option. Use --help. Passwords are accepted only via OPENCODE_SERVER_PASSWORD.');
+    const value = inline ?? args[++i];
+    if (!value || value.startsWith('--')) throw new Error(`Missing value for ${flag}.`);
+    if (flag === '--allowed-host') (config.allowedHosts ||= []).push(value); else config[flag.slice(2)] = value;
+  }
+  config.port = Number(config.port); config.window = Number(config.window);
+  if (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535) throw new Error('--port must be an integer from 1 to 65535.');
+  if (!Number.isFinite(config.window) || config.window <= 0) throw new Error('--window must be a positive number of hours.');
+  let url;
+  try { url = new URL(config.server); } catch { throw new Error('--server must be a valid HTTP(S) URL.'); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error('--server must be HTTP(S), without credentials, query or fragment.');
+  config.server = url.href.replace(/\/$/, '');
+  if (config.host === '[::1]') config.host = '::1';
+  if (!['127.0.0.1', 'localhost', '::1'].includes(config.host)) console.error('WARNING: UI has no authentication and exposes session data. Non-loopback bind requested.');
+  if (config.password && url.protocol === 'http:' && !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)) console.error('WARNING: use HTTPS for a remote OpenCode server; Basic authentication is not encrypted over HTTP.');
+  await start(config);
+  if (config.open) {
+    const target = `http://${config.host.includes(':') ? `[${config.host}]` : config.host}:${config.port}`;
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'rundll32' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', target] : [target];
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' }); child.on('error', () => console.error('Unable to open browser; open the UI URL manually.')); child.unref();
+  }
+} catch (error) { console.error(error.message); process.exitCode = 1; }

package/docs/architecture.md

@@ -0,0 +1,58 @@
+# Architecture
+
+Agent Flow is a read-only backend-for-frontend (BFF) for OpenCode V2. Node.js
+20+ serves static browser assets and aggregates the public HTTP API in memory.
+There is no database access, build step, or runtime npm dependency.
+
+## Data lifecycle
+
+1. Check `/api/info` for a V2 server version. Authenticate with Basic only when
+   an environment password is configured. Credentials never reach the browser.
+2. Open one global `/api/event` SSE subscription before loading history.
+3. Page `/api/session` descending by `time.updated`, stopping locally at the
+   aggregation cutoff: the earliest of the activity window, 12 hours, and midnight.
+4. Recover missing ancestors and recursively enumerate children of active roots,
+   including dormant children. Fetch message pages with concurrency capped at four.
+   Messages have no time filter; pagination stops locally after an old page.
+5. Semantic SSE events mark affected sessions dirty. Coalesced GET requests replace
+   authoritative session/message snapshots, avoiding double-counted usage and
+   duplicated tool events. Reconnect uses exponential backoff (1–30 seconds), then
+   resynchronizes snapshots. A 60-second reconciliation covers missed events.
+6. Poll pending permissions and forms every five seconds for every known active
+   session directory. Locations refer to the upstream server, not the BFF machine.
+
+The selected-session endpoint lazily loads the complete descendant history,
+including sessions outside the activity window. Default aggregates include only
+the aggregation horizon; session-scoped aggregates include the selected tree.
+The in-memory cache lasts for the process lifetime; no prompts or tool results
+are written to disk. Unknown events are ignored or reconciled by snapshots.
+
+## Browser contract
+
+- `GET /api/state[?session=ID]`: roots, trees, grouped agents, last 200 events,
+  token aggregates, pending approvals, permission health, upstream version/status.
+- `GET /api/sessions`: recent root session picker summaries.
+- `GET /api/stream[?session=ID]`: `event: state` snapshots and 15-second heartbeats.
+- `GET /api/permission/request`: normalized pending permissions/forms.
+
+Children with the same nonempty agent name under one parent form a group (`×N`).
+Unnamed sessions retain distinct identities; empty unnamed children are hidden.
+Group status precedence is waiting, working, idle, done. `agentCount` counts visible
+groups including the root; `callCount` counts all descendant sessions including
+the root. Group popovers preserve individual sessions and token totals.
+
+Statuses use active-session snapshots, running tools, pending permissions/forms,
+and final idle messages. Context is the latest assistant input plus cache read and
+write; missing current usage is marked estimated. Costs use `prices.json` and are
+always approximate (`≈ est.`), not provider billing.
+
+## Rendering and security
+
+Vanilla browser modules render all/session modes, event log, hourly token chart,
+cache ratio, activity heatmap, estimated cost, ledger and accessible group popovers.
+Vendored three.js powers WebGL flow connections with a Canvas fallback.
+
+Static assets use an explicit allowlist. The BFF exposes only GET routes, not a
+general upstream proxy. Loopback is the default; non-loopback binding warns that
+the UI has no authentication. Use HTTPS for remote upstream Basic authentication.
+See [API contract notes](opencode-v2-api-notes.md) for compatibility limitations.

package/docs/opencode-v2-api-notes.md

@@ -0,0 +1,121 @@
+# OpenCode V2 public API: contributor notes
+
+Contract verified against OpenCode **2.0.30** and clean **2.0.32**. The server describes this HTTP API
+as experimental. Version checks reject non-V2 servers but do not guarantee that
+every future V2 revision preserves this contract.
+
+## HTTP snapshots
+
+| Endpoint | Response and important details |
+| --- | --- |
+| `/api/info` | Server `version`; OpenAPI info.version is not the server version |
+| `/api/session?order=desc&limit=100` | `{data: Session[], cursor:{previous,next}}`, ordered by time.updated then ID |
+| `/api/session?parentID=ID` | Children, also paginated; parentID=null lists roots |
+| `/api/session/ID` | `{data: Session}` |
+| `/api/session/ID/message?order=desc&limit=100` | `{data: Message[],cursor}`, sequence order within a session |
+| `/api/session/active` | `{data: {sessionID: {type:"running"}}}` |
+| `/api/permission/request?location[directory]=PATH` | `{location,data: Permission[]}` |
+| `/api/form?location[directory]=PATH` | `{location,data: Form[]}` |
+
+Subsequent pages use opaque `cursor` **without order**. Stop on empty pages as
+well as null cursors: the final nonempty page may still contain a next cursor.
+There are no session/message time filters. Apply cutoffs locally. Archived
+sessions are not automatically excluded. A session directory is
+`session.location.directory`; parentID is a tree edge, while fork is not.
+Old descendants must be loaded independently of an updated-time cutoff.
+
+Messages contain `id`, `type`, `time.created`, and assistant `content`, `model`,
+`tokens`, optional `finish`, `time.streamed/completed`. Tool content contains
+`id`, `name`, `state.input/status`, `time.created/ran/completed`. Statuses are
+streaming, running, completed, error; streaming input can be a JSON string.
+Unfiltered history includes idle messages, although `type=idle` is rejected.
+The public API does not expose message row update timestamps or sequence fields.
+
+Tokens are `{input,output,reasoning,cache:{read,write}}`. Session token totals are
+cumulative: replace them, never add successive usage snapshots. A latest
+assistant token snapshot approximates context size. Model cost can be zero;
+local pricing is an estimate, not billing.
+
+Permissions and forms are **location-scoped**. Omitting location only accesses
+the server's default directory, not every session. Permission resources use
+`resources: string[]`; forms contain id, sessionID, title and fields. Pending
+forms count as waiting too. Session-scoped alternatives exist at
+`/api/session/ID/permission` and `/api/session/ID/form`.
+
+## Global event stream
+
+`GET /api/event` covers all locations with one subscription. Frames use `data:`
+containing JSON `{id,created,type,location?,data,durable?}`. The first frame is
+`server.connected`. Heartbeats are comments. There is no documented replay,
+time filter, cursor, or Last-Event-ID recovery; JSON event IDs do not imply replay.
+Slow readers may be disconnected. The BFF must reconnect and reload snapshots.
+
+Relevant event families include:
+
+- session.created/deleted/renamed/moved, agent.selected/model.selected
+- session.step.started/streamed/ended/failed and session.usage.updated
+- session.tool.input.started/delta/ended, tool.called/progress/success/failed
+- session.text.started/delta/ended, reasoning.started/delta/ended
+- session.execution.started/succeeded/failed/interrupted, session.status/idle
+- session.inbox.*, permission.asked/replied, form.created/replied/cancelled
+
+Most data carries `sessionID`; assistant events carry `assistantMessageID` and
+tool events carry tool `id`. form.created nests its session ID in `data.form`.
+V1-style message.updated and message.part.updated events are not available.
+Invalidating per-session snapshots avoids implementing a fragile full event store.
+Do not log reasoning, prompts, tool outputs, form answers or authorization headers.
+
+The experimental session log endpoint did not yield historical events in the
+verified deployment (only log.synced); it is not used as a recovery guarantee.
+Historical permission decisions and transient streaming deltas are not recoverable
+from standard snapshots. Exact message row update timestamps cannot be reproduced.
+
+## Authentication and portability
+
+Basic authentication works with the configured server username/password. A
+protected server returns 401 without credentials. Bearer authentication is not
+equivalent. Keep credentials in environment variables and use HTTPS remotely.
+Native browser EventSource cannot set Authorization, and arbitrary origins may
+not be allowed by upstream CORS. The same-origin Node BFF avoids both issues.
+It never forwards credentials to browser clients and performs only GET requests.
+
+Verified against 2.0.30: version, session/active snapshots, pagination, idle
+messages, location-scoped pending requests, Basic authentication and a live global
+stream containing multiple locations. Remote deployments and future versions
+require additional verification; capability changes should fail clearly.
+
+### Clean 2.0.32 verification (2026-10-17)
+
+Installed official `@opencode/cli@2.0.32` locally with isolated HOME/XDG paths;
+the similarly named `opencode-ai` npm package is V1. No existing service or data
+was used. Root and linked child sessions were created through `POST /api/session`
+without model calls. One CLIProxy `gemini-3.8-flash-high` turn read a fixture
+README using `read` and completed successfully.
+
+Session/message/active snapshots and the global SSE envelope still match the
+contract above. Observed 22 frames including `session.tool.input.started/ended`,
+`session.tool.called/success`, `session.step.*`, `session.usage.updated`,
+`session.text.*`, and `session.execution.started/succeeded`. Tool events retain
+`data.sessionID`, `data.assistantMessageID`, and `data.id`. The BFF emitted four
+live state frames (idle → working → tool completion → idle), retained the child,
+and reported 10,301 input tokens, matching the two assistant snapshots. Upstream
+output tokens were zero despite a text answer; the BFF preserves reported usage
+rather than inventing output counts.
+
+Both `/api/state` and `/api/state?session=ID`, `/api/sessions`, and the browser
+session view were verified. Browser viewport: 1440×900; no console errors or
+failed requests (headless WebGL ReadPixels performance warnings only).
+
+Authentication caveat: an unset password does **not** produce an unprotected
+server on this clean version. `serve` generates a password and unauthenticated
+requests return 401. Basic auth works with both its generated password and an
+explicit `OPENCODE_SERVER_PASSWORD`; a real password-free upstream scenario was
+therefore unavailable. Wrong credentials now produce an actionable 401 log
+without exposing credentials, while retaining the existing retry behavior.
+Successful initialization logs the negotiated server version. No event-schema
+adapter changes were needed. Multi-location streams and permission/form flows
+were not re-exercised on 2.0.32; their earlier 2.0.30 checks remain the evidence.
+
+Sources: [API](https://opencode.ai/v2/docs/api),
+[client](https://opencode.ai/v2/docs/build/client), published
+`@opencode/client@2.0.30` event types, and live read-only HTTP/SSE observations.

package/lib/demo.mjs

@@ -0,0 +1,42 @@
+export function demo(onChange = () => {}, { interval = setInterval, cancel = clearInterval, clock = Date.now } = {}) {
+  const now = Date.now(), sessions = new Map(), messages = new Map();
+  const agents = ['lead', 'builder', 'researcher', 'reviewer', 'builder', 'tester', 'designer'];
+  agents.forEach((agent, i) => {
+    const id = `ses_demo${i}`, model = { id: ['gpt-6.1-sol', 'claude-sonnet-4-5', 'gemini-2.5-pro'][i % 3] };
+    sessions.set(id, { id, parentID: i ? 'ses_demo0' : undefined, title: i ? `${agent} · public API integration` : 'Build a better developer experience', agent, model, time: { created: now - 3600000, updated: now - i * 1000 }, tokens: { input: 24000 + i * 7000, output: 3200, cache: { read: 180000 + i * 19000, write: 0 } } });
+    messages.set(id, [{ id: `msg_demo${i}`, type: 'assistant', model, time: { created: now - 90000 + i * 5000, completed: now - 20000 }, tokens: { input: 12000, output: 1200, cache: { read: 48000, write: 0 } }, content: [{ id: `call_demo${i}`, type: 'tool', name: ['read', 'patch', 'webfetch', 'grep', 'shell', 'shell', 'read'][i], state: { status: i === 1 || i === 2 ? 'running' : 'completed', input: { path: ['src/index.ts', 'src/api/client.ts', 'https://example.org/docs', 'src/**/*.ts', 'npm test', 'npm run check', 'docs/design.md'][i] } }, time: { created: now - 30000 + i * 2000, completed: now - 10000 } }], finish: 'tool-calls' }]);
+  });
+  let timer, tick = 0;
+  const tools = [
+    ['read', 'src/index.ts'], ['patch', 'src/api/client.ts'],
+    ['webfetch', 'https://example.org/docs'], ['grep', 'src/**/*.ts'],
+    ['shell', 'npm test'], ['shell', 'npm run check'], ['read', 'docs/design.md']
+  ];
+  const state = { sessions, messages, active: { ses_demo1: { type: 'running' }, ses_demo2: { type: 'running' } }, approvals: [], health: { ok: true, status: 200 }, version: '2.0.32', connection: 'connected', cutoff: () => clock() - 86400000,
+    start: async () => {
+      if (timer !== undefined) return;
+      timer = interval(() => {
+        tick++;
+        const time = clock();
+        state.active = {};
+        agents.forEach((agent, i) => {
+          const id = `ses_demo${i}`, previous = sessions.get(id);
+          const working = i === 0 || (tick + i) % 4 !== 0;
+          if (working) state.active[id] = { type: 'running' };
+          sessions.set(id, { ...previous, time: { ...previous.time, updated: time }, tokens: { ...previous.tokens, output: previous.tokens.output + 24 } });
+          // Replace arrays/objects to invalidate the BFF's identity-based caches.
+          const history = messages.get(id).map(message => ({ ...message, time: { ...message.time, completed: time }, content: message.content.map(tool => ({ ...tool, state: { ...tool.state, status: 'completed' }, time: { ...tool.time, completed: time } })) }));
+          const [name, path] = tools[(tick + i) % tools.length];
+          const tool = { id: `call_demo${i}_${tick}`, type: 'tool', name, state: { status: working ? 'running' : 'completed', input: { path } }, time: { created: time, ...(working ? {} : { completed: time }) } };
+          history.push({ id: `msg_demo${i}_${tick}`, type: 'assistant', model: previous.model, time: { created: time }, tokens: { input: 12000, output: 1200 + tick % 100, cache: { read: 48000, write: 0 } }, content: [tool], finish: 'tool-calls' });
+          messages.set(id, history.slice(-12));
+        });
+        onChange();
+      }, 1500);
+      timer.unref?.();
+    },
+    stop() { if (timer !== undefined) cancel(timer); timer = undefined; },
+    ensureTree: async () => {}
+  };
+  return state;
+}

package/lib/privacy.mjs

@@ -0,0 +1,9 @@
+// Best-effort display redaction, not a security boundary.
+export function clip(value, limit = 180) {
+  return String(value ?? '')
+    .replace(/\bBearer\s+\S+/gi, 'Bearer [redacted]')
+    .replace(/(-u\s+)\S+:\S+/g, '$1[redacted]')
+    .replace(/((?:--)?(?:password|token|secret|authorization|api[_-]?key)["']?\s*(?:[:=]\s*|\s+))["']?[^\s,;"'}]+["']?/gi, '$1[redacted]')
+    .replace(/\b(?:sk-[\w-]+|ghp_[\w]+|github_pat_[\w_]+|xox[bp]-[\w-]+|AKIA[A-Z0-9]+)\b/g, '[redacted]')
+    .slice(0, limit);
+}