opencode-agent-flow 0.1.0 → 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/README.md

@@ -1,5 +1,12 @@
 # opencode-agent-flow
 
+[![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
@@ -7,23 +14,79 @@ only its public HTTP API and SSE—no database access required.
 
 Zero runtime npm dependencies. Node.js 20+; no frontend build step.
 
-![Agent Flow demo dashboard](docs/screenshot.png)
+![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
-# Protected server: supply the password through your environment, not CLI flags.
-OPENCODE_SERVER_PASSWORD="$YOUR_OPENCODE_PASSWORD" npx opencode-agent-flow
-# Remote server
-OPENCODE_SERVER_PASSWORD="$YOUR_OPENCODE_PASSWORD" npx opencode-agent-flow --server https://opencode.example.org
-# Fictional data, no server required
-npx opencode-agent-flow --demo --open
+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 |
@@ -57,7 +120,19 @@ individual-call popovers preserve the orchestration hierarchy.
 including the root. The recent activity window applies to root selection; explicit
 session mode loads the complete selected tree, including dormant children.
 
-## Security and compatibility
+## 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
@@ -70,8 +145,6 @@ session mode loads the complete selected tree, including dormant children.
   **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).
-- Tested against **OpenCode 2.0.30**. The V2 HTTP API is **experimental**; future
-  changes may require adapter updates. Non-V2 servers remain in connecting state.
 - 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
@@ -87,7 +160,8 @@ subscriptions may differ, and these figures are not billing statements.
 
 ```sh
 node bin/cli.mjs --demo
-node --test
+node scripts/check-syntax.mjs
+npm test
 npm pack --dry-run
 ```
 
@@ -95,6 +169,13 @@ 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/),

package/bin/cli.mjs

@@ -1,10 +1,12 @@
 #!/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 help = `opencode-agent-flow 0.1.0 — live OpenCode V2 agent visualization
+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)

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

@@ -1,6 +1,6 @@
 # OpenCode V2 public API: contributor notes
 
-Contract verified against OpenCode **2.0.30**. The server describes this HTTP API
+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.
 
@@ -84,6 +84,38 @@ messages, location-scoped pending requests, Basic authentication and a live glob
 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

@@ -1,4 +1,4 @@
-export function demo() {
+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) => {
@@ -6,5 +6,37 @@ export function demo() {
     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' }]);
   });
-  return { sessions, messages, active: { ses_demo1: { type: 'running' }, ses_demo2: { type: 'running' } }, approvals: [], health: { ok: true, status: 200 }, version: '2.0.30', connection: 'connected', cutoff: () => now - 86400000, start: async () => {}, stop() {}, ensureTree: async () => {} };
+  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/upstream.mjs

@@ -167,7 +167,7 @@ export class Upstream {
     void this.initialize();
   }
   async initialize() {
-    let delay = 1000;
+    let delay = 1000, lastError;
     while (!this.abort.signal.aborted) {
     try {
     let info;
@@ -175,11 +175,15 @@ export class Upstream {
     this.version = info.version || info.data?.version;
     if (!/^2\./.test(this.version || '')) throw new Error('Unsupported server: OpenCode V2 /api/info version 2.x is required.');
     await this.sync(); if (this.abort.signal.aborted) return; void this.stream();
+    console.log(`Connected to OpenCode ${this.version}.`);
     this.syncTimer = setInterval(() => { void this.sync().catch(() => console.error('OpenCode reconciliation failed; retrying in 60s.')); }, 60000);
     this.pendingTimer = setInterval(() => { void this.pollPending(); }, 5000);
     return;
-    } catch {
+    } catch (error) {
       if (this.abort.signal.aborted) return;
+      // Keep retrying, but do not silently hide authentication/version failures.
+      const message = error.message;
+      if (message !== lastError) { console.error(message); lastError = message; }
       this.connection = 'connecting'; this.changed();
       await new Promise(resolve => { const finish = () => { clearTimeout(timer); this.abort.signal.removeEventListener('abort', finish); resolve(); }; const timer = setTimeout(finish, delay); this.abort.signal.addEventListener('abort', finish, { once: true }); });
       delay = Math.min(delay * 2, 30000);

package/package.json

@@ -1,17 +1,48 @@
 {
   "name": "opencode-agent-flow",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Live agent flow visualization for OpenCode V2 over its public HTTP API and SSE",
   "type": "module",
-  "bin": { "opencode-agent-flow": "bin/cli.mjs" },
-  "engines": { "node": ">=20" },
+  "bin": {
+    "opencode-agent-flow": "bin/cli.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "license": "MIT",
   "author": "orybakov (https://github.com/orybakov)",
-  "repository": { "type": "git", "url": "https://github.com/orybakov/opencode-agent-flow.git" },
-  "bugs": { "url": "https://github.com/orybakov/opencode-agent-flow/issues" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orybakov/opencode-agent-flow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/orybakov/opencode-agent-flow/issues"
+  },
   "homepage": "https://github.com/orybakov/opencode-agent-flow#readme",
-  "keywords": ["opencode", "ai-agents", "visualizer", "observability", "webgl"],
+  "keywords": [
+    "opencode",
+    "ai-agents",
+    "visualizer",
+    "observability",
+    "webgl"
+  ],
   "exports": {},
-  "files": ["bin", "server.mjs", "lib", "public", "prices.json", "README.md", "LICENSE", "SECURITY.md", "CONTRIBUTING.md", "docs/*.md", "docs/screenshot.png"],
-  "scripts": { "start": "node bin/cli.mjs", "test": "node --test" }
+  "files": [
+    "bin",
+    "server.mjs",
+    "lib",
+    "public",
+    "prices.json",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md",
+    "docs/*.md",
+    "docs/screenshot.png"
+  ],
+  "scripts": {
+    "start": "node bin/cli.mjs",
+    "test": "node --test"
+  }
 }

package/server.mjs

@@ -15,7 +15,7 @@ const json = s => { try { return JSON.parse(s || '{}'); } catch { return {}; } }
 const modelId = m => clip((typeof m === 'string' ? m : m?.id || m?.modelID) || 'unknown', 100);
 const rate = m => prices.models[m] || Object.entries(prices.models).find(([k]) => m.startsWith(k))?.[1] || prices.default;
 let snapshot, signature = '', timer;
-const upstream = config.demo ? demo() : new Upstream(config, schedule);
+const upstream = config.demo ? demo(schedule) : new Upstream(config, schedule);
 let approvals = [], permissionHealth = { ok: false, status: null };
 const clients = new Set();
 const rowCache = new Map();