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
test(relay): e2e — bootstrap, pinned owner join, live share and unshare
reviewb60ef042c572
diff --git a/src/server/hosted-e2e.test.ts b/src/server/hosted-e2e.test.tsindex 0b484b547..54a9fd8bf 100644--- a/src/server/hosted-e2e.test.ts+++ b/src/server/hosted-e2e.test.ts@@ -12,6 +12,11 @@// the owner's canvas ops are written to the shared project's file by this core, the viewer hears// them and cannot cast one, an outside edit of the file reaches the owner as ops → `team unshare`// silences the viewer's terminal → a restart on the same data dir keeps every edit.+// A second test starts from a server with no team at all and drives `team bootstrap`, the one verb+// the desktop's "Share with team" calls: it sets up the team, the owner, an adopted folder and its+// share → the owner joins with no SAS on either side → a re-run changes nothing and keeps the code →+// a second folder's share reaches the connected owner live (`relay:hosted:shared-changed`) → so does+// its `team unshare`.//// What is real and what is not:// - REAL: startServer and every core service it boots, the admin unix socket and its client, the@@ -31,9 +36,10 @@// that polls is the project file (`projectFileWhen`): the authority's flush is a disk write, and no// client is sent an event for it. It polls every 100 ms under a step deadline.//-// One data dir per file (see hosted-boot.test.ts: some core paths are memoized per process, so a-// boot on ANOTHER data dir would write into this one). The restart boots a second server on the-// SAME data dir, which is exactly where those memoized paths already point.+// One data dir per test. The per-process memos hosted-boot.test.ts warns about (the context-link+// dir, the hook endpoint file) are re-derived by every boot (`initContextLink`) and dropped by every+// close (`hookServer.stop()`), so a later test's boot does not write into an earlier test's removed+// dir. The first test's restart boots a second server on the SAME data dir.import { describe, it, expect, vi, afterEach, afterAll } from 'vitest'import { execFileSync } from 'node:child_process'import fs from 'node:fs'@@ -55,6 +61,7 @@ import type { RelayTransport } from '../core/relay/relay-socket'import { IPC } from '../shared/ipc'import { mutationKey } from '../shared/canvas-order'import { seededColumnId } from '../shared/kanban-default-board'+import type { BootstrapResult } from '../shared/share-team'import type { CanvasMutation, CanvasNodeState, Project, PtyCreateResult, Workspace } from '../shared/types'// A broken seam must fail HERE, never reach production. index.ts reads NODETERM_RELAY_URL at module@@ -367,39 +374,42 @@ afterAll(() => {else process.env.NODETERM_RELAY_URL = env.prev})-// The admin channel is a unix socket, which Windows does not have (team-admin.ts refuses it by-// name there), so no hosted team can be set up on that platform. Linux and macOS run it.-describe.skipIf(process.platform === 'win32')('hosted team relay, end to end on a headless server', () => {- it('admin setup → owner auto-approved → guest waits → approved as viewer → watches the owner’s terminal, starts none, writes nothing → shared canvas edits persist with no browser attached and survive a restart', async () => {- spawned.length = 0- const dataDir = fs.mkdtempSync(path.join(SHORT_BASE, 'nthe-'))- teardown.push(() => fs.rmSync(dataDir, { recursive: true, force: true }))- // Plain-shell terminals (see the header), from the server's own settings file.- fs.writeFileSync(path.join(dataDir, 'settings.json'), JSON.stringify({ tmuxEnabled: false }))-- // The relay: each listener the scheduler opens is one in-process transport pair, and its peer end- // is handed to whichever teammate connects next — the relay's pairing, minus the network. A fresh- // queue per boot (step 9): the listeners a closed server opened are dead ends.- let listeners = fifo<RelayTransport>()- const relayTestTransport = (): RelayTransport => {+/** A fresh data dir, removed after the test. Its terminals are plain shells, from the server's own+ * settings file (see the header). */+function hostedDataDir(): string {+ const dataDir = fs.mkdtempSync(path.join(SHORT_BASE, 'nthe-'))+ teardown.push(() => fs.rmSync(dataDir, { recursive: true, force: true }))+ fs.writeFileSync(path.join(dataDir, 'settings.json'), JSON.stringify({ tmuxEnabled: false }))+ return dataDir+}++/** The relay and the host-token API, faked in-process. */+function fakeRelay() {+ // The host-token API, proof of possession included: a byte-exact mirror of the backend issues+ // the challenge and refuses a mint whose proof does not verify, so a host that stopped proving it+ // holds its key (or proved the wrong thing) never gets a listener. A token good for an hour, so+ // no listener refresh lands mid-test.+ const popServer = createTestPopServer()+ const relay = {+ /** Each listener the scheduler opens is one in-process transport pair, and its peer end is+ * handed to whichever teammate connects next — the relay's pairing, minus the network. Replace+ * it for a fresh boot: the listeners a closed server opened are dead ends. */+ listeners: fifo<RelayTransport>(),+ /** Every host-token mint the host asked for, in order. */+ mints: [] as Array<{ url: string; body: Record<string, unknown> }>,+ relayTestTransport: (): RelayTransport => {const { hostT, peerT } = transportPair()- listeners.push(peerT)+ relay.listeners.push(peerT)return hostT- }- // The host-token API, proof of possession included: a byte-exact mirror of the backend issues- // the challenge and refuses a mint whose proof does not verify, so a host that stopped proving it- // holds its key (or proved the wrong thing) never gets a listener. A token good for an hour, so- // no listener refresh lands mid-test.- const popServer = createTestPopServer()- const mints: Array<{ url: string; body: Record<string, unknown> }> = []- const relayTestFetch = (async (url: string | URL | Request, init?: RequestInit) => {+ },+ relayTestFetch: (async (url: string | URL | Request, init?: RequestInit) => {const body = JSON.parse(String(init?.body ?? '{}')) as Record<string, unknown>const json = (status: number, payload: unknown) =>new Response(JSON.stringify(payload), { status, headers: { date: new Date().toUTCString() } })if (String(url).endsWith('/v1/relay/challenge')) {return json(200, popServer.issue(String(body.hostPublicKeyB64), body.purpose as 'host-token'))}- mints.push({ url: String(url), body })+ relay.mints.push({ url: String(url), body })const proven = popServer.verify({hostPublicKeyB64: String(body.hostPublicKeyB64),purpose: 'host-token',@@ -410,14 +420,46 @@ describe.skipIf(process.platform === 'win32')('hosted team relay, end to end onif (!proven) return json(403, { error: 'pop_invalid' })return json(200, { pairingToken: 'relay-token', hostId: 'H', exp: Math.floor(Date.now() / 1000) + 3600 })}) as typeof fetch- // The mint's production twin of the relay trap above: if `relayTestFetch` stopped being plumbed- // through, the mint would fall back to the global fetch — which refuses here instead of minting- // a host token against the real API.- const globalHostTokenCalls: string[] = []- vi.stubGlobal('fetch', (async (url: string | URL | Request) => {- if (String(url).includes('/v1/relay/')) globalHostTokenCalls.push(String(url))- throw new Error('hosted-e2e: the global fetch is not used in this test')- }) as typeof fetch)+ }+ return relay+}++/** The mint's production twin of the relay trap at the top: if `relayTestFetch` stopped being+ * plumbed through, the mint would fall back to the global fetch — which refuses here instead of+ * minting a host token against the real API. Returns the relay URLs that reached it. */+function trapGlobalFetch(): string[] {+ const calls: string[] = []+ vi.stubGlobal('fetch', (async (url: string | URL | Request) => {+ if (String(url).includes('/v1/relay/')) calls.push(String(url))+ throw new Error('hosted-e2e: the global fetch is not used in this test')+ }) as typeof fetch)+ return calls+}++/** A headless boot on `dataDir` that dials the fake relay. */+function hostedConfig(dataDir: string, relay: ReturnType<typeof fakeRelay>): Parameters<typeof startServer>[0] {+ return {+ port: 0,+ host: '127.0.0.1',+ dataDir,+ rendererDir: path.join(dataDir, 'no-renderer'),+ insecureHttp: false,+ headless: true,+ // Never touch the developer's real agent configs (see ServerConfig.installHooks).+ installHooks: false,+ relayTestTransport: relay.relayTestTransport,+ relayTestFetch: relay.relayTestFetch+ }+}++// The admin channel is a unix socket, which Windows does not have (team-admin.ts refuses it by+// name there), so no hosted team can be set up on that platform. Linux and macOS run it.+describe.skipIf(process.platform === 'win32')('hosted team relay, end to end on a headless server', () => {+ it('admin setup → owner auto-approved → guest waits → approved as viewer → watches the owner’s terminal, starts none, writes nothing → shared canvas edits persist with no browser attached and survive a restart', async () => {+ spawned.length = 0+ const dataDir = hostedDataDir()+ const relay = fakeRelay()+ const globalHostTokenCalls = trapGlobalFetch()// The shared project's folder: a subfolder of a real repository, in its own temp dir.const repoBase = fs.mkdtempSync(path.join(SHORT_BASE, 'nther-'))@@ -435,18 +477,7 @@ describe.skipIf(process.platform === 'win32')('hosted team relay, end to end on}// Both boots (step 9 restarts on the same data dir) take this config.- const config: Parameters<typeof startServer>[0] = {- port: 0,- host: '127.0.0.1',- dataDir,- rendererDir: path.join(dataDir, 'no-renderer'),- insecureHttp: false,- headless: true,- // Never touch the developer's real agent configs (see ServerConfig.installHooks).- installHooks: false,- relayTestTransport,- relayTestFetch- }+ const config = hostedConfig(dataDir, relay)const booting = startServer(config)// Registered BEFORE the boot is awaited: a boot that outlives its step deadline is still closed// once it lands, instead of leaking a server (and its admin socket) into the next test. The wait@@ -475,11 +506,11 @@ describe.skipIf(process.platform === 'win32')('hosted team relay, end to end onawait admin(dataDir, { cmd: 'share', projectId: SHARED, on: true })// ---- 2. The owner connects: a team member, so the host approves it without a human.- const owner = teammate(code, await step('first listener', listeners.next()), ownerKeys, true)+ const owner = teammate(code, await step('first listener', relay.listeners.next()), ownerKeys, true)teardown.push(() => owner.c.close())await step('owner approved', owner.approved)// The host minted that listener's token for THIS host key, through the seam, proving it holds it.- expect(mints[0]).toMatchObject({+ expect(relay.mints[0]).toMatchObject({url: expect.stringMatching(/\/v1\/relay\/host-token$/),body: {hostPublicKeyB64: code.hostPublicKeyB64,@@ -508,7 +539,7 @@ describe.skipIf(process.platform === 'win32')('hosted team relay, end to end on// ---- 3. A guest knocks. It waits; only the owner hears of it, with the SAS the guest sees.const guestKeys = genKeyPair()const knock = owner.event(IPC.relayHostedPeerPending)- const guest = teammate(code, await step('second listener', listeners.next()), guestKeys, false)+ const guest = teammate(code, await step('second listener', relay.listeners.next()), guestKeys, false)teardown.push(() => guest.c.close())const pending = (await step('owner told of the guest', knock)).args?.[0] as { pendingId: string; sas: string; peerKeyB64: string }expect(pending.peerKeyB64).toBe(pub(guestKeys))@@ -730,12 +761,12 @@ describe.skipIf(process.platform === 'win32')('hosted team relay, end to end on// the authority's stop (which writes what is owed) is pinned in hosted-boot.test.ts.expect(positionOf(readProjectFile(sharedCwd).file.nodes, IDLE)).toEqual({ x: 654, y: 0 })- listeners = fifo<RelayTransport>()+ relay.listeners = fifo<RelayTransport>()const rebooting = startServer(config)teardown.push(() => step('second server teardown', rebooting.catch(() => null).then((s) => s?.close())))await step('server boot after the restart', rebooting)// The owner comes back the way a bookmarked, already-approved host is rejoined: pinned.- const back = teammate(code, await step('listener after the restart', listeners.next()), ownerKeys, true)+ const back = teammate(code, await step('listener after the restart', relay.listeners.next()), ownerKeys, true)teardown.push(() => back.c.close())await step('owner approved after the restart', back.approved)const reloaded = await back.call(IPC.workspaceLoad)@@ -750,4 +781,80 @@ describe.skipIf(process.platform === 'win32')('hosted team relay, end to end on// Nothing ever went around the seams.expect(globalHostTokenCalls).toEqual([])}, 90_000)++ it('team bootstrap sets up the team, the owner and a shared project; a second share appears live; unshare goes', async () => {+ const dataDir = hostedDataDir()+ const relay = fakeRelay()+ const globalHostTokenCalls = trapGlobalFetch()+ // The folders bootstrap adopts: real directories on this host. Registered before the server's+ // teardown, so they are removed after it closes (the canvas authority may still write into them).+ const folderA = fs.mkdtempSync(path.join(SHORT_BASE, 'nte-a-'))+ teardown.push(() => fs.rmSync(folderA, { recursive: true, force: true }))+ const folderB = fs.mkdtempSync(path.join(SHORT_BASE, 'nte-b-'))+ teardown.push(() => fs.rmSync(folderB, { recursive: true, force: true }))++ // No seeded workspace and no `team init`: the server boots with no team at all.+ const booting = startServer(hostedConfig(dataDir, relay))+ teardown.push(() => step('server teardown', booting.catch(() => null).then((s) => s?.close())))+ await step('server boot', booting)++ // ---- 1. One admin call: the team and its host key, hosting, the owner, the adopted folder and+ // its share.+ const ownerKeys = genKeyPair()+ const bootstrap = (adoptCwd: string): Promise<BootstrapResult> =>+ admin<BootstrapResult>(dataDir, { cmd: 'bootstrap', ownerKey: pub(ownerKeys), ownerLabel: 'Owner', adoptCwd })+ const a = await bootstrap(folderA)+ expect(a.created).toEqual({ team: true, owner: true, project: true, share: true })+ // `starting` is still a success: no relay verdict within the wait, and a join retries.+ expect(['up', 'starting']).toContain(a.hosting)+ // What the desktop is handed: a code that decodes and names this host.+ const code = decodeJoinCode(a.joinCode)+ expect(code).not.toBeNull()+ if (!code) return+ expect(code.hostId).toBe(a.hostId)++ // ---- 2. The owner joins as the desktop's share flow does: its key is a team owner and the host+ // is pinned on its side, so neither end asks a human to compare a SAS.+ const owner = teammate(code, await step('first listener', relay.listeners.next()), ownerKeys, true)+ teardown.push(() => owner.c.close())+ await step('owner approved', owner.approved)+ const status = await admin<AdminStatusResult>(dataDir, { cmd: 'status' })+ expect(status.peers).toEqual([{ label: 'Owner', role: 'owner', connected: true }])+ expect(status.pending).toEqual([])+ const ws1 = await owner.call(IPC.workspaceLoad)+ expect(ws1).toMatchObject({ ok: true })+ expect((ws1.result as Workspace).projects.map((p) => p.id)).toEqual([a.projectId])++ // ---- 3. A re-run is a no-op with the same code: nothing created, nothing re-shared.+ const again = await bootstrap(folderA)+ expect(again.created).toEqual({ team: false, owner: false, project: false, share: false })+ expect(again.joinCode).toBe(a.joinCode)+ expect(again.projectId).toBe(a.projectId)+ // One round trip on the owner's tunnel: anything the host sent it before this answer has arrived.+ expect(await owner.call(IPC.relayHostedSelf)).toMatchObject({ ok: true, result: { role: 'owner' } })+ const sharedChanges = (): Frame[] =>+ owner.frames.filter((f) => f.t === 'ev' && f.channel === IPC.relayHostedSharedChanged)+ expect(sharedChanges()).toEqual([])++ // ---- 4. A second folder on the same host joins the same team, and the connected owner hears+ // of it live: the whole shared set, in the team file's order.+ const projectIdsOf = (f: Frame): unknown => (f.args?.[0] as { projectIds?: unknown } | undefined)?.projectIds+ const changed = owner.event(IPC.relayHostedSharedChanged, (p) => Array.isArray(p.projectIds) && p.projectIds.length === 2)+ const b = await bootstrap(folderB)+ expect(b.created).toEqual({ team: false, owner: false, project: true, share: true })+ expect(b.joinCode).toBe(a.joinCode)+ expect(projectIdsOf(await step('shared-changed (2)', changed))).toEqual([a.projectId, b.projectId])+ const ws2 = await owner.call(IPC.workspaceLoad)+ expect(ws2).toMatchObject({ ok: true })+ expect((ws2.result as Workspace).projects.map((p) => p.id).sort()).toEqual([a.projectId, b.projectId].sort())++ // ---- 5. `team unshare` of the second: the owner hears the set shrink.+ const gone = owner.event(IPC.relayHostedSharedChanged, (p) => Array.isArray(p.projectIds) && p.projectIds.length === 1)+ await admin(dataDir, { cmd: 'share', projectId: b.projectId, on: false })+ expect(projectIdsOf(await step('shared-changed (1)', gone))).toEqual([a.projectId])++ expect(owner.denied).toEqual([])+ // Nothing ever went around the seams.+ expect(globalHostTokenCalls).toEqual([])+ }, 90_000)})