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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.urlsudpReachable = 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) returnthis.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 nullconst 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.tsnew file mode 100644index 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)