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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import fs from 'fs'
import os from 'os'
import path from 'path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import {
PLUGIN_MARKER,
buildOpencodePlugin,
buildOpencodeV2Plugin,
installOpencodeHooks,
opencodeConfigDir,
pluginPath,
removeOpencodeHooks,
v2PluginPath
} from './opencode'
import { normalizeOpencode } from '../../../shared/agents/normalize'
// Both generated plugins share one process-wide latch (which plugin API armed first). Every test
// loads fresh module copies into the SAME process, so the latch is reset before each one.
const LATCH = Symbol.for('nodeterm.opencode.status.api')
const g = globalThis as unknown as Record<symbol, unknown>
let tmp: string
beforeEach(() => {
delete g[LATCH]
tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-oc-'))
vi.spyOn(os, 'homedir').mockReturnValue(tmp)
// CI runners export XDG_CONFIG_HOME (GitHub Actions: /home/runner/.config), which wins
// over the mocked homedir in opencodeConfigDir() — the installer then writes outside the
// temp dir and every read here misses. Clear it so the homedir fallback is what's tested;
// the XDG describe block below stubs its own value on top.
vi.stubEnv('XDG_CONFIG_HOME', '')
})
afterEach(() => {
vi.unstubAllEnvs()
vi.restoreAllMocks()
fs.rmSync(tmp, { recursive: true, force: true })
})
const planted = () => path.join(tmp, '.config', 'opencode', 'plugins', 'nodeterm-status.js')
describe('opencode plugin install', () => {
it('writes the marker-bearing plugin file (idempotent)', () => {
installOpencodeHooks()
installOpencodeHooks()
const body = fs.readFileSync(planted(), 'utf8')
expect(body.startsWith(PLUGIN_MARKER)).toBe(true)
expect(body).toContain('NODETERM_NODE_ID')
expect(body).toContain('/hook/opencode')
})
it('never overwrites a user file without the marker', () => {
fs.mkdirSync(path.dirname(planted()), { recursive: true })
fs.writeFileSync(planted(), '// my own plugin\n')
installOpencodeHooks()
expect(fs.readFileSync(planted(), 'utf8')).toBe('// my own plugin\n')
})
it('remove deletes only a marker-bearing file', () => {
installOpencodeHooks()
removeOpencodeHooks()
expect(fs.existsSync(planted())).toBe(false)
fs.mkdirSync(path.dirname(planted()), { recursive: true })
fs.writeFileSync(planted(), '// my own plugin\n')
removeOpencodeHooks()
expect(fs.existsSync(planted())).toBe(true)
})
it('generated plugin is env-gated and fail-open', () => {
const body = buildOpencodePlugin()
expect(body).toContain('return {}') // missing env → no-op
expect(body).toContain('catch') // POSTs never throw into opencode
})
})
// Execute the generated plugin body against SDK-shaped inputs. opencode delivers bus
// events (session.created/idle/error, message.updated, permission.*) ONLY through the
// `event` catch-all hook — a hook keyed by the event name itself is never called (the
// original bug: every handler was dead, so no status ever reached the hook server).
describe('generated plugin behavior (executed)', () => {
let posts: Array<{ url: string; payload: Record<string, unknown>; nodeId: string }>
async function loadHooks(): Promise<Record<string, (input: unknown) => Promise<void>>> {
posts = []
vi.stubGlobal('fetch', (url: string, init: { body: string }) => {
const params = new URLSearchParams(init.body)
posts.push({
url,
nodeId: params.get('nodeId') ?? '',
payload: JSON.parse(params.get('payload') ?? '{}')
})
return Promise.resolve(new Response())
})
vi.stubEnv('NODETERM_NODE_ID', 'node-1')
vi.stubEnv('NODETERM_HOOK_PORT', '43210')
vi.stubEnv('NODETERM_HOOK_TOKEN', 'tok')
vi.stubEnv('NODETERM_HOOK_ENDPOINT', '')
// A developer may be running this test from a live nodeterm PTY. Never let the
// generated plugin inherit that session's socket and post test events to it.
vi.stubEnv('NODETERM_HOOK_SOCK', '')
const file = path.join(tmp, `plugin-under-test-${Math.random().toString(36).slice(2)}.mjs`)
fs.writeFileSync(file, buildOpencodePlugin())
const mod = await import(/* @vite-ignore */ `file://${file}`)
return mod.NodetermStatus()
}
afterEach(() => {
vi.unstubAllEnvs()
vi.unstubAllGlobals()
})
it('forwards bus events through the `event` catch-all with the wire-contract names', async () => {
const hooks = await loadHooks()
expect(typeof hooks.event).toBe('function')
await hooks.event({ event: { type: 'session.created', properties: { info: { id: 'ses_1' } } } })
await hooks.event({ event: { type: 'session.idle', properties: { sessionID: 'ses_1' } } })
await hooks.event({ event: { type: 'session.error', properties: { sessionID: 'ses_1' } } })
await hooks.event({ event: { type: 'permission.updated', properties: { id: 'perm1', sessionID: 'ses_1' } } })
await hooks.event({
event: { type: 'permission.replied', properties: { sessionID: 'ses_1', permissionID: 'perm1', response: 'once' } }
})
// The question (elicitation) flow, measured on 1.18.3: the TUI dialog blocks the turn
// but the session never goes idle, so without these the badge sat on RUNNING.
await hooks.event({
event: { type: 'question.asked', properties: { id: 'que_1', sessionID: 'ses_1', questions: [] } }
})
await hooks.event({
event: { type: 'question.replied', properties: { sessionID: 'ses_1', requestID: 'que_1', answers: [['Red']] } }
})
await hooks.event({
event: { type: 'question.rejected', properties: { sessionID: 'ses_1', requestID: 'que_1' } }
})
expect(posts.map((p) => p.payload)).toEqual([
{ event: 'session.created', sessionID: 'ses_1' },
{ event: 'session.idle', sessionID: 'ses_1' },
{ event: 'session.error', sessionID: 'ses_1' },
{ event: 'permission.asked', sessionID: 'ses_1' },
{ event: 'permission.replied', sessionID: 'ses_1' },
{ event: 'question.asked', sessionID: 'ses_1' },
{ event: 'question.replied', sessionID: 'ses_1' },
{ event: 'question.rejected', sessionID: 'ses_1' }
])
expect(posts[0].url).toBe('http://127.0.0.1:43210/hook/opencode')
expect(posts[0].nodeId).toBe('node-1')
})
it('forwards message.updated only for user messages (turn start)', async () => {
const hooks = await loadHooks()
await hooks.event({
event: { type: 'message.updated', properties: { info: { id: 'm1', sessionID: 'ses_1', role: 'user' } } }
})
await hooks.event({
event: { type: 'message.updated', properties: { info: { id: 'm2', sessionID: 'ses_1', role: 'assistant' } } }
})
expect(posts.map((p) => p.payload)).toEqual([{ event: 'message.updated', sessionID: 'ses_1', role: 'user' }])
})
it('posts a user message.updated ONCE per messageID — later updates of the same message are not new turns', async () => {
// Measured on opencode 1.18.3 (TUI): the user message record is updated again both at
// turn start (created → completed) and AFTER session.idle (title/bookkeeping touch).
// Each re-forward became working+newTurn, which bypasses the done-holdoff by design —
// so the node bounced back to RUNNING right after done and stuck there forever.
const hooks = await loadHooks()
const user = (id: string) => ({
event: { type: 'message.updated', properties: { info: { id, sessionID: 'ses_1', role: 'user' } } }
})
await hooks.event(user('m1'))
await hooks.event(user('m1')) // turn-start double fire
await hooks.event({ event: { type: 'session.idle', properties: { sessionID: 'ses_1' } } })
await hooks.event(user('m1')) // post-idle bookkeeping touch — must NOT resurrect the turn
await hooks.event(user('m2')) // a genuinely new prompt still counts
expect(posts.map((p) => p.payload)).toEqual([
{ event: 'message.updated', sessionID: 'ses_1', role: 'user' },
{ event: 'session.idle', sessionID: 'ses_1' },
{ event: 'message.updated', sessionID: 'ses_1', role: 'user' }
])
})
it('ignores unrelated bus events (token-stream deltas never reach the hook server)', async () => {
const hooks = await loadHooks()
await hooks.event({ event: { type: 'message.part.delta', properties: {} } })
await hooks.event({ event: { type: 'session.updated', properties: { info: { id: 'ses_1' } } } })
expect(posts).toEqual([])
})
it('posts tool.execute.before from the real plugin hook of that name', async () => {
const hooks = await loadHooks()
await hooks['tool.execute.before']({ tool: 'bash', sessionID: 'ses_1', callID: 'c1' })
expect(posts.map((p) => p.payload)).toEqual([{ event: 'tool.execute.before', sessionID: 'ses_1' }])
})
})
// SSH hosts advertise a UNIX SOCKET (NODETERM_HOOK_SOCK), not a TCP port — the endpoint
// file on a remote host has no PORT line at all. The POSIX managed script posts with
// `curl --unix-socket`; the plugin must speak the socket too or every opencode status
// on an SSH project silently vanishes (fetch can't do unix sockets in Node — node:http
// socketPath is the fallback; under Bun (opencode's runtime) fetch takes `unix`).
describe('generated plugin unix-socket transport', () => {
let sockDir: string
beforeEach(() => {
sockDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-oc-sock-'))
})
afterEach(() => {
vi.unstubAllEnvs()
vi.unstubAllGlobals()
fs.rmSync(sockDir, { recursive: true, force: true })
})
async function importPlugin(): Promise<Record<string, (input: unknown) => Promise<void>>> {
const file = path.join(tmp, `plugin-sock-${Math.random().toString(36).slice(2)}.mjs`)
fs.writeFileSync(file, buildOpencodePlugin())
const mod = await import(/* @vite-ignore */ `file://${file}`)
return mod.NodetermStatus()
}
it('posts over the unix socket via node:http when NODETERM_HOOK_SOCK is set (no port)', async () => {
const { createServer } = await import('node:http')
const sock = path.join(sockDir, 'hook.sock')
const received: Array<{ url: string; token: string; body: string }> = []
const server = createServer((req, res) => {
let body = ''
req.on('data', (c: Buffer) => (body += c))
req.on('end', () => {
received.push({ url: req.url ?? '', token: String(req.headers['x-nodeterm-hook-token']), body })
res.end('ok')
})
})
await new Promise<void>((r) => server.listen(sock, r))
try {
vi.stubEnv('NODETERM_NODE_ID', 'node-ssh')
vi.stubEnv('NODETERM_HOOK_SOCK', sock)
vi.stubEnv('NODETERM_HOOK_TOKEN', 'socktok')
vi.stubEnv('NODETERM_HOOK_PORT', '')
vi.stubEnv('NODETERM_HOOK_ENDPOINT', '')
const hooks = await importPlugin()
await hooks.event({ event: { type: 'session.idle', properties: { sessionID: 'ses_ssh' } } })
await vi.waitFor(() => expect(received.length).toBe(1))
expect(received[0].url).toBe('/hook/opencode')
expect(received[0].token).toBe('socktok')
const params = new URLSearchParams(received[0].body)
expect(params.get('nodeId')).toBe('node-ssh')
expect(JSON.parse(params.get('payload') ?? '{}')).toEqual({ event: 'session.idle', sessionID: 'ses_ssh' })
} finally {
server.close()
}
})
it('reads NODETERM_HOOK_SOCK from the live endpoint file (restart handoff) and prefers it over a TCP port', async () => {
const { createServer } = await import('node:http')
const sock = path.join(sockDir, 'hook2.sock')
const received: string[] = []
const server = createServer((req, res) => {
req.resume()
req.on('end', () => {
received.push(req.url ?? '')
res.end('ok')
})
})
await new Promise<void>((r) => server.listen(sock, r))
const tcpFetch = vi.fn(() => Promise.resolve(new Response()))
vi.stubGlobal('fetch', tcpFetch)
try {
const envFile = path.join(sockDir, 'hook-endpoint.env')
fs.writeFileSync(envFile, `NODETERM_HOOK_SOCK=${sock}\nNODETERM_HOOK_TOKEN=filetok\nNODETERM_HOOK_VERSION=1\n`)
vi.stubEnv('NODETERM_NODE_ID', 'node-ssh')
vi.stubEnv('NODETERM_HOOK_ENDPOINT', envFile)
vi.stubEnv('NODETERM_HOOK_PORT', '59999') // stale env port — socket from the file must win
vi.stubEnv('NODETERM_HOOK_TOKEN', 'stale')
vi.stubEnv('NODETERM_HOOK_SOCK', '')
const hooks = await importPlugin()
await hooks.event({ event: { type: 'session.idle', properties: { sessionID: 'ses_ssh' } } })
await vi.waitFor(() => expect(received.length).toBe(1))
expect(tcpFetch).not.toHaveBeenCalled()
} finally {
server.close()
}
})
it('uses Bun fetch with the `unix` option when running under Bun', async () => {
const calls: Array<{ url: string; init: Record<string, unknown> }> = []
vi.stubGlobal('Bun', {})
vi.stubGlobal('fetch', (url: string, init: Record<string, unknown>) => {
calls.push({ url, init })
return Promise.resolve(new Response())
})
vi.stubEnv('NODETERM_NODE_ID', 'node-ssh')
vi.stubEnv('NODETERM_HOOK_SOCK', '/tmp/some.sock')
vi.stubEnv('NODETERM_HOOK_TOKEN', 'tok')
vi.stubEnv('NODETERM_HOOK_PORT', '')
vi.stubEnv('NODETERM_HOOK_ENDPOINT', '')
const hooks = await importPlugin()
await hooks.event({ event: { type: 'session.idle', properties: { sessionID: 'ses_ssh' } } })
expect(calls.length).toBe(1)
expect(calls[0].url).toBe('http://localhost/hook/opencode')
expect(calls[0].init.unix).toBe('/tmp/some.sock')
})
})
// The per-node token (task A10). The plugin is the one client that is not sh: it must learn the
// token dir from the SAME endpoint file (a new KEY=VALUE line the file's regex has to accept),
// read `<dir>/<nodeId>`, and put the header on BOTH transports — the Bun `fetch` (TCP and unix)
// and the node:http socketPath fallback.
describe('generated plugin presents the per-node token', () => {
let tokenDir: string
let sockDir: string
beforeEach(() => {
tokenDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-oc-tok-'))
sockDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-oc-tsock-'))
fs.writeFileSync(path.join(tokenDir, 'node-1'), 'OPENCODE-NODE-TOKEN\n', { mode: 0o600 })
})
afterEach(() => {
vi.unstubAllEnvs()
vi.unstubAllGlobals()
fs.rmSync(tokenDir, { recursive: true, force: true })
fs.rmSync(sockDir, { recursive: true, force: true })
})
async function importPlugin(): Promise<Record<string, (input: unknown) => Promise<void>>> {
const file = path.join(tmp, `plugin-token-${Math.random().toString(36).slice(2)}.mjs`)
fs.writeFileSync(file, buildOpencodePlugin())
const mod = await import(/* @vite-ignore */ `file://${file}`)
return mod.NodetermStatus()
}
/** Fires one event over the plain TCP `fetch` path and returns the headers it sent. */
async function tcpHeaders(env: Record<string, string>): Promise<Record<string, string>> {
const calls: Array<Record<string, string>> = []
vi.stubGlobal('fetch', (_url: string, init: { headers: Record<string, string> }) => {
calls.push(init.headers)
return Promise.resolve(new Response())
})
vi.stubEnv('NODETERM_NODE_ID', 'node-1')
vi.stubEnv('NODETERM_HOOK_PORT', '43210')
vi.stubEnv('NODETERM_HOOK_TOKEN', 'tok')
vi.stubEnv('NODETERM_HOOK_ENDPOINT', '')
vi.stubEnv('NODETERM_HOOK_SOCK', '')
for (const [k, v] of Object.entries(env)) vi.stubEnv(k, v)
const hooks = await importPlugin()
await hooks.event({ event: { type: 'session.idle', properties: { sessionID: 'ses_1' } } })
expect(calls.length).toBe(1)
return calls[0]
}
it('sends the token on the fetch path when the file exists', async () => {
const headers = await tcpHeaders({ NODETERM_NODE_TOKEN_DIR: tokenDir })
expect(headers['x-nodeterm-node-token']).toBe('OPENCODE-NODE-TOKEN')
})
it('sends an EMPTY token — and still posts — when there is no token file', async () => {
const headers = await tcpHeaders({ NODETERM_NODE_TOKEN_DIR: path.join(tokenDir, 'nope') })
expect(headers['x-nodeterm-node-token']).toBe('')
})
it('sends an empty token when no dir is advertised at all (pre-v2 endpoint)', async () => {
const headers = await tcpHeaders({})
expect(headers['x-nodeterm-node-token']).toBe('')
})
it('never presents ANOTHER node\'s token file — the path is keyed by the node id', async () => {
const headers = await tcpHeaders({ NODETERM_NODE_TOKEN_DIR: tokenDir, NODETERM_NODE_ID: 'node-9' })
expect(headers['x-nodeterm-node-token']).toBe('')
})
it('learns the dir from the ENDPOINT FILE (the v2 line), not only the env', async () => {
const envFile = path.join(sockDir, 'hook-endpoint.env')
fs.writeFileSync(
envFile,
`NODETERM_HOOK_PORT=43210\nNODETERM_HOOK_TOKEN=filetok\nNODETERM_HOOK_VERSION=2\nNODETERM_NODE_TOKEN_DIR=${tokenDir}\n`
)
const headers = await tcpHeaders({ NODETERM_HOOK_ENDPOINT: envFile, NODETERM_HOOK_PORT: '' })
expect(headers['x-nodeterm-node-token']).toBe('OPENCODE-NODE-TOKEN')
expect(headers['x-nodeterm-hook-token']).toBe('filetok')
})
it('sends it on the Bun unix-fetch path too', async () => {
const calls: Array<{ init: Record<string, unknown> }> = []
vi.stubGlobal('Bun', {})
vi.stubGlobal('fetch', (_url: string, init: Record<string, unknown>) => {
calls.push({ init })
return Promise.resolve(new Response())
})
vi.stubEnv('NODETERM_NODE_ID', 'node-1')
vi.stubEnv('NODETERM_HOOK_SOCK', '/tmp/some.sock')
vi.stubEnv('NODETERM_HOOK_TOKEN', 'tok')
vi.stubEnv('NODETERM_HOOK_PORT', '')
vi.stubEnv('NODETERM_HOOK_ENDPOINT', '')
vi.stubEnv('NODETERM_NODE_TOKEN_DIR', tokenDir)
const hooks = await importPlugin()
await hooks.event({ event: { type: 'session.idle', properties: { sessionID: 'ses_1' } } })
expect(calls.length).toBe(1)
expect((calls[0].init.headers as Record<string, string>)['x-nodeterm-node-token']).toBe(
'OPENCODE-NODE-TOKEN'
)
})
it('sends it on the node:http socketPath path too (real unix server)', async () => {
const { createServer } = await import('node:http')
const sock = path.join(sockDir, 'hook.sock')
const received: Array<string> = []
const server = createServer((req, res) => {
req.resume()
req.on('end', () => {
received.push(String(req.headers['x-nodeterm-node-token'] ?? ''))
res.end('ok')
})
})
await new Promise<void>((r) => server.listen(sock, r))
try {
vi.stubEnv('NODETERM_NODE_ID', 'node-1')
vi.stubEnv('NODETERM_HOOK_SOCK', sock)
vi.stubEnv('NODETERM_HOOK_TOKEN', 'socktok')
vi.stubEnv('NODETERM_HOOK_PORT', '')
vi.stubEnv('NODETERM_HOOK_ENDPOINT', '')
vi.stubEnv('NODETERM_NODE_TOKEN_DIR', tokenDir)
const hooks = await importPlugin()
await hooks.event({ event: { type: 'session.idle', properties: { sessionID: 'ses_1' } } })
await vi.waitFor(() => expect(received.length).toBe(1))
expect(received[0]).toBe('OPENCODE-NODE-TOKEN')
} finally {
server.close()
}
})
it('posts over node:http with an EMPTY token when the file is missing', async () => {
const { createServer } = await import('node:http')
const sock = path.join(sockDir, 'hook-empty.sock')
const received: Array<string> = []
const server = createServer((req, res) => {
req.resume()
req.on('end', () => {
received.push(String(req.headers['x-nodeterm-node-token'] ?? ''))
res.end('ok')
})
})
await new Promise<void>((r) => server.listen(sock, r))
try {
vi.stubEnv('NODETERM_NODE_ID', 'node-1')
vi.stubEnv('NODETERM_HOOK_SOCK', sock)
vi.stubEnv('NODETERM_HOOK_TOKEN', 'socktok')
vi.stubEnv('NODETERM_HOOK_PORT', '')
vi.stubEnv('NODETERM_HOOK_ENDPOINT', '')
vi.stubEnv('NODETERM_NODE_TOKEN_DIR', path.join(tokenDir, 'nope'))
const hooks = await importPlugin()
await hooks.event({ event: { type: 'session.idle', properties: { sessionID: 'ses_1' } } })
await vi.waitFor(() => expect(received.length).toBe(1))
expect(received[0]).toBe('')
} finally {
server.close()
}
})
})
describe('opencodeConfigDir honors XDG_CONFIG_HOME', () => {
it('lands the plugin under $XDG_CONFIG_HOME/opencode when the (absolute) env var is set', () => {
const xdg = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-xdg-'))
vi.stubEnv('XDG_CONFIG_HOME', xdg)
try {
expect(opencodeConfigDir()).toBe(path.join(xdg, 'opencode'))
expect(pluginPath()).toBe(path.join(xdg, 'opencode', 'plugins', 'nodeterm-status.js'))
installOpencodeHooks()
const body = fs.readFileSync(path.join(xdg, 'opencode', 'plugins', 'nodeterm-status.js'), 'utf8')
expect(body.startsWith(PLUGIN_MARKER)).toBe(true)
// and NOT under ~/.config
expect(fs.existsSync(path.join(tmp, '.config', 'opencode', 'plugins', 'nodeterm-status.js'))).toBe(false)
} finally {
vi.unstubAllEnvs()
fs.rmSync(xdg, { recursive: true, force: true })
}
})
it('falls back to ~/.config/opencode when XDG_CONFIG_HOME is unset', () => {
vi.stubEnv('XDG_CONFIG_HOME', '')
try {
expect(opencodeConfigDir()).toBe(path.join(tmp, '.config', 'opencode'))
expect(pluginPath()).toBe(path.join(tmp, '.config', 'opencode', 'plugins', 'nodeterm-status.js'))
} finally {
vi.unstubAllEnvs()
}
})
})
// Issue #1136. OpenCode 2.x needs a default export object `{ id, setup }`; OpenCode <= 1.2.10
// calls every export as a function and dies on an object (bisected on real builds). So there are
// TWO plugins: the 1.x file (named export only) and a 2.x DIRECTORY no 1.x glob matches.
const planted2 = () => path.join(tmp, '.config', 'opencode', 'plugins', 'nodeterm-status-v2', 'index.js')
describe('opencode plugin install — the 2.x directory plugin', () => {
it('plants both plugins, each marker-bearing, at the paths each opencode generation loads', () => {
installOpencodeHooks()
expect(v2PluginPath()).toBe(planted2())
expect(fs.readFileSync(planted(), 'utf8')).toBe(buildOpencodePlugin())
expect(fs.readFileSync(planted2(), 'utf8')).toBe(buildOpencodeV2Plugin())
expect(fs.readFileSync(planted2(), 'utf8').startsWith(PLUGIN_MARKER)).toBe(true)
})
it('refreshes a stale managed copy (an older build\'s body) but never a user file', () => {
fs.mkdirSync(path.dirname(planted2()), { recursive: true })
fs.writeFileSync(planted2(), PLUGIN_MARKER + '\n// old body\n')
installOpencodeHooks()
expect(fs.readFileSync(planted2(), 'utf8')).toBe(buildOpencodeV2Plugin())
fs.writeFileSync(planted2(), '// my own v2 plugin\n')
installOpencodeHooks()
expect(fs.readFileSync(planted2(), 'utf8')).toBe('// my own v2 plugin\n')
})
it('does not rewrite an up-to-date file (opencode 2.x watches plugin files and reloads on change)', () => {
installOpencodeHooks()
const past = Math.floor(Date.now() / 1000) - 60 // whole seconds: mtimeMs is a float
fs.utimesSync(planted2(), past, past)
installOpencodeHooks()
expect(Math.round(fs.statSync(planted2()).mtimeMs / 1000)).toBe(past)
})
it('remove deletes both managed plugins and the now-empty directory, but keeps anything else', () => {
installOpencodeHooks()
removeOpencodeHooks()
expect(fs.existsSync(planted())).toBe(false)
expect(fs.existsSync(path.dirname(planted2()))).toBe(false)
installOpencodeHooks()
fs.writeFileSync(path.join(path.dirname(planted2()), 'notes.txt'), 'mine')
removeOpencodeHooks()
expect(fs.existsSync(planted2())).toBe(false)
expect(fs.readFileSync(path.join(path.dirname(planted2()), 'notes.txt'), 'utf8')).toBe('mine')
})
})
describe('generated plugins, module shapes (executed)', () => {
let posts: Array<Record<string, unknown>>
beforeEach(() => {
posts = []
vi.stubGlobal('fetch', (_url: string, init: { body: string }) => {
posts.push(JSON.parse(new URLSearchParams(init.body).get('payload') ?? '{}'))
return Promise.resolve(new Response())
})
vi.stubEnv('NODETERM_NODE_ID', 'node-1')
vi.stubEnv('NODETERM_HOOK_PORT', '43210')
vi.stubEnv('NODETERM_HOOK_TOKEN', 'tok')
vi.stubEnv('NODETERM_HOOK_ENDPOINT', '')
vi.stubEnv('NODETERM_HOOK_SOCK', '')
})
afterEach(() => {
vi.unstubAllEnvs()
vi.unstubAllGlobals()
})
type V1Hooks = Record<string, (input: unknown) => Promise<void>>
type V2Def = { id: string; setup: (ctx: unknown) => Promise<(() => void) | void> }
async function load(body: string): Promise<Record<string, unknown>> {
const file = path.join(tmp, `plugin-${Math.random().toString(36).slice(2)}.mjs`)
fs.writeFileSync(file, body)
return import(/* @vite-ignore */ `file://${file}`)
}
const loadV1 = async (): Promise<{ NodetermStatus: () => Promise<V1Hooks> }> =>
(await load(buildOpencodePlugin())) as unknown as { NodetermStatus: () => Promise<V1Hooks> }
const loadV2 = async (): Promise<V2Def> => (await load(buildOpencodeV2Plugin())).default as V2Def
/** A 2.x context: an event stream we push into, and a tool-hook registry. */
function v2Context(): {
ctx: unknown
push: (type: string, data: Record<string, unknown>) => void
end: () => void
toolHooks: Array<{ name: string; cb: (input: unknown) => unknown }>
subscribed: () => number
signal: () => AbortSignal | undefined
} {
const queue: unknown[] = []
let wake: (() => void) | null = null
let done = false
let subs = 0
let sig: AbortSignal | undefined
const toolHooks: Array<{ name: string; cb: (input: unknown) => unknown }> = []
const ctx = {
event: {
subscribe: (options?: { signal?: AbortSignal }) => {
subs++
sig = options?.signal
return {
async *[Symbol.asyncIterator]() {
for (;;) {
if (queue.length) {
yield queue.shift()
continue
}
if (done || sig?.aborted) return
await new Promise<void>((r) => (wake = r))
}
}
}
}
},
tool: {
hook: async (name: string, cb: (input: unknown) => unknown) => {
toolHooks.push({ name, cb })
return { dispose: () => {} }
}
}
}
return {
ctx,
push: (type, data) => {
queue.push({ id: 'evt_' + queue.length, created: 1, type, location: { directory: '/p' }, data })
wake?.()
},
end: () => {
done = true
wake?.()
},
toolHooks,
subscribed: () => subs,
signal: () => sig
}
}
const flush = (): Promise<void> => new Promise((r) => setTimeout(r, 0))
it('1.x file: ONLY the named function export — a default would crash opencode <= 1.2.10', async () => {
const mod = await load(buildOpencodePlugin())
// opencode <= 1.2.10 does `for (const [, fn] of Object.entries(mod)) await fn(input)`.
expect(Object.keys(mod)).toEqual(['NodetermStatus'])
for (const v of Object.values(mod)) expect(typeof v).toBe('function')
})
it('2.x directory plugin: a default OBJECT with an id and a setup function, nothing else exported', async () => {
const mod = await load(buildOpencodeV2Plugin())
expect(Object.keys(mod)).toEqual(['default'])
const def = mod.default as V2Def
expect(typeof def).toBe('object')
expect(def.id).toBe('nodeterm-status')
expect(typeof def.setup).toBe('function')
})
it('2.x: translates the event stream to the 1.x wire names normalizeOpencode reads', async () => {
const def = await loadV2()
const v2 = v2Context()
await def.setup(v2.ctx)
expect(v2.subscribed()).toBe(1)
v2.push('session.created', { sessionID: 'ses_1', projectID: 'p', slug: 's', version: '2.0.30' })
v2.push('session.inbox.enqueued', { sessionID: 'ses_1' })
v2.push('session.execution.started', { sessionID: 'ses_1' })
v2.push('session.text.delta', { sessionID: 'ses_1', delta: 'hi' })
v2.push('permission.asked', { id: 'per_1', sessionID: 'ses_1', action: 'shell' })
v2.push('permission.replied', { sessionID: 'ses_1', requestID: 'per_1', reply: 'once' })
v2.push('form.created', { form: { id: 'frm_1', sessionID: 'ses_1', title: 'Questions' } })
v2.push('form.replied', { id: 'frm_1', sessionID: 'ses_1', answer: { q0: 'Red' } })
v2.push('form.created', { form: { id: 'frm_2', sessionID: 'ses_1' } })
v2.push('form.cancelled', { id: 'frm_2', sessionID: 'ses_1' })
v2.push('session.execution.succeeded', { sessionID: 'ses_1' })
v2.push('session.execution.started', { sessionID: 'ses_1' })
v2.push('session.execution.interrupted', { sessionID: 'ses_1' })
v2.push('session.execution.started', { sessionID: 'ses_1' })
v2.push('session.execution.failed', { sessionID: 'ses_1', error: {} })
await flush()
expect(posts).toEqual([
{ event: 'session.created', sessionID: 'ses_1' },
{ event: 'message.updated', sessionID: 'ses_1', role: 'user' },
{ event: 'permission.asked', sessionID: 'ses_1' },
{ event: 'permission.replied', sessionID: 'ses_1' },
{ event: 'question.asked', sessionID: 'ses_1' },
{ event: 'question.replied', sessionID: 'ses_1' },
{ event: 'question.asked', sessionID: 'ses_1' },
{ event: 'question.rejected', sessionID: 'ses_1' },
{ event: 'session.idle', sessionID: 'ses_1' },
{ event: 'message.updated', sessionID: 'ses_1', role: 'user' },
{ event: 'session.idle', sessionID: 'ses_1' },
{ event: 'message.updated', sessionID: 'ses_1', role: 'user' },
{ event: 'session.error', sessionID: 'ses_1' }
])
v2.end()
})
it('2.x: a real 2.0.30 TUI turn (as captured) normalizes to the same states as a 1.x turn', async () => {
// The order a measured `opencode --standalone` turn produced: a shell call behind a
// permission prompt, then a question form, then the end of the turn.
const def = await loadV2()
const v2 = v2Context()
await def.setup(v2.ctx)
const hook = v2.toolHooks[0].cb
v2.push('session.created', { sessionID: 'ses_1' })
v2.push('session.execution.started', { sessionID: 'ses_1' })
await flush()
hook({ tool: 'shell', sessionID: 'ses_1' })
v2.push('permission.asked', { id: 'per_1', sessionID: 'ses_1' })
v2.push('permission.replied', { sessionID: 'ses_1', requestID: 'per_1', reply: 'once' })
await flush()
hook({ tool: 'question', sessionID: 'ses_1' })
v2.push('form.created', { form: { id: 'frm_1', sessionID: 'ses_1' } })
v2.push('form.replied', { id: 'frm_1', sessionID: 'ses_1', answer: { q0: 'Red' } })
v2.push('session.execution.succeeded', { sessionID: 'ses_1' })
await flush()
const states = posts.map((payload) => {
const n = normalizeOpencode({ nodeId: 'node-1', agentId: 'opencode', payload })
return n && (n.kind === 'state' ? n.state + (n.newTurn ? '+newTurn' : '') : n.kind)
})
expect(states).toEqual([
'session',
'working+newTurn',
'working',
'blocked',
'working',
'working',
'blocked',
'working',
'done'
])
v2.end()
})
it('2.x: the tool hook posts tool.execute.before and never throws into the tool call', async () => {
const def = await loadV2()
const v2 = v2Context()
await def.setup(v2.ctx)
expect(v2.toolHooks.map((h) => h.name)).toEqual(['execute.before'])
expect(() => v2.toolHooks[0].cb({ tool: 'shell', sessionID: 'ses_1', id: 'call_1' })).not.toThrow()
expect(() => v2.toolHooks[0].cb(undefined)).not.toThrow()
expect(posts[0]).toEqual({ event: 'tool.execute.before', sessionID: 'ses_1' })
v2.end()
})
it('2.x: a subagent child session does not move the node, but its blocking prompts do (under the root id)', async () => {
const def = await loadV2()
const v2 = v2Context()
await def.setup(v2.ctx)
v2.push('session.created', { sessionID: 'ses_c', parentID: 'ses_1' })
v2.push('session.created', { sessionID: 'ses_g', parentID: 'ses_c' })
v2.push('session.execution.started', { sessionID: 'ses_c' })
v2.push('permission.asked', { id: 'per_1', sessionID: 'ses_g' })
v2.push('form.created', { form: { id: 'frm_1', sessionID: 'ses_c' } })
v2.push('form.replied', { id: 'frm_1', sessionID: 'ses_c' })
v2.push('session.execution.succeeded', { sessionID: 'ses_c' })
await flush()
v2.toolHooks[0].cb({ tool: 'read', sessionID: 'ses_c' })
expect(posts).toEqual([
{ event: 'permission.asked', sessionID: 'ses_1' },
{ event: 'question.asked', sessionID: 'ses_1' },
{ event: 'question.replied', sessionID: 'ses_1' }
])
v2.end()
})
it('2.x: stays inert inside the shared background server (`serve --service`) — its env names another pane', async () => {
const def = await loadV2()
const v2 = v2Context()
const argv = process.argv
process.argv = ['bun', '/$bunfs/root/opencode', 'serve', '--service']
try {
await def.setup(v2.ctx)
} finally {
process.argv = argv
}
expect(v2.subscribed()).toBe(0)
expect(v2.toolHooks).toEqual([])
expect(g[LATCH]).toBeUndefined()
})
it('2.x: no NODETERM_NODE_ID (outside nodeterm) → no subscription, no hook', async () => {
vi.stubEnv('NODETERM_NODE_ID', '')
const def = await loadV2()
const v2 = v2Context()
await def.setup(v2.ctx)
expect(v2.subscribed()).toBe(0)
expect(v2.toolHooks).toEqual([])
})
it('2.x: a context without an event stream (a 1.x compatibility pass) is a no-op', async () => {
const def = await loadV2()
await def.setup({ options: {}, agent: {}, catalog: {} })
await def.setup(undefined)
expect(g[LATCH]).toBeUndefined()
})
it('both plugins in ONE process: 1.x armed first keeps 2.x inert (no double posts)', async () => {
const v1 = await loadV1()
const hooks = await v1.NodetermStatus()
const def = await loadV2()
const v2 = v2Context()
await def.setup(v2.ctx)
expect(v2.subscribed()).toBe(0)
await hooks.event({ event: { type: 'session.idle', properties: { sessionID: 'ses_1' } } })
expect(posts).toEqual([{ event: 'session.idle', sessionID: 'ses_1' }])
})
it('both plugins in ONE process: 2.x armed first keeps the 1.x hooks empty', async () => {
const def = await loadV2()
const v2 = v2Context()
await def.setup(v2.ctx)
const v1 = await loadV1()
expect(await v1.NodetermStatus()).toEqual({})
v2.end()
})
it('the latch is per API, not per call: a second plugin instance of the SAME API still arms', async () => {
const v1 = await loadV1()
expect(typeof (await v1.NodetermStatus()).event).toBe('function')
expect(typeof (await v1.NodetermStatus()).event).toBe('function')
const def = await loadV2()
delete g[LATCH]
const a = v2Context()
const b = v2Context()
await def.setup(a.ctx)
await def.setup(b.ctx)
expect(a.subscribed()).toBe(1)
expect(b.subscribed()).toBe(1)
a.end()
b.end()
})
it('2.x: the cleanup setup returns aborts the subscription', async () => {
const def = await loadV2()
const v2 = v2Context()
const cleanup = await def.setup(v2.ctx)
expect(typeof cleanup).toBe('function')
expect(v2.signal()?.aborted).toBe(false)
;(cleanup as () => void)()
expect(v2.signal()?.aborted).toBe(true)
v2.end()
})
})