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
// The Server Edition's half of context-link: deriving the link map from persisted canvases, and
// registering the read handler core answers with. The reads themselves (authorization, transcript
// parsing, the local/remote split) are core's and are covered by src/core/context-link.handler.test.ts —
// what is tested here is the wiring that was missing server-side.
import { describe, it, expect, beforeEach, afterEach, afterAll, vi } from 'vitest'
import {
existsSync,
mkdtempSync,
promises as fsPromises,
readFileSync,
rmSync,
writeFileSync
} from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { deriveLinkMap, initServerContextLink } from './context-link'
import { setNodeTranscript } from '../core/context-link-core'
import { hookServer } from '../core/agents/hook-server'
import { initPlatform, resetPlatformForTests } from '../core/platform'
import { fakePlatform } from '../core/platform-fake'
import type { CanvasNodeState } from '../shared/types'
import type { PtyManager } from '../core/pty-manager'
const dir = mkdtempSync(join(tmpdir(), 'srv-ctxlink-'))
// initContextLink installs the skill + instruction blocks under the user's HOME. Point HOME at a
// scratch dir for the duration so a test run never edits the real ~/.claude / ~/.codex / ~/.gemini.
const realHome = process.env.HOME
let home = ''
/** Enough PtyManager for context-link: the tmux binary it stamps into each link document, and
* the terminal capture the `terminal` verb goes through. */
function fakePty(): PtyManager {
return {
getTmuxBin: () => '/usr/bin/tmux',
captureSession: async (key: string) => `pane of ${key}`
} as unknown as PtyManager
}
/** A serialized agent node, the shape `.nodeterm/project.json` stores in `nodes[]`. */
function node(id: string, over: Partial<CanvasNodeState> = {}): CanvasNodeState {
return {
id,
kind: 'terminal',
position: { x: 0, y: 0 },
size: { width: 400, height: 300 },
title: id,
color: '#fff',
group: null,
...over
} as CanvasNodeState
}
const bridge = (source: string, target: string) => ({ id: `bridge-${source}-${target}`, source, target })
beforeEach(() => {
home = mkdtempSync(join(tmpdir(), 'srv-ctxlink-home-'))
process.env.HOME = home
resetPlatformForTests()
initPlatform(fakePlatform({ userDataDir: dir }))
})
afterEach(() => {
if (realHome === undefined) delete process.env.HOME
else process.env.HOME = realHome
rmSync(home, { recursive: true, force: true })
})
afterAll(() => rmSync(dir, { recursive: true, force: true }))
describe('deriveLinkMap', () => {
it('maps a bridge between two agent nodes in BOTH directions', () => {
const map = deriveLinkMap({
canvases: () => [
{
id: 'p1',
nodes: [node('term-a', { title: 'Alpha' }), node('term-b', { title: 'Beta' })],
bridges: [bridge('term-a', 'term-b')]
}
]
})
expect(map['term-a']).toEqual([{ id: 'term-b', title: 'Beta', cwd: '' }])
expect(map['term-b']).toEqual([{ id: 'term-a', title: 'Alpha', cwd: '' }])
})
it('covers EVERY canvas — headless, no project is the active one', () => {
const map = deriveLinkMap({
canvases: () => [
{ id: 'p1', nodes: [node('a'), node('b')], bridges: [bridge('a', 'b')] },
{ id: 'p2', nodes: [node('c'), node('d')], bridges: [bridge('c', 'd')] }
]
})
// The desktop skips the active project (its renderer supplies that one live). There is no
// renderer here, so skipping any project would silently sever a running agent's links.
expect(Object.keys(map).sort()).toEqual(['a', 'b', 'c', 'd'])
})
it('drops bridges whose endpoints are no longer on the canvas', () => {
const map = deriveLinkMap({
canvases: () => [
{ id: 'p1', nodes: [node('a')], bridges: [bridge('a', 'deleted')] }
]
})
expect(map).toEqual({})
})
it('ignores a canvas with no bridges at all', () => {
expect(deriveLinkMap({ canvases: () => [{ id: 'p1', nodes: [node('a'), node('b')] }] })).toEqual({})
})
it('links a sticky note one way only — a note cannot read', () => {
const map = deriveLinkMap({
canvases: () => [
{
id: 'p1',
nodes: [node('sticky-1', { kind: 'sticky', title: 'Spec', text: 'ship it' }), node('term-a')],
bridges: [bridge('sticky-1', 'term-a')]
}
]
})
expect(map['term-a']).toEqual([{ id: 'sticky-1', title: 'Spec', note: 'ship it' }])
expect(map['sticky-1']).toBeUndefined()
})
it('takes agent + session from the hooks when the serialized node predates the launch', () => {
// A plain terminal the user started an agent CLI in by hand: project.json carries no agentId,
// but the status mirror learned both from the hook events.
const map = deriveLinkMap({
canvases: () => [{ id: 'p1', nodes: [node('a'), node('b')], bridges: [bridge('a', 'b')] }],
agentSessions: () => [{ nodeId: 'b', agentId: 'codex', sessionId: 'sess-b' }]
})
expect(map['a']).toEqual([{ id: 'b', title: 'b', cwd: '', agentId: 'codex', sessionId: 'sess-b' }])
})
})
describe('initServerContextLink', () => {
/** Start the wiring and hand back the handler it registered on the hook server — the exact
* function the /context-link/ route calls. */
function start(deps: Parameters<typeof initServerContextLink>[0]) {
const spy = vi.spyOn(hookServer, 'setContextLinkHandler')
const link = initServerContextLink(deps)
const handler = spy.mock.calls.at(-1)?.[0]
spy.mockRestore()
return { link, handler: handler!, registered: !!handler }
}
it('registers the read handler the route would otherwise refuse for', async () => {
const { link, handler, registered } = start({
ptyManager: fakePty(),
canvases: () => [
{
id: 'p1',
nodes: [node('term-a', { title: 'Alpha' }), node('term-b', { title: 'Beta' })],
bridges: [bridge('term-a', 'term-b')]
}
]
})
// Without this registration the hook server answers every read with
// "Context link is unavailable in this session." — the whole desktop-only symptom.
expect(registered).toBe(true)
const shimBody = readFileSync(join(dir, 'context-links', 'context.sh'), 'utf8')
expect(shimBody).toContain('CODEX_THREAD_ID')
expect(shimBody).toContain(join(dir, 'codex-thread-nodes'))
await link.refresh()
const out = await handler({ verb: 'list', nodeId: 'term-a', args: {} })
expect(out).toContain('Beta')
expect(out).toContain('term-b')
await link.stop()
})
it('answers a node with no links, rather than pretending the feature is missing', async () => {
const { link, handler } = start({
ptyManager: fakePty(),
canvases: () => []
})
await link.refresh()
const out = await handler({ verb: 'list', nodeId: 'term-a', args: {} })
expect(out).toContain('No linked nodes')
await link.stop()
})
it('never writes into the agent config dirs itself — that is the consent lifecycle\'s (#744)', async () => {
const { link, registered } = start({
ptyManager: fakePty(),
canvases: () => []
})
expect(registered).toBe(true)
expect(existsSync(join(home, '.claude', 'skills', 'get-linked-context', 'SKILL.md'))).toBe(false)
expect(existsSync(join(home, '.codex', 'AGENTS.md'))).toBe(false)
await link.stop()
})
it('picks up a bridge drawn after boot', async () => {
let bridges = [] as ReturnType<typeof bridge>[]
const { link, handler } = start({
ptyManager: fakePty(),
canvases: () => [{ id: 'p1', nodes: [node('term-a'), node('term-b', { title: 'Beta' })], bridges }]
})
await link.refresh()
expect(await handler({ verb: 'list', nodeId: 'term-a', args: {} })).toContain('No linked nodes')
// What a browser drawing the edge produces: a workspace save, and the onPersist refresh.
bridges = [bridge('term-a', 'term-b')]
await link.refresh()
expect(await handler({ verb: 'list', nodeId: 'term-a', args: {} })).toContain('Beta')
const docPath = join(dir, 'context-links', 'term-a.json')
expect(JSON.parse(readFileSync(docPath, 'utf8')).links[0].id).toBe('term-b')
expect(await handler({ verb: 'list', nodeId: 'term-b', args: {} })).toContain('term-a')
bridges = []
await link.refresh()
expect(await handler({ verb: 'list', nodeId: 'term-a', args: {} })).toContain('No linked nodes')
expect(existsSync(docPath)).toBe(false)
await link.stop()
})
it('rewrites when a linked node\'s transcript arrives, though the canvas never changed', async () => {
const transcript = join(dir, 'late.jsonl')
writeFileSync(transcript, JSON.stringify({ type: 'user', message: { content: 'ship it' } }))
const canvases = () => [
{
id: 'p1',
nodes: [node('term-a'), node('term-b', { title: 'Beta', agentId: 'claude' as const })],
bridges: [bridge('term-a', 'term-b')]
}
]
const { link, handler } = start({
ptyManager: fakePty(),
canvases
})
await link.refresh()
expect(await handler({ verb: 'summary', nodeId: 'term-a', args: {} })).toContain(
'no conversation transcript yet'
)
// The transcript path is hook-fed, so it lands with no canvas change behind it — the sweep's
// change signature has to include it or the link document stays permanently empty.
setNodeTranscript('term-b', 'sess-b', transcript)
await link.refresh()
expect(await handler({ verb: 'summary', nodeId: 'term-a', args: {} })).toContain('user: ship it')
await link.stop()
})
it('settles owed writes on stop, and writes nothing afterwards', async () => {
const { link } = start({
ptyManager: fakePty(),
canvases: () => [
{ id: 'p1', nodes: [node('term-a'), node('term-b')], bridges: [bridge('term-a', 'term-b')] }
]
})
// Neither the sweep nor onPersist awaits a refresh, so at close there is normally one in
// flight. A stop that does not drain it lets link files land in a dataDir the caller is
// already tearing down (a server test caught exactly that, as ENOTEMPTY).
const owed = link.refresh()
await link.stop()
await expect(owed).resolves.toBeUndefined()
const writes = vi.spyOn(fsPromises, 'writeFile')
await link.refresh()
expect(writes).not.toHaveBeenCalled()
writes.mockRestore()
})
it('skips the rewrite when nothing moved', async () => {
const { link } = start({
ptyManager: fakePty(),
canvases: () => [
{ id: 'p1', nodes: [node('term-a'), node('term-b')], bridges: [bridge('term-a', 'term-b')] }
]
})
await link.refresh()
// The sweep runs every 15s for the life of the server: an unconditional rewrite would be a
// clear-and-rewrite of every link file, forever, on a canvas nobody is touching.
const writes = vi.spyOn(fsPromises, 'writeFile')
await link.refresh()
await link.refresh()
expect(writes).not.toHaveBeenCalled()
writes.mockRestore()
await link.stop()
})
})