opencode-agent-flow 0.0.0-stage → 0.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,101 @@
-# 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.
+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.
+
+![Agent Flow demo dashboard](docs/screenshot.png)
+
+## Quick start
+
+```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
+```
+
+Open <http://127.0.0.1:3340>. For an unpublished local checkout:
+`node bin/cli.mjs --demo`.
+
+## 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.
+
+## Security and compatibility
+
+- 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).
+- 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
+  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 --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.
+
+## 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,52 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+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
+
+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,89 @@
+# OpenCode V2 public API: contributor notes
+
+Contract verified against OpenCode **2.0.30**. 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.
+
+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,10 @@
+export function demo() {
+  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' }]);
+  });
+  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 () => {} };
+}

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);
+}

package/lib/upstream.mjs

@@ -0,0 +1,190 @@
+export function reconnectDelay(delay, connectedAt, now = Date.now()) { return connectedAt !== undefined && now - connectedAt >= 30000 ? 1000 : delay; }
+export function trimMessage(m) {
+  return { id: m.id, type: m.type, time: m.time, tokens: m.tokens, agent: m.agent, model: m.model, finish: m.finish, outcome: String(m.outcome || '').slice(0, 300), content: (m.content || []).map(c => ({ type: c.type, name: c.name || c.tool, id: c.id, time: c.time, text: String(c.text || '').slice(0, 300), state: { status: c.state?.status, time: c.state?.time, input: Object.fromEntries(Object.entries(c.state?.input || c.input || {}).filter(([key]) => ['code', 'filePath', 'path', 'pattern', 'command', 'query', 'url', 'agent', 'description'].includes(key)).map(([key, value]) => [key, String(value).slice(0, 300)])) } })) };
+}
+export class Upstream {
+  constructor(config, changed) {
+    Object.assign(this, { config, changed, sessions: new Map(), messages: new Map(), messageVersions: new Map(), fullHistory: new Set(), active: {}, approvals: [], health: { ok: false }, connection: 'connecting', dirty: new Set(), queue: [], jobs: 0, abort: new AbortController() });
+  }
+  async request(path, signal) {
+    const headers = this.config.password ? { Authorization: `Basic ${Buffer.from(`${this.config.username}:${this.config.password}`).toString('base64')}` } : {};
+    const response = await fetch(`${this.config.server}${path}`, { headers, redirect: 'error', signal: AbortSignal.any([this.abort.signal, signal || AbortSignal.timeout(15000)]) });
+    if (!response.ok) { await response.body?.cancel(); throw new Error(response.status === 401 ? 'OpenCode returned 401: set OPENCODE_SERVER_PASSWORD (and optionally OPENCODE_SERVER_USERNAME).' : `OpenCode API returned HTTP ${response.status}.`); }
+    return response;
+  }
+  async get(path) { return (await this.request(path)).json(); }
+  async limited(fn) {
+    if (this.jobs >= 4) await new Promise(resolve => this.queue.push(resolve));
+    else this.jobs++;
+    try { return await fn(); } finally { const next = this.queue.shift(); if (next) next(); else this.jobs--; }
+  }
+  cutoff() { return Math.min(Date.now() - Math.max(12, this.config.window) * 3600000, new Date().setHours(0, 0, 0, 0)); }
+  async pages(path, stop = () => false, compact = value => value) {
+    const all = []; let cursor; const seen = new Set();
+    do {
+      const body = await this.get(`${path}${path.includes('?') ? '&' : '?'}limit=100&${cursor ? `cursor=${encodeURIComponent(cursor)}` : 'order=desc'}`);
+      if (!Array.isArray(body.data)) throw new Error('Unsupported OpenCode V2 list response.');
+      all.push(...body.data.map(compact));
+      if (!body.data.length || stop(body.data)) break;
+      cursor = body.cursor?.next;
+      if (seen.has(cursor)) break; seen.add(cursor);
+    } while (cursor);
+    return all;
+  }
+  async loadMessages(id, full = false, recent = false) {
+    full ||= this.fullHistory.has(id);
+    return this.limited(async () => {
+      const version = this.sessions.get(id)?.time?.updated;
+      const previous = this.messages.get(id), known = new Set(previous?.map(m => m.id));
+      const list = await this.pages(`/api/session/${encodeURIComponent(id)}/message`, page => recent && page.some(m => known.has(m.id)) || !full && page.every(m => m.time?.created < this.cutoff()), trimMessage);
+      if (!this.sessions.has(id)) return;
+      const compact = list.map(trimMessage);
+      if (recent && previous) {
+        const merged = new Map(previous.map(m => [m.id, m]));
+        for (const message of compact.reverse()) merged.set(message.id, message);
+        this.messages.set(id, [...merged.values()].filter(m => full || Math.max(m.time?.created || 0, m.time?.completed || 0) >= this.cutoff()));
+      } else this.messages.set(id, compact.reverse().filter(m => full || Math.max(m.time?.created || 0, m.time?.completed || 0) >= this.cutoff()));
+      if (!recent) this.messageVersions.set(id, version);
+    });
+  }
+  async loadSession(id) {
+    const body = await this.get(`/api/session/${encodeURIComponent(id)}`);
+    if (body.data) this.sessions.set(id, body.data);
+  }
+  removeSession(id, seen = new Set()) {
+    if (seen.has(id)) return; seen.add(id);
+    for (const child of this.sessions.values()) if (child.parentID === id) this.removeSession(child.id, seen);
+    this.sessions.delete(id); this.messages.delete(id); this.fullHistory.delete(id); this.messageVersions.delete(id);
+  }
+  async descendants(ids) {
+    const seen = new Set(); let pending = [...ids];
+    while (pending.length) {
+      const batch = pending.filter(id => !seen.has(id)); pending = [];
+      if (!batch.length) break;
+      await Promise.all(batch.map(id => this.limited(async () => {
+        seen.add(id);
+        const children = await this.pages(`/api/session?parentID=${encodeURIComponent(id)}`), ids = new Set(children.map(child => child.id));
+        for (const child of this.sessions.values()) if (child.parentID === id && !ids.has(child.id)) this.removeSession(child.id);
+        for (const child of children) { this.sessions.set(child.id, child); pending.push(child.id); }
+      })));
+    }
+    return seen;
+  }
+  async sync(force = false) {
+    if (this.syncing) return this.syncing;
+    this.syncing = (async () => {
+      const list = await this.pages('/api/session', page => page.at(-1)?.time?.updated < this.cutoff());
+      const listed = new Set(list.map(s => s.id));
+      for (const s of this.sessions.values()) if (!this.fullHistory.has(s.id) && !s.parentID && (s.time?.updated < this.cutoff() || !listed.has(s.id))) this.removeSession(s.id);
+      for (const s of list) if (s.time?.updated >= this.cutoff() || this.fullHistory.has(s.id)) this.sessions.set(s.id, s);
+      for (const s of [...this.sessions.values()]) { let parent = s.parentID; const seen = new Set(); while (parent && !this.sessions.has(parent) && !seen.has(parent)) { seen.add(parent); await this.loadSession(parent); parent = this.sessions.get(parent)?.parentID; } }
+      const roots = [...this.sessions.values()].filter(s => !s.parentID && !s.time?.archived && s.time?.updated >= Date.now() - this.config.window * 3600000);
+      const tree = await this.descendants([...roots.map(s => s.id), ...this.fullHistory]);
+      this.evict(tree);
+      await Promise.all([...this.sessions.values()].filter(s => (tree.has(s.id) || s.time?.updated >= this.cutoff() || !this.messages.has(s.id)) && (force || !this.messages.has(s.id) || this.active[s.id] || this.messageVersions.get(s.id) !== s.time?.updated)).map(s => this.loadMessages(s.id)));
+      this.active = (await this.get('/api/session/active')).data || {};
+      await this.pollPending(); this.changed();
+    })().finally(() => { this.syncing = null; });
+    return this.syncing;
+  }
+  async ensureTree(id) {
+    await this.loadSession(id); const ids = await this.descendants([id]);
+    this.historyScopes ||= new Map(); this.historyScopes.delete(id); this.historyScopes.set(id, ids);
+    while (this.historyScopes.size > 20) this.historyScopes.delete(this.historyScopes.keys().next().value);
+    this.fullHistory = new Set([...this.historyScopes.values()].flatMap(scope => [...scope]));
+    await Promise.all([...ids].map(sid => this.loadMessages(sid, true))); this.changed();
+  }
+  evict(tree = new Set()) {
+    for (const s of [...this.sessions.values()]) if (!tree.has(s.id) && !this.fullHistory.has(s.id) && s.time?.updated < this.cutoff()) this.removeSession(s.id);
+    for (const [id, messages] of this.messages) if (!this.fullHistory.has(id)) this.messages.set(id, messages.filter(m => Math.max(m.time?.created || 0, m.time?.completed || 0) >= this.cutoff()));
+  }
+  touchScope(id) { const scope = this.historyScopes?.get(id); if (scope) { this.historyScopes.delete(id); this.historyScopes.set(id, scope); } }
+  async pollPending() {
+    if (this.pendingPoll) return;
+    this.pendingPoll = true;
+    const previous = JSON.stringify([this.approvals, this.health]);
+    try {
+      const locations = new Set([...this.sessions.values()].filter(s => this.active[s.id] || s.time?.updated >= Date.now() - this.config.window * 3600000).map(s => s.location?.directory).filter(Boolean));
+      const approvals = [];
+      await Promise.all([...locations].map(directory => this.limited(async () => {
+        const query = `?location%5Bdirectory%5D=${encodeURIComponent(directory)}`;
+        const permissions = await this.get(`/api/permission/request${query}`), forms = await this.get(`/api/form${query}`);
+        for (const p of permissions.data || []) approvals.push({ id: p.id, sessionID: p.sessionID, action: p.action || 'permission', resource: (p.resources || []).join(', '), time: this.approvals.find(a => a.id === p.id)?.time || Date.now() });
+        for (const f of forms.data || []) approvals.push({ id: f.id, sessionID: f.sessionID, action: 'form', resource: f.title || 'Input requested', time: this.approvals.find(a => a.id === f.id)?.time || Date.now() });
+      })));
+      this.approvals = approvals; this.health = { ok: true, status: 200 };
+    } catch { this.health = { ok: false, status: null }; }
+    finally { this.pendingPoll = false; if (previous !== JSON.stringify([this.approvals, this.health])) this.changed(); }
+  }
+  event(event) {
+    const data = event.data || {}, id = data.sessionID || data.form?.sessionID;
+    if (!id) return;
+    if (event.type === 'session.deleted') { this.removeSession(id); this.changed(); return; }
+    this.dirty.add(id);
+    if (/permission\.|form\./.test(event.type)) void this.pollPending();
+    if (!this.dirtyTimer) this.dirtyTimer = setTimeout(() => {
+      this.dirtyTimer = null; const ids = [...this.dirty]; this.dirty.clear();
+      void Promise.allSettled(ids.map(sid => this.limited(() => this.loadSession(sid)).then(() => this.loadMessages(sid, false, true)))).then(async () => { this.active = (await this.get('/api/session/active')).data || {}; this.changed(); }).catch(() => console.error('OpenCode live refresh failed; reconciliation will retry.'));
+    }, 250);
+  }
+  async stream() {
+    let delay = 1000;
+    while (!this.abort.signal.aborted) {
+      const controller = new AbortController(), abort = () => controller.abort();
+      this.abort.signal.addEventListener('abort', abort, { once: true });
+      let watchdog = setTimeout(abort, 45000), connectedAt;
+      try {
+        const response = await this.request('/api/event', controller.signal);
+        this.connection = 'connected'; this.changed();
+        connectedAt = Date.now();
+        if (!this.lastResync || Date.now() - this.lastResync >= 10000) { this.lastResync = Date.now(); void this.sync(true).catch(() => console.error('OpenCode resynchronization failed; retrying periodically.')); }
+        let buffer = ''; const decoder = new TextDecoder();
+        for await (const chunk of response.body) {
+          clearTimeout(watchdog); watchdog = setTimeout(abort, 45000);
+          buffer += decoder.decode(chunk, { stream: true }); buffer = buffer.replace(/\r\n/g, '\n');
+          let end;
+          while ((end = buffer.indexOf('\n\n')) >= 0) {
+            const frame = buffer.slice(0, end); buffer = buffer.slice(end + 2);
+            const text = frame.split('\n').filter(line => line.startsWith('data:')).map(line => line.slice(5).trimStart()).join('\n');
+            if (text) { try { this.event(JSON.parse(text)); } catch { /* Ignore unknown envelopes. */ } }
+          }
+          if (buffer.length > 8 * 1024 * 1024) throw new Error('Oversized SSE frame');
+        }
+        if (!this.abort.signal.aborted) throw new Error('SSE closed');
+      } catch {
+        if (this.abort.signal.aborted) break;
+        delay = reconnectDelay(delay, connectedAt);
+        this.connection = 'reconnecting'; this.changed();
+        console.error(`OpenCode event stream disconnected; reconnecting in ${delay / 1000}s.`);
+        await new Promise(resolve => { const finish = () => { clearTimeout(t); this.abort.signal.removeEventListener('abort', finish); resolve(); }; const t = setTimeout(finish, delay); this.abort.signal.addEventListener('abort', finish, { once: true }); });
+        delay = Math.min(delay * 2, 30000);
+      } finally {
+        clearTimeout(watchdog); this.abort.signal.removeEventListener('abort', abort); controller.abort();
+      }
+    }
+  }
+  async start() {
+    void this.initialize();
+  }
+  async initialize() {
+    let delay = 1000;
+    while (!this.abort.signal.aborted) {
+    try {
+    let info;
+    try { info = await this.get('/api/info'); } catch (error) { throw new Error(`Cannot connect to OpenCode V2. ${error.message}`); }
+    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();
+    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 {
+      if (this.abort.signal.aborted) return;
+      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);
+    }
+    }
+  }
+  stop() { this.abort.abort(); clearInterval(this.syncTimer); clearInterval(this.pendingTimer); clearTimeout(this.dirtyTimer); }
+}

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "opencode-agent-flow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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" },
+  "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" },
+  "homepage": "https://github.com/orybakov/opencode-agent-flow#readme",
+  "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" }
+}

package/prices.json

@@ -0,0 +1,10 @@
+{
+  "note": "Illustrative placeholders, USD per 1M tokens, not subscription billing. Context limits are estimates; edit to match your provider.",
+  "default": { "input": 3, "output": 15, "cacheRead": 0.3, "contextLimit": 200000 },
+  "models": {
+    "claude-opus-5-5": { "input": 5, "output": 25, "cacheRead": 0.5, "contextLimit": 200000 },
+    "claude-sonnet-5-5": { "input": 3, "output": 15, "cacheRead": 0.3, "contextLimit": 200000 },
+    "gpt-6.1-sol": { "input": 2.5, "output": 15, "cacheRead": 0.25, "contextLimit": 200000 },
+    "gemini-3.8-flash-high": { "input": 0.5, "output": 3, "cacheRead": 0.05, "contextLimit": 1000000 }
+  }
+}