Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

perf(cli): load the peer library only when P2P needs it (#935)

Dee76283e059d52
diff --git a/cli/e2e/harness/p2pPhone.ts b/cli/e2e/harness/p2pPhone.ts
new file mode 100644
index 000000000..5e90b75ec
--- /dev/null
+++ b/cli/e2e/harness/p2pPhone.ts
@@ -0,0 +1,98 @@
+/** A paired test phone with a real encrypted WebRTC channel to the isolated gateway.
+ * Kept apart from RelayPhone: a relay-only test must not silently become a P2P test.
+ * Host candidates only; no public STUN, TURN or account is used. */
+import { WebSocket } from 'ws'
+import { RelaySessionCrypto } from '../../src/lib/e2ee/relayClient.js'
+import { TerminalP2pInitiator, TERMINAL_P2P_SIGNAL_TYPES } from '../../src/lib/terminalP2p.js'
+import type { TerminalBinaryClear } from '../../src/lib/terminalBinary.js'
+import type { Frame } from './client.js'
+import { until } from './daemon.js'
+import type { PhoneMachine } from './fleet.js'
+
+type Transport = 'relay' | 'p2p'
+
+export class P2pPhone {
+ readonly frames: Array<{ frame: Frame; transport: Transport }> = []
+ readonly binaries: Array<{ frame: TerminalBinaryClear; transport: Transport }> = []
+ readonly errors: string[] = []
+ readonly peer: TerminalP2pInitiator
+ private readonly crypto: RelaySessionCrypto
+ private readonly ws: WebSocket
+
+ private constructor(world: PhoneMachine) {
+ const { backend, machine, phone } = world
+ this.crypto = new RelaySessionCrypto({ machineId: machine.machineId,
+ selfIdentity: phone.identity, peerPub: machine.identity.pub })
+ this.ws = new WebSocket(`${backend.wsUrl}/api/web-ws?autonomousEnv=prod`, [phone.token])
+ this.peer = new TerminalP2pInitiator({
+ policy: { enabled: true, protocolVersion: 1, stunUrls: [], openWaitMs: 1_500 },
+ sendSignal: (type, payload) => this.send(type, { ...payload }, 'relay'),
+ onData: data => this.receive(data, typeof data !== 'string', 'p2p'),
+ })
+ this.ws.on('error', error => this.errors.push(error.message))
+ this.ws.on('open', () => this.ws.send(JSON.stringify({ type: 'machine_select', payload: { machineId: machine.machineId } })))
+ this.ws.on('message', (data, binary) => this.receive(binary ? Buffer.concat(Array.isArray(data) ? data : [Buffer.from(data as ArrayBuffer)]) : data.toString(), binary, 'relay'))
+ }
+
+ static async open(world: PhoneMachine): Promise<P2pPhone> {
+ // QA #906: local readiness precedes gateway registration; an early hello is otherwise lost.
+ await until('the gateway on the fake backend', () => world.backend.nodeUp(world.machine.machineId), 30_000)
+ const phone = new P2pPhone(world)
+ try {
+ await until('the paired P2P phone session', () => phone.crypto.ready, 20_000)
+ if (phone.crypto.terminalP2pVersion !== 1) throw new Error('gateway did not advertise terminal P2P')
+ return phone
+ } catch (error) {
+ await phone.close()
+ throw error
+ }
+ }
+
+ private receive(data: string | Buffer, binary: boolean, transport: Transport): void {
+ if (binary) {
+ const frame = this.crypto.decryptTerminal(Buffer.from(data))
+ if (frame) this.binaries.push({ frame, transport })
+ else this.errors.push('terminal frame did not authenticate')
+ return
+ }
+ let frame: Frame
+ try { frame = JSON.parse(data.toString()) as Frame } catch { this.errors.push('invalid JSON'); return }
+ if (!this.crypto.ready) {
+ if (frame.type === 'connected' && frame.payload?.machineId) this.ws.send(JSON.stringify(this.crypto.helloFrame()))
+ else if (frame.type === 'e2e_welcome' && !this.crypto.handleWelcome(frame.payload ?? {})) this.errors.push('invalid welcome')
+ else if (frame.type === 'e2e_denied') this.errors.push('phone denied')
+ return
+ }
+ if (frame.type === 'e2e_rekey') { this.crypto.handleRekey(frame.payload ?? {}); return }
+ const opened = this.crypto.unwrapIncoming(frame) as Frame | null
+ if (!opened || opened.payload?.__e2e) { this.errors.push('frame did not authenticate'); return }
+ this.frames.push({ frame: opened, transport })
+ if (TERMINAL_P2P_SIGNAL_TYPES.has(opened.type)) {
+ void this.peer.handleSignal(opened.type, opened.payload).catch(error => this.errors.push(String(error)))
+ }
+ }
+
+ async negotiate(): Promise<void> {
+ this.peer.start()
+ if (!await this.peer.waitUntilReady(15_000)) throw new Error(`P2P did not connect: ${this.peer.negotiationDetail}`)
+ }
+
+ send(type: string, payload: Record<string, unknown>, transport: Transport): void {
+ if (!this.crypto.ready) throw new Error('phone has no sealed session')
+ const wire = JSON.stringify(this.crypto.wrapOutgoing({ type, payload }))
+ if (transport === 'p2p') {
+ // Never hide a failed P2P send by substituting relay: this test proves the actual channel.
+ if (!this.peer.send(wire)) throw new Error('P2P send failed')
+ } else this.ws.send(wire)
+ }
+
+ sendBinary(frame: TerminalBinaryClear): void {
+ const sealed = this.crypto.encryptTerminal(frame)
+ if (!sealed || !this.peer.send(Buffer.from(sealed))) throw new Error('P2P binary send failed')
+ }
+
+ async close(): Promise<void> {
+ await this.peer.stop('test_complete', false)
+ this.ws.terminate()
+ }
+}
diff --git a/cli/e2e/p2p.e2e.ts b/cli/e2e/p2p.e2e.ts
new file mode 100644
index 000000000..bd8674d7c
--- /dev/null
+++ b/cli/e2e/p2p.e2e.ts
@@ -0,0 +1,86 @@
+/** The gateway must still negotiate a real peer connection after its peer library becomes lazy. */
+import { randomUUID } from 'node:crypto'
+import { mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { inflateSync } from 'node:zlib'
+import { expect, it, onTestFailed } from 'vitest'
+import { TerminalBinaryKind } from '../src/lib/terminalBinary.js'
+import { LocalClient } from './harness/client.js'
+import { until } from './harness/daemon.js'
+import { startPhoneMachine } from './harness/fleet.js'
+import { P2pPhone } from './harness/p2pPhone.js'
+
+it('loads P2P on demand, carries sealed terminal bytes, then keeps the agent working over relay', async () => {
+ const world = await startPhoneMachine()
+ const { machine, backend } = world
+ const daemon = machine.daemon
+ let desk: LocalClient | undefined
+ let phone: P2pPhone | undefined
+ onTestFailed(() => {
+ console.log(`---- daemon log\n${daemon.log()}`)
+ console.log(`---- peer errors\n${JSON.stringify(phone?.errors)}`)
+ })
+ try {
+ desk = await LocalClient.connect(daemon, { machineId: machine.machineId })
+ const corePid = daemon.corePid()
+ const cwd = join(daemon.projectsDir, 'peer-terminal')
+ mkdirSync(cwd)
+ const created = await desk.request('agent_create', { engine: 'claude', cwd, bypassPermission: true }, 60_000)
+ expect(created.error, JSON.stringify(created)).toBeUndefined()
+ const agentId = created.agent.id as string
+ const inventory = async () => (await desk!.request('agents_list', { includeStopped: true })).agents as Array<Record<string, any>>
+ const bound = await until('the P2P agent conversation', async () => (await inventory()).find(a => a.id === agentId && a.sessionId), 45_000)
+ phone = await P2pPhone.open(world)
+ await phone.negotiate()
+
+ const requestId = randomUUID()
+ // QA #908: the opening keyframe can arrive in the same callback as terminal_ready.
+ const since = phone.binaries.length
+ phone.send('terminal_open', { requestId, protocolVersion: 3, agentId, cols: 100, rows: 30 }, 'p2p')
+ const answer = await until('terminal_ready over the peer channel', () => phone!.frames.find(({ frame }) =>
+ ['terminal_ready', 'terminal_error'].includes(frame.type) && frame.payload?.requestId === requestId), 30_000)
+ expect(answer.transport).toBe('p2p')
+ expect(answer.frame.type, JSON.stringify(answer.frame)).toBe('terminal_ready')
+ const streamId = answer.frame.payload!.streamId as string
+ const opening = await until('the sealed P2P keyframe', () => phone!.binaries.slice(since).find(({ frame }) =>
+ frame.streamId === streamId && frame.kind === TerminalBinaryKind.keyframe), 20_000)
+ expect(opening.transport).toBe('p2p')
+ const bytes = opening.frame.compressed ? inflateSync(opening.frame.bytes) : opening.frame.bytes
+ expect(Buffer.from(bytes).toString()).toContain('Welcome to Claude Code (fake)')
+
+ const content = 'typed across the peer channel'
+ const ended = desk.next(f => f.type === 'turn_ended' && f.agentId === agentId, 30_000, 'peer input turn ended')
+ phone.sendBinary({ kind: TerminalBinaryKind.input, streamId, seq: 0, compressed: false, bytes: Buffer.from(content + '\r') })
+ await ended
+ await until('the peer terminal to show its response', () => phone!.binaries.slice(since)
+ .filter(({ frame, transport }) => transport === 'p2p' && frame.streamId === streamId && frame.kind === TerminalBinaryKind.output)
+ .map(({ frame }) => Buffer.from(frame.compressed ? inflateSync(frame.bytes) : frame.bytes).toString()).join('').includes(content), 20_000)
+ const connId = backend.webConnections(machine.machineId).at(-1)!
+ const relayed = [...backend.webSent.get(connId) ?? [], ...backend.webReceived.get(connId) ?? []]
+ expect(relayed.some(f => f.type === 'p2p_offer')).toBe(true)
+ expect(relayed.filter(f => f.type?.startsWith('p2p_')).every(f => f.payload?.__e2e)).toBe(true)
+ expect(relayed.some(f => f.type === 'terminal_open' || f.type === 'terminal_ready')).toBe(false)
+ expect(JSON.stringify(relayed)).not.toContain(content)
+
+ // Keep the sealed session and its agent; remove only the optional peer transport.
+ await phone.peer.stop('test_relay_fallback')
+ const fallback = randomUUID()
+ phone.send('terminal_resync', { streamId }, 'relay')
+ const done = desk.next(f => f.type === 'turn_ended' && f.agentId === agentId, 30_000, 'relay turn ended')
+ phone.send('message', { agentId, content: fallback }, 'relay')
+ await done
+ const history = await desk.request('session_get', { sessionId: bound.sessionId, limit: 500 })
+ const messages = history.events.filter((event: Record<string, any>) => event.type === 'user_message')
+ .map((event: Record<string, any>) => event.payload.content ?? event.payload.text)
+ expect(messages.filter((text: string) => text === content)).toHaveLength(1)
+ expect(messages.filter((text: string) => text === fallback)).toHaveLength(1)
+ expect((await inventory()).find(a => a.id === agentId)).toMatchObject({ sessionId: bound.sessionId, status: 'active' })
+ expect(daemon.corePid()).toBe(corePid)
+ expect(daemon.coresStarted()).toBe(1)
+ expect(phone.errors).toEqual([])
+ } finally {
+ await phone?.close()
+ desk?.close()
+ await world.close()
+ }
+}, 120_000)
diff --git a/cli/src/lib/terminalP2p.ts b/cli/src/lib/terminalP2p.ts
index 0f9b30214..0d58cb373 100644
--- a/cli/src/lib/terminalP2p.ts
+++ b/cli/src/lib/terminalP2p.ts
@@ -1,5 +1,5 @@
import { randomUUID } from 'node:crypto'
-import { RTCPeerConnection, type RTCDataChannel, type RTCIceCandidateInit } from 'werift'
+import type { RTCPeerConnection, RTCDataChannel, RTCIceCandidateInit } from 'werift'
import { env } from '../config/env.js'
import { pickTurnUrl, selectStunUrls, type StunSelector } from './stunSelect.js'
@@ -291,7 +291,7 @@ export class TerminalP2pInitiator {
this.timeout = setTimeout(() => this.fail('negotiation_timeout'), TERMINAL_P2P_NEGOTIATION_TIMEOUT_MS)
this.timeout.unref?.()
this.deps.onState?.('connecting', 0)
- void this.begin()
+ void this.begin().catch(() => this.fail('offer_failed'))
}
private async begin(): Promise<void> {
@@ -302,7 +302,10 @@ export class TerminalP2pInitiator {
stunUrls = selection.urls
udpReachable = selection.udpReachable
} catch { /* the selector contract is that it never rejects; keep the policy order regardless */ }
- // stop()/fail() may have run while the race was in flight. Building the peer connection now would
+ // Found by QA on a quiet machine: idle gateways loaded werift without a single P2P signal.
+ // Node shares this deferred module across negotiations; relay-only connections never load it.
+ const { RTCPeerConnection } = await import('werift')
+ // stop()/fail() may have run while STUN or the import was in flight. Building the connection now would
// strand it: nothing holds a reference any more, so its UDP sockets would never be closed.
if (this.finished) return
this.step('stun-raced')
@@ -656,7 +659,7 @@ export class TerminalP2pResponderPool {
}
/** STUN race + RTCPeerConnection construction shared by acceptOffer/acceptUpgradeOffer. `stillCurrent`
- * is re-checked after the only await in here (the STUN race) so a superseded offer never publishes a
+ * is re-checked after STUN and the library load so a superseded offer never publishes a
* peer connection nothing would ever close. Returns null when superseded — caller just returns. */
private async buildResponderEntry(
connId: string,
@@ -672,6 +675,7 @@ export class TerminalP2pResponderPool {
// The offerer raced these too, and may well have landed on a different server. That is fine: a
// srflx candidate is each peer's own public address, so the two sides need not agree on who to ask.
const selection = await this.selectStunUrls(offeredStunUrls)
+ const { RTCPeerConnection } = await import('werift')
if (!stillCurrent()) return null
const turn = turnChoice(readTurn(payload.turn), selection.udpReachable)
const pc = new RTCPeerConnection(peerConfig(selection.urls, turn))
diff --git a/cli/src/lib/terminalP2pLoading.spec.ts b/cli/src/lib/terminalP2pLoading.spec.ts
new file mode 100644
index 000000000..9a3a1f68c
--- /dev/null
+++ b/cli/src/lib/terminalP2pLoading.spec.ts
@@ -0,0 +1,107 @@
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { build } from 'esbuild'
+import { expect, it } from 'vitest'
+
+it('loads the real peer library once, only when a peer negotiation needs it', async () => {
+ // Found by QA on a quiet machine: a gateway paid for werift before any P2P traffic.
+ // Observe real module evaluation in a disposable split bundle, not Node's CommonJS cache.
+ const root = mkdtempSync(join(tmpdir(), 'terminal-p2p-loading-'))
+ const module = fileURLToPath(new URL('./terminalP2p.ts', import.meta.url))
+ const cli = fileURLToPath(new URL('../../', import.meta.url))
+ let observedModules = 0
+ try {
+ await build({
+ stdin: {
+ sourcefile: 'peer-loading.ts', resolveDir: cli, loader: 'ts',
+ contents: `
+ import assert from 'node:assert/strict';
+ import { TerminalP2pInitiator, TerminalP2pResponderPool } from ${JSON.stringify(module)};
+ const evaluations = () => globalThis.__qaPeerLibraryEvaluations ?? 0;
+ assert.equal(evaluations(), 0, 'importing the gateway P2P module must not evaluate werift');
+ const pool = new TerminalP2pResponderPool({ sendSignal() {}, onData() {},
+ selectStunUrls: async () => ({ urls: [], udpReachable: null }) });
+ const off = new TerminalP2pInitiator({
+ policy: { enabled: false, protocolVersion: 1, stunUrls: [], openWaitMs: 0 },
+ sendSignal() {}, onData() {},
+ });
+ try {
+ off.start();
+ assert.equal(await pool.handleSignal('unused', 'agents_list', {}), false);
+ assert.equal(await pool.handleSignal('unused', 'p2p_offer', {}), true);
+ await pool.handleSignal('unused', 'p2p_abort', {
+ sessionId: '00000000-0000-4000-8000-000000000000', protocolVersion: 1,
+ });
+ assert.equal(evaluations(), 0, 'idle pools, disabled peers and irrelevant signals stay lightweight');
+ const offer = { sessionId: '00000000-0000-4000-8000-000000000001',
+ protocolVersion: 1, sdp: 'not-a-real-sdp', stunUrls: [] };
+ if (process.env.EXPECT_PEER_LOAD_FAILURE === '1') {
+ let failed;
+ const failure = new Promise(resolve => { failed = resolve });
+ const peer = new TerminalP2pInitiator({
+ policy: { enabled: true, protocolVersion: 1, stunUrls: [], openWaitMs: 0 },
+ sendSignal() {}, onData() {},
+ onState(state, _ms, reason) { if (state === 'failed') failed(reason) },
+ });
+ peer.start();
+ assert.equal(await failure, 'offer_failed');
+ assert.equal(await peer.waitUntilReady(1), false);
+ await peer.stop('test_complete', false);
+ // The gateway's dispatch boundary catches a rejected responder negotiation.
+ await assert.rejects(pool.handleSignal('missing', 'p2p_offer', offer), /Cannot find module/);
+ assert.equal(evaluations(), 0);
+ console.log(JSON.stringify({ unavailable: true }));
+ } else {
+ // The real SDP parser must load to refuse this offer. No external STUN or TURN server.
+ await pool.handleSignal('first', 'p2p_offer', offer);
+ assert.equal(evaluations(), 1, 'the first offer must actually load the peer library');
+ await Promise.all(['second', 'third'].map(id => pool.handleSignal(id, 'p2p_offer', offer)));
+ assert.equal(evaluations(), 1, 'later and concurrent offers reuse the module');
+ console.log(JSON.stringify({ evaluations: evaluations() }));
+ }
+ } finally {
+ await off.stop('test_complete', false);
+ await pool.stop();
+ }
+ `,
+ },
+ bundle: true, platform: 'node', format: 'esm', target: 'node20', splitting: true,
+ outdir: root, entryNames: 'probe', chunkNames: 'part-[hash]', outExtension: { '.js': '.mjs' },
+ external: ['bufferutil', 'utf-8-validate'], logLevel: 'silent',
+ banner: { js: 'import{createRequire as ___cr}from"node:module";const require=___cr(import.meta.url);' },
+ plugins: [{
+ name: 'observe-real-peer-module',
+ setup(builder) {
+ builder.onLoad({ filter: /[\\/]werift[\\/]lib[\\/]index\.mjs$/ }, args => {
+ observedModules++
+ return { loader: 'js', resolveDir: dirname(args.path), contents:
+ 'globalThis.__qaPeerLibraryEvaluations = (globalThis.__qaPeerLibraryEvaluations ?? 0) + 1;\n'
+ + readFileSync(args.path, 'utf8') }
+ })
+ },
+ }],
+ })
+ expect(observedModules, 'the probe must observe the actual werift entry').toBe(1)
+ // Vitest supplies throwaway homes. The child starts neither a daemon nor a tmux server.
+ const output = execFileSync(process.execPath, [join(root, 'probe.mjs')], {
+ cwd: cli, encoding: 'utf8', timeout: 15_000, maxBuffer: 1024 * 1024,
+ env: { ...process.env, NODE_OPTIONS: '' },
+ })
+ expect(JSON.parse(output.trim())).toEqual({ evaluations: 1 })
+ // A missing split chunk costs only P2P. In particular begin() must not reject unhandled.
+ const peerChunk = readdirSync(root).find(name => name.startsWith('part-')
+ && readFileSync(join(root, name), 'utf8').includes('globalThis.__qaPeerLibraryEvaluations ='))
+ expect(peerChunk, 'the actual peer module must live in a deferred chunk').toBeDefined()
+ rmSync(join(root, peerChunk!))
+ const unavailable = execFileSync(process.execPath, [join(root, 'probe.mjs')], {
+ cwd: cli, encoding: 'utf8', timeout: 15_000, maxBuffer: 1024 * 1024,
+ env: { ...process.env, NODE_OPTIONS: '', EXPECT_PEER_LOAD_FAILURE: '1' },
+ })
+ expect(JSON.parse(unavailable.trim())).toEqual({ unavailable: true })
+ } finally {
+ rmSync(root, { recursive: true, force: true })
+ }
+}, 20_000)