Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(chat): gate opencode exports on a db stat, space live refreshes, honour page size

review9827f3ffaf1b
diff --git a/CLAUDE.md b/CLAUDE.md
index f7547f9dd..64b355494 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1882,15 +1882,26 @@ else, and its context links must keep classifying across restarts).
`Error: …` on a failed call), `[name] message` for an errored turn, compaction/subtask chips,
`at` from `time.created`, `model`/`effort` from the newest assistant's `modelID`/`variant`.
Reasoning, `synthetic`/`ignored` text, file/agent parts and step bookkeeping are dropped;
- unmappable shapes are skipped and counted. **One page, always** (`olderCursor: null`, newest
- messages within 5 MB): there are no byte offsets to page by. Refusals: no/unsafe session id runs
+ unmappable shapes are skipped and counted. **One page, always** (`olderCursor: null`): there are
+ no byte offsets to page by. The page honours the caller's `maxBytes` (the phone asks 256 KB),
+ grows ×4 up to 5 MB like claude's reader when it holds no whole message, and shows a newest
+ message larger than 5 MB TRUNCATED (with a note) rather than as an empty conversation. Refusals: no/unsafe session id runs
nothing (a bare `opencode export` opens a picker over the NEWEST sessions — someone else's); an
export whose `info.id` is another session is `unreadable`; only `Session not found: <id>` with
exit 1 and empty stdout is a clean miss. **Remote (SSH) nodes are refused** (`unreadable`, no
export runs) — their sessions are in the host's database and there is no remote leg yet; the
panel's copy names both causes an opencode `unreadable` can have. One export costs 1.0–1.7 s and
- ~320 MB, so `createOpencodeExportGate` runs at most one per session (starts ≥ 2 s apart, a caller
- arriving mid-run gets a FRESH export, never a cached one) and two in total. Plan/question answer
+ ~320 MB, so `createOpencodeExportGate` runs at most one per session (a caller arriving mid-run
+ gets a FRESH export) and two in total; the panel's hook-driven refreshes are marked
+ `page.background` and spaced ≥ 5 s per session, while an open / ↻ / Retry is immediate (and wakes
+ a sleeping background one). A **change gate** in front of it `stat`s (never opens) opencode's
+ `opencode*.db` + `-wal` in `$XDG_DATA_HOME/opencode` (else `~/.local/share/opencode`, opencode's
+ own xdg-basedir rule) BEFORE exporting, and an unchanged fingerprint answers from a 4-session LRU
+ of parsed exports; no db file found, or `OPENCODE_DB` set, means no caching. The export runs with
+ `cwd: os.tmpdir()` (from a repo cwd opencode writes `<repo>/.git/opencode`; sessions resolve by
+ global id). **It inherits the APP's `process.env`, not the node's shell env**: a user who
+ relocates opencode's data via `XDG_DATA_HOME` / `OPENCODE_*` only in their shell rc gets
+ "Session not found" — an honest miss, not a bug in the reader. Plan/question answer
cards stay claude-only (no `body`/`questions` on opencode's `question` tool). Desktop and Server
Edition both serve it (core handler); the phone gets it over the relay `chat.page` for free.
Fixtures + the exact rules for the iOS port: `src/shared/chat-fixtures/opencode/README.md`.
diff --git a/src/core/opencode-chat-cache.test.ts b/src/core/opencode-chat-cache.test.ts
new file mode 100644
index 000000000..b9a15e1fa
--- /dev/null
+++ b/src/core/opencode-chat-cache.test.ts
@@ -0,0 +1,246 @@
+// Review fixes for the opencode ⌘M reader: the stat change gate + bounded parsed cache, the
+// background-refresh spacing, and the page-size contract (`page.maxBytes`, an oversized newest
+// message). Synthetic data only.
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import {
+ createOpencodeChatCache,
+ createOpencodeExportGate,
+ opencodeDataDir,
+ opencodeDbFingerprint,
+ readOpencodeChat
+} from './opencode-chat'
+import { normalizeChatPage } from '../shared/chat-page'
+import type { OpencodeExportOutcome } from './opencode-export'
+import type { ChatMessage } from '../shared/types'
+
+const SID = 'ses_0a1b2c3d4ffeSynthetic000001'
+const doc = (messages: unknown[]): string =>
+ JSON.stringify({ info: { id: SID }, messages }, null, 2) + '\n'
+const msg = (i: number, role: 'user' | 'assistant', t: string) => ({
+ info: { id: `msg_${i}`, sessionID: SID, role, time: { created: i } },
+ parts: [{ id: `prt_${i}`, type: 'text', text: t }]
+})
+const textOf = (m: ChatMessage) => (m.parts[0] as { text: string }).text
+
+describe('opencodeDataDir — the same resolution opencode uses (xdg-basedir)', () => {
+ it('XDG_DATA_HOME wins, else ~/.local/share; "opencode" under it', () => {
+ expect(opencodeDataDir({ XDG_DATA_HOME: '/x/data' }, '/home/u')).toBe(path.join('/x/data', 'opencode'))
+ expect(opencodeDataDir({}, '/home/u')).toBe(path.join('/home/u', '.local', 'share', 'opencode'))
+ expect(opencodeDataDir({ XDG_DATA_HOME: '' }, '/home/u')).toBe(path.join('/home/u', '.local', 'share', 'opencode'))
+ })
+})
+
+describe('opencodeDbFingerprint — stat, never open', () => {
+ let dir: string
+ beforeEach(() => {
+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-oc-fp-'))
+ })
+ afterEach(() => fs.rmSync(dir, { recursive: true, force: true }))
+
+ it('changes when the WAL changes, and is stable otherwise', async () => {
+ fs.writeFileSync(path.join(dir, 'opencode.db'), 'a')
+ fs.writeFileSync(path.join(dir, 'opencode.db-wal'), 'w')
+ const a = await opencodeDbFingerprint(dir, {})
+ expect(a).not.toBeNull()
+ expect(await opencodeDbFingerprint(dir, {})).toBe(a)
+ fs.appendFileSync(path.join(dir, 'opencode.db-wal'), 'more')
+ expect(await opencodeDbFingerprint(dir, {})).not.toBe(a)
+ })
+
+ it('a missing WAL is a state, not a failure; the db changing changes it', async () => {
+ fs.writeFileSync(path.join(dir, 'opencode.db'), 'a')
+ const a = await opencodeDbFingerprint(dir, {})
+ expect(a).not.toBeNull()
+ fs.appendFileSync(path.join(dir, 'opencode.db'), 'b')
+ expect(await opencodeDbFingerprint(dir, {})).not.toBe(a)
+ })
+
+ it('covers a channel-named database too (opencode-<channel>.db)', async () => {
+ fs.writeFileSync(path.join(dir, 'opencode-dev.db'), 'a')
+ const a = await opencodeDbFingerprint(dir, {})
+ expect(a).not.toBeNull()
+ fs.writeFileSync(path.join(dir, 'opencode-dev.db-wal'), 'w')
+ expect(await opencodeDbFingerprint(dir, {})).not.toBe(a)
+ })
+
+ it('cannot gate (null) with no database, an unreadable dir, or an OPENCODE_DB override', async () => {
+ expect(await opencodeDbFingerprint(dir, {})).toBeNull()
+ expect(await opencodeDbFingerprint(path.join(dir, 'nope'), {})).toBeNull()
+ fs.writeFileSync(path.join(dir, 'opencode.db'), 'a')
+ expect(await opencodeDbFingerprint(dir, { OPENCODE_DB: '/elsewhere.db' })).toBeNull()
+ })
+})
+
+describe('readOpencodeChat — the change gate', () => {
+ const page = normalizeChatPage({ maxBytes: 262144 })
+ const OK = doc([msg(1, 'user', 'hi'), msg(2, 'assistant', 'yo')])
+
+ it('an unchanged database answers from the cache: no second export', async () => {
+ const run = vi.fn(async (): Promise<OpencodeExportOutcome> => ({ ok: true, stdout: OK }))
+ const cache = createOpencodeChatCache({ fingerprint: async () => 'fp1', maxSessions: 4 })
+ const a = await readOpencodeChat({ sessionId: SID }, page, run, cache)
+ const b = await readOpencodeChat({ sessionId: SID }, page, run, cache)
+ expect(b).toStrictEqual(a)
+ expect(a.messages).toHaveLength(2)
+ expect(run).toHaveBeenCalledTimes(1)
+ })
+
+ it('a changed database exports again', async () => {
+ let fp = 'fp1'
+ const run = vi.fn(async (): Promise<OpencodeExportOutcome> => ({ ok: true, stdout: OK }))
+ const cache = createOpencodeChatCache({ fingerprint: async () => fp, maxSessions: 4 })
+ await readOpencodeChat({ sessionId: SID }, page, run, cache)
+ fp = 'fp2'
+ await readOpencodeChat({ sessionId: SID }, page, run, cache)
+ expect(run).toHaveBeenCalledTimes(2)
+ })
+
+ it('the fingerprint is taken BEFORE the export (a write during it forces the next export)', async () => {
+ const order: string[] = []
+ const run = vi.fn(async (): Promise<OpencodeExportOutcome> => {
+ order.push('export')
+ return { ok: true, stdout: OK }
+ })
+ const cache = createOpencodeChatCache({
+ fingerprint: async () => {
+ order.push('stat')
+ return 'fp'
+ },
+ maxSessions: 4
+ })
+ await readOpencodeChat({ sessionId: SID }, page, run, cache)
+ expect(order).toEqual(['stat', 'export'])
+ })
+
+ it('no fingerprint (cannot gate) never caches; a failure is never cached', async () => {
+ const run = vi.fn(async (): Promise<OpencodeExportOutcome> => ({ ok: true, stdout: OK }))
+ const nullCache = createOpencodeChatCache({ fingerprint: async () => null, maxSessions: 4 })
+ await readOpencodeChat({ sessionId: SID }, page, run, nullCache)
+ await readOpencodeChat({ sessionId: SID }, page, run, nullCache)
+ expect(run).toHaveBeenCalledTimes(2)
+
+ const flaky = vi
+ .fn<() => Promise<OpencodeExportOutcome>>()
+ .mockResolvedValueOnce({ ok: false })
+ .mockResolvedValueOnce({ ok: true, stdout: OK })
+ const cache = createOpencodeChatCache({ fingerprint: async () => 'fp', maxSessions: 4 })
+ expect((await readOpencodeChat({ sessionId: SID }, page, flaky, cache)).found).toBe(false)
+ expect((await readOpencodeChat({ sessionId: SID }, page, flaky, cache)).found).toBe(true)
+ expect(flaky).toHaveBeenCalledTimes(2)
+ })
+
+ it('is bounded: least-recently-used session evicted', async () => {
+ const ids = ['ses_a', 'ses_b', 'ses_c']
+ const run = vi.fn(async (id: string): Promise<OpencodeExportOutcome> => ({
+ ok: true,
+ stdout: JSON.stringify({ info: { id }, messages: [] })
+ }))
+ const cache = createOpencodeChatCache({ fingerprint: async () => 'fp', maxSessions: 2 })
+ await readOpencodeChat({ sessionId: ids[0] }, page, run, cache)
+ await readOpencodeChat({ sessionId: ids[1] }, page, run, cache)
+ await readOpencodeChat({ sessionId: ids[0] }, page, run, cache) // hit; a is now most recent
+ await readOpencodeChat({ sessionId: ids[2] }, page, run, cache) // evicts b
+ expect(run).toHaveBeenCalledTimes(3)
+ await readOpencodeChat({ sessionId: ids[0] }, page, run, cache)
+ expect(run).toHaveBeenCalledTimes(3)
+ await readOpencodeChat({ sessionId: ids[1] }, page, run, cache)
+ expect(run).toHaveBeenCalledTimes(4)
+ })
+
+ it('passes background to the runner so the gate can space live refreshes', async () => {
+ const run = vi.fn(async (): Promise<OpencodeExportOutcome> => ({ ok: true, stdout: OK }))
+ await readOpencodeChat({ sessionId: SID }, normalizeChatPage({ maxBytes: 262144, background: true }), run, null)
+ await readOpencodeChat({ sessionId: SID }, page, run, null)
+ expect(run.mock.calls).toEqual([
+ [SID, { background: true }],
+ [SID, { background: false }]
+ ])
+ })
+})
+
+describe('normalizeChatPage — background', () => {
+ it('only a literal true marks a read as background', () => {
+ expect(normalizeChatPage({ background: true })?.background).toBe(true)
+ expect(normalizeChatPage({ background: 'yes' })).not.toHaveProperty('background')
+ expect(normalizeChatPage({})).not.toHaveProperty('background')
+ })
+})
+
+describe('createOpencodeExportGate — background spacing', () => {
+ const flush = () => new Promise((r) => setTimeout(r, 0))
+
+ it('a background refresh waits the background spacing; an explicit read does not wait', async () => {
+ let t = 10_000
+ const sleeps: number[] = []
+ const run = vi.fn(async () => ({ ok: true as const, stdout: 'x' }))
+ const gate = createOpencodeExportGate(run, {
+ minSpacingMs: 0,
+ backgroundSpacingMs: 5000,
+ maxConcurrent: 2,
+ now: () => t,
+ sleep: async (ms) => {
+ sleeps.push(ms)
+ t += ms
+ }
+ })
+ await gate(SID)
+ t += 1000
+ await gate(SID, { background: true })
+ expect(sleeps).toEqual([4000])
+ t += 1000
+ await gate(SID)
+ expect(sleeps).toEqual([4000])
+ expect(run).toHaveBeenCalledTimes(3)
+ })
+
+ it('an explicit read joining a sleeping background refresh wakes it', async () => {
+ const run = vi.fn(async () => ({ ok: true as const, stdout: 'x' }))
+ const never = new Promise<void>(() => {})
+ const gate = createOpencodeExportGate(run, {
+ minSpacingMs: 0,
+ backgroundSpacingMs: 5000,
+ maxConcurrent: 2,
+ sleep: () => never
+ })
+ await gate(SID)
+ const bg = gate(SID, { background: true })
+ await flush()
+ expect(run).toHaveBeenCalledTimes(1)
+ const explicit = gate(SID)
+ expect(await explicit).toEqual({ ok: true, stdout: 'x' })
+ expect(await bg).toEqual({ ok: true, stdout: 'x' })
+ expect(run).toHaveBeenCalledTimes(2)
+ })
+})
+
+describe('readOpencodeChat — page size', () => {
+ const run = (stdout: string) => async (): Promise<OpencodeExportOutcome> => ({ ok: true, stdout })
+
+ it('honours a smaller page.maxBytes (the phone asks for 256 KB)', async () => {
+ const stdout = doc([1, 2, 3, 4].map((i) => msg(i, 'assistant', String(i).repeat(100 * 1024))))
+ const res = await readOpencodeChat({ sessionId: SID }, normalizeChatPage({ maxBytes: 262144 }), run(stdout), null)
+ expect(res.messages.map((m) => textOf(m)[0])).toEqual(['3', '4'])
+ })
+
+ it('a newest message bigger than the page grows the window like claude (×4 up to 5 MB)', async () => {
+ const stdout = doc([1, 2, 3].map((i) => msg(i, 'assistant', String(i).repeat(400 * 1024))))
+ const res = await readOpencodeChat({ sessionId: SID }, normalizeChatPage({ maxBytes: 262144 }), run(stdout), null)
+ // 256 KB holds none; 1 MB holds the two newest.
+ expect(res.messages.map((m) => textOf(m)[0])).toEqual(['2', '3'])
+ expect(textOf(res.messages[1])).toHaveLength(400 * 1024)
+ })
+
+ it('a newest message bigger than 5 MB is shown TRUNCATED, never as an empty conversation', async () => {
+ const stdout = doc([msg(1, 'user', 'q'), msg(2, 'assistant', 'z'.repeat(6 * 1024 * 1024))])
+ const res = await readOpencodeChat({ sessionId: SID }, normalizeChatPage({ maxBytes: 262144 }), run(stdout), null)
+ expect(res.found).toBe(true)
+ expect(res.messages).toHaveLength(1)
+ const t = textOf(res.messages[0])
+ expect(t.startsWith('zzz')).toBe(true)
+ expect(t).toMatch(/truncated/)
+ expect(Buffer.byteLength(JSON.stringify(res.messages[0]))).toBeLessThanOrEqual(5 * 1024 * 1024)
+ })
+})
diff --git a/src/core/opencode-chat.test.ts b/src/core/opencode-chat.test.ts
index 6db647d83..0aac21073 100644
--- a/src/core/opencode-chat.test.ts
+++ b/src/core/opencode-chat.test.ts
@@ -416,7 +416,7 @@ describe('readChatTranscript — opencode', () => {
model: 'm1',
effort: 'low'
})
- expect(opencodeExport).toHaveBeenCalledWith(SID)
+ expect(opencodeExport).toHaveBeenCalledWith(SID, { background: false })
})
it('an unpaged read keeps the legacy shape exactly', async () => {
@@ -486,11 +486,15 @@ describe('readChatTranscript — opencode', () => {
}
})
- it('keeps a page within the legacy 5 MB cap: the newest messages, in order', async () => {
+ it('a page too small for one message grows like claude\'s (×4); the legacy read keeps 5 MB', async () => {
const big = (i: number) => asst(`msg_${i}`, [text(String(i).repeat(1024 * 1024))])
const stdout = doc([1, 2, 3, 4, 5, 6].map(big))
- const res = await read({ sessionId: SID, agentId: 'opencode' }, { maxBytes: 262144 }, { opencodeExport: exportOf({ ok: true, stdout }) })
- expect(res.messages.map((m) => (m.parts[0] as { text: string }).text[0])).toEqual(['3', '4', '5', '6'])
+ const first = (r: { messages: ChatMessage[] }) => r.messages.map((m) => (m.parts[0] as { text: string }).text[0])
+ // 256 KB and 1 MB hold no whole ~1 MB message; 4 MB holds three.
+ const paged = await read({ sessionId: SID, agentId: 'opencode' }, { maxBytes: 262144 }, { opencodeExport: exportOf({ ok: true, stdout }) })
+ expect(first(paged)).toEqual(['4', '5', '6'])
+ const legacy = await read({ sessionId: SID, agentId: 'opencode' }, undefined, { opencodeExport: exportOf({ ok: true, stdout }) })
+ expect(first(legacy)).toEqual(['3', '4', '5', '6'])
})
it('an OLDER-page request has nothing older to give, and costs no export', async () => {
diff --git a/src/core/opencode-chat.ts b/src/core/opencode-chat.ts
index c91af8946..9698856e4 100644
--- a/src/core/opencode-chat.ts
+++ b/src/core/opencode-chat.ts
@@ -28,6 +28,9 @@
//
// Every mapping rule is written down in `src/shared/chat-fixtures/opencode/README.md` for the iOS
// port, and pinned by the golden fixtures there.
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
import type { ChatMessage, ChatPart, ChatTranscriptResult } from '../shared/types'
import { CHAT_TOOL_ARG_MAX } from '../shared/chat-command'
import { CHAT_PAGE_MAX_BYTES, type ChatTranscriptPage } from '../shared/chat-page'
@@ -222,9 +225,8 @@ export function parseOpencodeExport(raw: string, sessionId: string): OpencodeCha
return out
}
-/** The newest messages whose JSON fits in `maxBytes` (UTF-8), in order. One export is one page,
- * and a page stays within the legacy read's cap (`CHAT_PAGE_MAX_BYTES`) — it crosses the relay
- * to a phone. Like grok's capped tail, the cut is not announced (`olderCursor` stays null). */
+/** The newest messages whose JSON fits in `maxBytes` (UTF-8), in order. Like grok's capped tail,
+ * the cut is not announced (`olderCursor` stays null). */
export function newestWithinBytes(messages: ChatMessage[], maxBytes: number): ChatMessage[] {
let total = 0
let i = messages.length
@@ -237,13 +239,159 @@ export function newestWithinBytes(messages: ChatMessage[], maxBytes: number): Ch
return messages.slice(i)
}
+/** Same growth as claude's paged reader (`parseGrowingWindow`): a page that holds no whole message
+ * is re-evaluated at ×4 the size, up to the legacy 5 MB cap. */
+const PAGE_GROWTH = 4
+
+const TRUNCATED_NOTE = (droppedBytes: number) =>
+ `\n\n[… truncated: ${Math.ceil(droppedBytes / 1024)} KB more of this message is only in opencode]`
+
+/** `text` cut to at most `maxBytes` UTF-8 bytes, never splitting a surrogate pair. */
+function cutToBytes(text: string, maxBytes: number): string {
+ if (maxBytes <= 0) return ''
+ if (Buffer.byteLength(text) <= maxBytes) return text
+ let lo = 0
+ let hi = Math.min(text.length, maxBytes)
+ while (lo < hi) {
+ const mid = Math.ceil((lo + hi) / 2)
+ if (Buffer.byteLength(text.slice(0, mid)) <= maxBytes) lo = mid
+ else hi = mid - 1
+ }
+ let out = text.slice(0, lo)
+ const last = out.charCodeAt(out.length - 1)
+ if (last >= 0xd800 && last <= 0xdbff) out = out.slice(0, -1)
+ return out
+}
+
+/**
+ * One message too big for the largest page: its text parts cut (largest first) until its JSON fits
+ * `maxBytes`, each cut announced in the text itself. Better than the alternative the byte budget
+ * leaves — `messages: []` with `found: true`, which reads as an empty conversation. Tool chips are
+ * already bounded (arg 200, result 500 units), so text is the only thing that can be this big.
+ */
+export function truncateMessage(m: ChatMessage, maxBytes: number): ChatMessage {
+ const parts = m.parts.map((p) => ({ ...p }))
+ const size = () => Buffer.byteLength(JSON.stringify({ ...m, parts }))
+ // JSON escaping can make a text's serialized form larger than its UTF-8 bytes, so iterate.
+ for (let guard = 0; guard < 8 && size() > maxBytes; guard++) {
+ let idx = -1
+ for (let i = 0; i < parts.length; i++) {
+ const p = parts[i]
+ if (p.kind === 'text' && (idx < 0 || p.text.length > (parts[idx] as { text: string }).text.length)) idx = i
+ }
+ if (idx < 0) break
+ const p = parts[idx] as Extract<ChatPart, { kind: 'text' }>
+ const over = size() - maxBytes
+ const full = Buffer.byteLength(p.text)
+ const note = TRUNCATED_NOTE(full)
+ const keep = Math.max(0, full - over - Buffer.byteLength(JSON.stringify(note)) - 64 * (guard + 1))
+ const kept = cutToBytes(p.text, keep)
+ p.text = kept + TRUNCATED_NOTE(full - Buffer.byteLength(kept))
+ }
+ return { ...m, parts }
+}
+
+/**
+ * The messages a page answers with. `maxBytes` is the caller's own window (the panel's tail read,
+ * the phone's 256 KB) and is honoured; when it holds no whole message the window grows exactly as
+ * claude's does (×4, up to 5 MB); a newest message bigger even than that is shown truncated.
+ */
+export function opencodePageMessages(messages: ChatMessage[], maxBytes: number): ChatMessage[] {
+ if (!messages.length) return []
+ let bytes = Math.min(maxBytes, CHAT_PAGE_MAX_BYTES)
+ for (;;) {
+ const out = newestWithinBytes(messages, bytes)
+ if (out.length) return out
+ if (bytes >= CHAT_PAGE_MAX_BYTES) break
+ bytes = Math.min(CHAT_PAGE_MAX_BYTES, bytes * PAGE_GROWTH)
+ }
+ return [truncateMessage(messages[messages.length - 1], CHAT_PAGE_MAX_BYTES)]
+}
+
+// ── The change gate: stat opencode's database, never open it ─────────────────────────────────
+
+/** opencode's data directory, resolved the way opencode resolves it (xdg-basedir's `xdgData`:
+ * `$XDG_DATA_HOME`, else `~/.local/share` — on every platform) plus `opencode`. */
+export function opencodeDataDir(env: NodeJS.ProcessEnv = process.env, home: string = os.homedir()): string {
+ const base = env.XDG_DATA_HOME ? env.XDG_DATA_HOME : path.join(home, '.local', 'share')
+ return path.join(base, 'opencode')
+}
+
+/** `opencode.db`, a channel build's `opencode-<channel>.db`, and their WALs. */
+const OPENCODE_DB_FILE = /^opencode(-[A-Za-z0-9._-]+)?\.db(-wal)?$/
+
+/**
+ * A fingerprint of opencode's session store: size, mtime (ns), ctime and inode of every database
+ * and WAL file in `dir`, from `readdir` + `stat` — the database itself is never opened (it also
+ * holds opencode's account tokens). `null` = we cannot vouch for the store, so nothing is cached:
+ * no database file found (a relocated store we would otherwise see as "never changes"), the
+ * directory unreadable, or `OPENCODE_DB` pointing opencode somewhere else.
+ */
+export async function opencodeDbFingerprint(
+ dir: string = opencodeDataDir(),
+ env: NodeJS.ProcessEnv = process.env
+): Promise<string | null> {
+ if (env.OPENCODE_DB) return null
+ try {
+ const names = (await fs.promises.readdir(dir)).filter((n) => OPENCODE_DB_FILE.test(n)).sort()
+ if (!names.some((n) => n.endsWith('.db'))) return null
+ const rows = await Promise.all(
+ names.map(async (n) => {
+ const st = await fs.promises.stat(path.join(dir, n), { bigint: true })
+ return `${n}:${st.size}:${st.mtimeNs}:${st.ctimeNs}:${st.ino}`
+ })
+ )
+ return rows.join('|')
+ } catch {
+ return null
+ }
+}
+
+export interface OpencodeChatCache {
+ fingerprint(): Promise<string | null>
+ get(sessionId: string, fingerprint: string): OpencodeChatParse | undefined
+ set(sessionId: string, fingerprint: string, parsed: OpencodeChatParse): void
+}
+
+/** A few sessions' parsed exports, keyed by the store fingerprint taken BEFORE their export, LRU. */
+export function createOpencodeChatCache(opts: {
+ fingerprint: () => Promise<string | null>
+ maxSessions: number
+}): OpencodeChatCache {
+ const entries = new Map<string, { fingerprint: string; parsed: OpencodeChatParse }>()
+ return {
+ fingerprint: opts.fingerprint,
+ get(sessionId, fingerprint) {
+ const e = entries.get(sessionId)
+ if (!e || e.fingerprint !== fingerprint) return undefined
+ entries.delete(sessionId)
+ entries.set(sessionId, e)
+ return e.parsed
+ },
+ set(sessionId, fingerprint, parsed) {
+ entries.delete(sessionId)
+ entries.set(sessionId, { fingerprint, parsed })
+ while (entries.size > opts.maxSessions) entries.delete(entries.keys().next().value as string)
+ }
+ }
+}
+
+let defaultCache: OpencodeChatCache | undefined
+export function defaultOpencodeChatCache(): OpencodeChatCache {
+ defaultCache ??= createOpencodeChatCache({ fingerprint: () => opencodeDbFingerprint(), maxSessions: 4 })
+ return defaultCache
+}
+
// ── The export gate ─────────────────────────────────────────────────────────────────────────────
-export type OpencodeExportRun = (sessionId: string) => Promise<OpencodeExportOutcome>
+export type OpencodeExportRun = (sessionId: string, opts?: { background?: boolean }) => Promise<OpencodeExportOutcome>
export interface OpencodeExportGateOptions {
- /** Minimum time between two export STARTS for one session. */
+ /** Minimum time between two export STARTS for one session, for a read the user asked for. */
minSpacingMs: number
+ /** The same, for a BACKGROUND live refresh (hook-driven, while the agent works). Defaults to
+ * `minSpacingMs`. An explicit read joining a background refresh still sleeping wakes it. */
+ backgroundSpacingMs?: number
/** Most exports running at once, across sessions. */
maxConcurrent: number
now?: () => number
@@ -257,14 +405,23 @@ export interface OpencodeExportGateOptions {
* - joins a caller to an export that has not STARTED yet (its answer is still fresh for them);
* - gives a caller arriving while one RUNS a new export started after it — never a stale answer,
* which would leave the panel's final turn-end read one turn behind — shared by every such caller;
- * - spaces starts for one session by `minSpacingMs`, and caps exports running at once;
- * - caches nothing: a failure is answered once and the next call runs again.
+ * - spaces starts for one session by `minSpacingMs` (an explicit read) or `backgroundSpacingMs`
+ * (a live refresh), and caps exports running at once;
+ * - caches nothing itself: a failure is answered once and the next call runs again. Answering an
+ * UNCHANGED store without exporting is the change gate's job (`opencodeDbFingerprint`).
*/
export function createOpencodeExportGate(run: OpencodeExportRun, opts: OpencodeExportGateOptions): OpencodeExportRun {
const now = opts.now ?? Date.now
const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)))
+ const bgSpacing = opts.backgroundSpacingMs ?? opts.minSpacingMs
+ const longest = Math.max(opts.minSpacingMs, bgSpacing)
+ interface Waiting {
+ job: Promise<OpencodeExportOutcome>
+ background: boolean
+ wake: () => void
+ }
interface Session {
- waiting?: Promise<OpencodeExportOutcome>
+ waiting?: Waiting
running?: Promise<OpencodeExportOutcome>
lastStart: number
}
@@ -286,11 +443,11 @@ export function createOpencodeExportGate(run: OpencodeExportRun, opts: OpencodeE
const prune = (): void => {
const t = now()
for (const [id, s] of sessions) {
- if (!s.waiting && !s.running && t - s.lastStart > opts.minSpacingMs) sessions.delete(id)
+ if (!s.waiting && !s.running && t - s.lastStart > longest) sessions.delete(id)
}
}
- return (sessionId) => {
+ return (sessionId, callOpts) => {
prune()
let s = sessions.get(sessionId)
if (!s) {
@@ -298,16 +455,26 @@ export function createOpencodeExportGate(run: OpencodeExportRun, opts: OpencodeE
sessions.set(sessionId, s)
}
const st = s
- if (st.waiting) return st.waiting
+ const background = callOpts?.background === true
+ if (st.waiting) {
+ // An open or Retry the user asked for is not held behind a background refresh's spacing.
+ if (!background && st.waiting.background) {
+ st.waiting.background = false
+ st.waiting.wake()
+ }
+ return st.waiting.job
+ }
+ let wake!: () => void
+ const woken = new Promise<void>((r) => (wake = r))
+ const w = { background, wake } as Waiting
// Assigned before its body's first `await` returns, so the body can recognise itself.
- let job!: Promise<OpencodeExportOutcome>
- job = (async () => {
+ w.job = (async () => {
if (st.running) await st.running
- const wait = st.lastStart + opts.minSpacingMs - now()
- if (wait > 0) await sleep(wait)
+ const wait = st.lastStart + (w.background ? bgSpacing : opts.minSpacingMs) - now()
+ if (wait > 0) await Promise.race([sleep(wait), woken])
await acquire()
// Started: later callers get the NEXT export, not this one.
- if (st.waiting === job) st.waiting = undefined
+ if (st.waiting === w) st.waiting = undefined
st.lastStart = now()
const running = (async (): Promise<OpencodeExportOutcome> => {
try {
@@ -323,8 +490,8 @@ export function createOpencodeExportGate(run: OpencodeExportRun, opts: OpencodeE
if (st.running === running) st.running = undefined
return out
})()
- st.waiting = job
- return job
+ st.waiting = w
+ return w.job
}
}
@@ -340,7 +507,9 @@ export function defaultOpencodeExport(): OpencodeExportRun {
const bin = await findInLoginPath('opencode')
return bin ? runOpencodeExportAt(bin, sessionId, OPENCODE_CHAT_EXPORT_TIMEOUT_MS) : { ok: false }
},
- { minSpacingMs: 2000, maxConcurrent: 2 }
+ // A read the user asked for (open, ↻, Retry) is immediate; the panel's hook-driven refreshes
+ // during a turn are spaced to one export per 5 s per session.
+ { minSpacingMs: 0, backgroundSpacingMs: 5000, maxConcurrent: 2 }
)
return defaultExport
}
@@ -362,8 +531,12 @@ export function defaultOpencodeExport(): OpencodeExportRun {
export async function readOpencodeChat(
q: { sessionId?: string; remoteOnly?: boolean },
page: ChatTranscriptPage | null,
- run: OpencodeExportRun = defaultOpencodeExport()
+ run?: OpencodeExportRun,
+ cache?: OpencodeChatCache | null
): Promise<ChatTranscriptResult> {
+ // An injected runner (a test seam) gets no cache unless one is passed with it.
+ const exportRun = run ?? defaultOpencodeExport()
+ const store = cache === undefined ? (run ? null : defaultOpencodeChatCache()) : cache
const notFound = (): ChatTranscriptResult =>
page ? { messages: [], found: false, olderCursor: null, unmatchedResults: [] } : { messages: [], found: false }
const unreadable = (): ChatTranscriptResult => (page ? { ...notFound(), unreadable: true } : notFound())
@@ -371,11 +544,19 @@ export async function readOpencodeChat(
if (page && page.before !== null) return { messages: [], found: true, olderCursor: null, unmatchedResults: [] }
const sessionId = q.sessionId
if (!sessionId || !isSafeOpencodeSessionId(sessionId)) return notFound()
- const out = await run(sessionId)
- if (!out.ok) return out.absent ? notFound() : unreadable()
- const parsed = parseOpencodeExport(out.stdout, sessionId)
- if (!parsed) return unreadable()
- const messages = newestWithinBytes(parsed.messages, CHAT_PAGE_MAX_BYTES)
+ // Taken BEFORE the export: a write that lands while it runs changes the next fingerprint, so the
+ // next read exports again rather than serving this (possibly older) answer.
+ const fingerprint = store ? await store.fingerprint() : null
+ let parsed = fingerprint !== null && store ? store.get(sessionId, fingerprint) : undefined
+ if (!parsed) {
+ const out = await exportRun(sessionId, { background: page?.background === true })
+ if (!out.ok) return out.absent ? notFound() : unreadable()
+ const fresh = parseOpencodeExport(out.stdout, sessionId)
+ if (!fresh) return unreadable()
+ parsed = fresh
+ if (fingerprint !== null && store) store.set(sessionId, fingerprint, fresh)
+ }
+ const messages = opencodePageMessages(parsed.messages, page ? page.maxBytes : CHAT_PAGE_MAX_BYTES)
if (!page) return { messages, found: true }
return {
messages,
diff --git a/src/core/opencode-export.test.ts b/src/core/opencode-export.test.ts
index 2c13f7b5f..a6bede7d8 100644
--- a/src/core/opencode-export.test.ts
+++ b/src/core/opencode-export.test.ts
@@ -84,6 +84,14 @@ describe('runOpencodeExportAt — the tri-state', () => {
expect(Date.now() - t0).toBeLessThan(10_000)
})
+ it('runs outside the app cwd (os.tmpdir), so opencode never bootstraps inside a repo', async () => {
+ // Run from inside a repo, an export writes `<repo>/.git/opencode`. Sessions resolve by their
+ // global id, so the cwd carries no meaning for the read.
+ const bin = writeFakeOpencode(dir, 'process.stdout.write(process.cwd())\n')
+ const out = await runOpencodeExportAt(bin, SID, 10_000)
+ expect(out.ok && fs.realpathSync(out.stdout)).toBe(fs.realpathSync(os.tmpdir()))
+ })
+
it('a binary that does not exist is a failure', async () => {
expect(await runOpencodeExportAt(path.join(dir, 'nope'), SID, 10_000)).toEqual({ ok: false })
})
diff --git a/src/core/opencode-export.ts b/src/core/opencode-export.ts
index e29a42fbf..86a768f92 100644
--- a/src/core/opencode-export.ts
+++ b/src/core/opencode-export.ts
@@ -11,6 +11,7 @@
// option exits 1 (yargs strict), so no flag is passed that an older CLI might not know. One export
// costs 1.0–1.7 s wall and ~320 MB peak RSS on this host, which is why the chat view gates it
// (`createOpencodeExportGate`).
+import os from 'os'
import { directExecutableInvocation } from './exec-path'
/** An export names ONE provider session. The id reaches us from a hook payload, so it is re-checked
@@ -53,6 +54,10 @@ export async function runOpencodeExportAt(
invocation.args,
{
...invocation.options,
+ // Never the app's cwd: opencode bootstraps a project for its cwd and, inside a git repo,
+ // writes `<repo>/.git/opencode`. An export resolves the session by its GLOBAL id, so a
+ // neutral directory changes nothing about what is read.
+ cwd: os.tmpdir(),
encoding: 'utf-8',
maxBuffer: OPENCODE_EXPORT_MAX_BYTES,
timeout: timeoutMs
diff --git a/src/renderer/nodes/ChatPanel.live.test.tsx b/src/renderer/nodes/ChatPanel.live.test.tsx
index 3711a1108..33d68064e 100644
--- a/src/renderer/nodes/ChatPanel.live.test.tsx
+++ b/src/renderer/nodes/ChatPanel.live.test.tsx
@@ -147,7 +147,7 @@ describe('ChatPanel live progress', () => {
expect(pending).toHaveLength(1)
await advance(CHAT_LIVE_RELOAD_MIN_MS)
expect(pending).toHaveLength(2)
- expect(pending[1].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES })
+ expect(pending[1].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES, background: true })
// A burst while that read is in flight: held, never overlapped…
await hook('working')
@@ -185,7 +185,7 @@ describe('ChatPanel live progress', () => {
await settle(1, { messages: [say(0, 'older')], olderCursor: null })
expect(bubbles()).toEqual(['older', 'tail'])
expect(pending).toHaveLength(3) // …then served once it landed
- expect(pending[2].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES })
+ expect(pending[2].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES, background: true })
})
it('the live read the send itself triggers does not erase the prompt the transcript lacks yet', async () => {
@@ -232,7 +232,7 @@ describe('ChatPanel live progress', () => {
await hook('working')
await advance(CHAT_LIVE_RELOAD_MIN_MS)
expect(pending).toHaveLength(3)
- expect(pending[2].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES })
+ expect(pending[2].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES, background: true })
expect(host.querySelector('.term-chat__older--error')).not.toBeNull()
await settle(2, { messages: [say(1000, 'tail'), say(2000, 'more')], olderCursor: 1000 })
expect(host.querySelector('.term-chat__older--error')).not.toBeNull()
@@ -365,7 +365,7 @@ describe('ChatPanel — a sent local command', () => {
expect(pending.length).toBe(1)
await advance(1)
expect(pending.length).toBe(2)
- expect(pending[1].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES })
+ expect(pending[1].page).toEqual({ maxBytes: CHAT_TAIL_PAGE_BYTES, background: true })
await settle(1, { messages: [say(0, 'hello'), cmd(100, '/model')], olderCursor: 0 })
expect(activity()).toBeNull()
// Exactly one read: nothing else is scheduled.
diff --git a/src/renderer/nodes/ChatPanel.tsx b/src/renderer/nodes/ChatPanel.tsx
index 579b572b3..2f5e243a8 100644
--- a/src/renderer/nodes/ChatPanel.tsx
+++ b/src/renderer/nodes/ChatPanel.tsx
@@ -330,7 +330,10 @@ export function ChatPanel({
// presenting itself as an empty conversation. Only the newest TAIL window is read — older
// history pages in on scroll-up, and a reload merges by key instead of discarding it.
void api.chat.readTranscript(sessionId, cwd, accountId, nodeId, agentId, {
- maxBytes: CHAT_TAIL_PAGE_BYTES
+ maxBytes: CHAT_TAIL_PAGE_BYTES,
+ // A hook-driven refresh the user did not ask for: an expensive reader (opencode's export) may
+ // space these out. An open, ↻, Retry or a held-request rebind is never marked.
+ ...(live && !rebind ? { background: true } : {})
}).then(
(res) => {
if (token !== reqRef.current) return
diff --git a/src/shared/chat-fixtures/opencode/README.md b/src/shared/chat-fixtures/opencode/README.md
index f9203aa97..128a70b4f 100644
--- a/src/shared/chat-fixtures/opencode/README.md
+++ b/src/shared/chat-fixtures/opencode/README.md
@@ -28,7 +28,11 @@ strict and exits 1 on an option an older build does not know). Measured on 1.18.
coloured) — the only answer read as a clean miss (`found: false`); every other failure is a
failed read (`unreadable: true`);
- one export costs 1.0–1.7 s and ~320 MB peak RSS, so the desktop runs at most one per session at a
- time (starts spaced 2 s apart) and two in total.
+ time and two in total; the panel's background refreshes are spaced 5 s, and an unchanged
+ database (stat of `opencode*.db` + `-wal`, never opened) is answered from a small cache.
+- a page honours the request's `maxBytes`, grows ×4 up to 5 MB when it holds no whole message (as
+ claude's reader does), and a newest message above 5 MB is served truncated with a note, never as
+ an empty page. The phone should expect that note in the text, not a separate field.
The reader never runs an export without a session id (a bare `opencode export` opens a picker over
the newest sessions), never for an id outside `^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$`, and never for a
diff --git a/src/shared/chat-page.ts b/src/shared/chat-page.ts
index 73b82563f..e4185ceac 100644
--- a/src/shared/chat-page.ts
+++ b/src/shared/chat-page.ts
@@ -18,12 +18,18 @@ export const CHAT_PAGE_DEFAULT_BYTES = 256 * 1024
export interface ChatTranscriptPageRequest {
before?: number
maxBytes?: number
+ /** A live refresh the panel issued on its own (a hook event), not an open or a Retry the user
+ * asked for. Readers whose read is expensive (opencode's `export`) may space these out; a
+ * reader that ignores it answers exactly as before. */
+ background?: boolean
}
/** A validated page: `before: null` = end of file. */
export interface ChatTranscriptPage {
before: number | null
maxBytes: number
+ /** Present (and `true`) only for a background live refresh — see the request field. */
+ background?: true
}
/**
@@ -51,5 +57,6 @@ export function normalizeChatPage(page: unknown): ChatTranscriptPage | null {
if (typeof maxBytes === 'number' && Number.isFinite(maxBytes)) {
m = Math.min(CHAT_PAGE_MAX_BYTES, Math.max(CHAT_PAGE_MIN_BYTES, Math.floor(maxBytes)))
}
- return { before: b, maxBytes: m }
+ const { background } = page as { background?: unknown }
+ return background === true ? { before: b, maxBytes: m, background: true } : { before: b, maxBytes: m }
}