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
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
import { createServer, type Server } from 'node:http'
import type { AddressInfo } from 'node:net'
import { dirname, join } from 'node:path'
import { randomBytes } from 'node:crypto'
import { bridgeKey, bridgePipeRecord, bridgeSocketPath, harnessKey, retireBridgeKey, rotateHarnessKey, KEY_GRACE_MS } from '../lib/connectors/agents.js'
import { serveBridgePipe, serveBridgeSocket } from '../lib/connectors/bridge.js'
import { writePrivate } from '../lib/connectors/store.js'
import type { LocalSocketServer } from '../lib/localSocket.js'
import { Store } from '../lib/connectors/store.js'
import { fakeCore } from '../testing/fakeCore.js'
import { startConnectors } from '../services/connectors.js'
import { daemonFetch, fetchOverSocket, socketIsPrivate } from '../lib/localTransport.js'
import { unixSocketPath } from '../lib/localSocket.js'
import { bridgeRoute, connectionsBridge } from './bridge.js'
import { McpClient } from './mcp.js'
const closers: Array<() => unknown> = []
afterEach(async () => { vi.useRealTimers(); for (const close of closers.splice(0)) await close(); rmSync(home, { recursive: true, force: true }) })
let vault: Store, env: NodeJS.ProcessEnv, home: string
beforeEach(() => {
// Short: a socket has to fit.
home = mkdtempSync(join('/tmp', 'cs-'))
env = { HOME: home, PATH: '', XDG_CONFIG_HOME: join(home, '.config') }
vault = new Store(join(home, 'c'), env)
})
/** Another account on the bridge's port, recording what it hears. */
async function holder(): Promise<{ heard: string[]; port: number }> {
const heard: string[] = []
const server = createServer((request, response) => { heard.push(`${request.method} ${request.url}`); response.writeHead(404).end() })
await new Promise<void>(ready => server.listen(0, '127.0.0.1', ready))
closers.push(() => new Promise(done => { server.closeAllConnections(); server.close(done) }))
return { heard, port: (server.address() as AddressInfo).port }
}
async function service(respond: (url: string, body: string) => { status?: number; body: string; type?: string }): Promise<string> {
const server: Server = createServer((request, response) => {
let raw = ''
request.on('data', part => { raw += part })
request.on('end', () => {
const answer = respond(request.url ?? '', raw)
response.writeHead(answer.status ?? 200, { 'content-type': answer.type ?? 'application/json' }).end(answer.body)
})
})
await new Promise<void>(ready => server.listen(0, '127.0.0.1', ready))
closers.push(() => new Promise(done => { server.closeAllConnections(); server.close(done) }))
return `http://127.0.0.1:${(server.address() as AddressInfo).port}`
}
const bridgeRoute2 = (): { fetch: typeof fetch } => ({ fetch: fetchOverSocket(bridgeSocketPath(vault)!) })
const onSocket = async (): Promise<LocalSocketServer> => {
const listening = await serveBridgeSocket(vault, bridgeSocketPath(vault)!)
closers.push(() => listening.close())
return listening
}
describe('cloud agents and the bridge', () => {
it('list, API and MCP calls all go over the socket; a holder of the port hears nothing, Harness\'s key least of all', async () => {
const hold = await holder()
vi.stubEnv('HARNESS_CONNECTIONS_PORT', String(hold.port))
closers.push(() => vi.unstubAllEnvs())
const api = await service((url) => ({ body: JSON.stringify({ url }) }))
const mcp = await service((_url, body) => {
const message = JSON.parse(body) as { id?: number; method: string }
return { body: JSON.stringify({ jsonrpc: '2.0', id: message.id, result: message.method === 'tools/list' ? { tools: [{ name: 'a' }] } : { protocolVersion: '2025-06-18' } }) }
})
vault.save('devin', { access_token: 't', source: 'custom', transport: 'none', api_entry: { origin: api } } as never)
vault.save('fo', { access_token: 't', source: 'dcr', mcp_entry: { url: `${mcp}/mcp`, headers: {} } })
await onSocket()
const bridge = connectionsBridge(() => bridgeRoute(vault))
expect((await bridge.connections()).map(c => c.code).sort()).toEqual(['devin', 'fo'])
expect((await bridge.api('devin', 'GET', '/v3/self')).status).toBe(200)
const client = new McpClient(bridge.mcpUrl('fo'), 'Fo', bridge.fetch)
expect((await client.tools()).map(t => t.name)).toEqual(['a'])
expect(hold.heard).toEqual([])
})
it('with the socket gone says Connections is not running, and sends nothing to the port', async () => {
const hold = await holder()
vi.stubEnv('HARNESS_CONNECTIONS_PORT', String(hold.port))
closers.push(() => vi.unstubAllEnvs())
await expect(connectionsBridge(() => bridgeRoute(vault)).connections()).rejects.toThrow()
expect(hold.heard).toEqual([])
})
it('the socket answers Harness\'s key, and an agent\'s route on it still reaches MCP servers only', async () => {
const key = harnessKey(vault)
await onSocket()
const { fetch: over } = bridgeRoute(vault)
expect((await over(`http://bridge/${key}/connections`)).status).toBe(200)
expect((await over('http://bridge/local/connections')).status).toBe(404)
expect((await over('http://bridge/wrong-key/connections')).status).toBe(404)
})
it('a socket that is not private is not used: Harness\'s key reaches nothing, and the port is not tried', async () => {
const hold = await holder()
vi.stubEnv('HARNESS_CONNECTIONS_PORT', String(hold.port))
closers.push(() => vi.unstubAllEnvs())
const listening = await onSocket()
const bridge = connectionsBridge(() => bridgeRoute(vault))
expect(await bridge.connections()).toEqual([])
chmodSync(listening.path, 0o666)
await expect(bridge.connections()).rejects.toThrow()
chmodSync(listening.path, 0o600)
// Reading Harness's key tightens the vault's folder, so the route heals this one by itself; the check still says so while it is open.
chmodSync(vault.root, 0o777)
expect(socketIsPrivate(listening.path)).toBe(false)
chmodSync(vault.root, 0o700)
expect(socketIsPrivate(listening.path)).toBe(true)
expect(hold.heard).toEqual([])
})
it('names a host that resolves nowhere, so the key cannot leave if the address ever reached plain fetch', () => {
expect(new URL(bridgeRoute(vault).base).hostname).toMatch(/\.invalid$/)
})
it('an unreadable Harness key refuses Harness\'s calls, and agents\' MCP calls still work', async () => {
const fake = await service((_url, body) => ({ body: JSON.stringify({ jsonrpc: '2.0', id: (JSON.parse(body) as { id?: number }).id, result: {} }) }))
vault.save('linear', { access_token: 't', source: 'dcr', mcp_entry: { url: `${fake}/mcp`, headers: {} } })
harnessKey(vault)
await onSocket()
writeFileSync(join(vault.root, 'harness-key.json'), 'not json', { mode: 0o600 })
const { fetch: over } = bridgeRoute2()
const answer = await over('http://bridge/local/linear/mcp', { method: 'POST', body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }) })
expect(answer.status).toBe(200)
})
it('a long vault\'s route is its short socket, and only a home too long as well is the port', () => {
const long = new Store(join(home, 'x'.repeat(120)), env)
expect(bridgeSocketPath(long)).toMatch(/\/\.harness\/s\/[0-9a-f]{16}\/bridge\.sock$/)
expect(bridgeRoute(long).base).toMatch(/^http:\/\/connections\.invalid\//)
vi.stubEnv('HOME', `/${'h'.repeat(120)}`)
closers.push(() => vi.unstubAllEnvs())
expect(bridgeSocketPath(long)).toBeNull()
expect(bridgeRoute(long).base).toMatch(/^http:\/\/127\.0\.0\.1:\d+\//)
})
})
describe('a long data folder\'s short socket', () => {
it('is not used when it is not private: nothing is sent to it, and nothing to the port', async () => {
const hold = await holder()
const data = join(home, 'd'.repeat(100))
vi.stubEnv('HOME', home)
closers.push(() => vi.unstubAllEnvs())
const path = unixSocketPath(data, hold.port)!
expect(path).toContain('/.harness/s/')
const heard: string[] = []
const server = createServer((request, response) => { heard.push(String(request.url)); response.writeHead(200).end('{}') })
mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
await new Promise<void>(ready => server.listen(path, ready))
closers.push(() => new Promise(done => { server.closeAllConnections(); server.close(done) }))
const send = daemonFetch(data, hold.port)
chmodSync(path, 0o600)
expect((await send(`http://127.0.0.1:${hold.port}/api/status`)).status).toBe(200)
expect(heard).toHaveLength(1)
chmodSync(path, 0o666)
await expect(send(`http://127.0.0.1:${hold.port}/api/status`)).rejects.toThrow()
expect(heard).toHaveLength(1)
expect(hold.heard).toEqual([])
})
})
describe('a long data folder whose daemon was given another port', () => {
it('follows its record to the short socket, and refuses it when it is not private', async () => {
const hold = await holder()
const data = join(home, 'd'.repeat(100))
mkdirSync(data, { recursive: true, mode: 0o700 })
vi.stubEnv('HOME', home)
closers.push(() => vi.unstubAllEnvs())
// Configured for 1, given the holder's port: the socket is named for the one it was configured with.
writeFileSync(join(data, 'daemon-1.json'), JSON.stringify({ port: hold.port }), { mode: 0o600 })
const path = unixSocketPath(data, 1)!
const heard: string[] = []
const server = createServer((request, response) => { heard.push(String(request.url)); response.writeHead(200).end('{}') })
mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
await new Promise<void>(ready => server.listen(path, ready))
closers.push(() => new Promise(done => { server.closeAllConnections(); server.close(done) }))
chmodSync(path, 0o600)
const send = daemonFetch(data, hold.port)
expect((await send(`http://127.0.0.1:${hold.port}/api/status`)).status).toBe(200)
expect(heard).toHaveLength(1)
chmodSync(path, 0o666)
await expect(send(`http://127.0.0.1:${hold.port}/api/status`)).rejects.toThrow()
expect(heard).toHaveLength(1)
expect(hold.heard).toEqual([])
})
})
describe('the keys that crossed the port', () => {
it('the service takes Harness\'s key on its socket and not on its port, and the agents\' old key on its port for now', async () => {
const agents = bridgeKey(vault), stale = harnessKey(vault)
const free = createServer()
await new Promise<void>(ready => free.listen(0, '127.0.0.1', ready))
const port = (free.address() as AddressInfo).port
await new Promise(done => free.close(done))
startConnectors(fakeCore(), { vault, env, port, offered: async () => ({}), retryMs: 60_000 })
const socket = bridgeRoute(vault)
await vi.waitFor(async () => expect((await socket.fetch(`${socket.base}/connections`)).status).toBe(200))
await vi.waitFor(async () => expect((await fetch(`http://127.0.0.1:${port}/nope/connections`)).status).toBe(404))
expect(harnessKey(vault)).not.toBe(stale)
expect((await fetch(`http://127.0.0.1:${port}/${harnessKey(vault)}/connections`)).status).toBe(404)
expect((await fetch(`http://127.0.0.1:${port}/${stale}/connections`)).status).toBe(404)
// Reached by the key, and nothing is connected under this name.
const answer = await fetch(`http://127.0.0.1:${port}/${agents}/nothing/mcp`, { method: 'POST', body: '{}' })
expect(await answer.text()).toMatch(/not connected/)
expect(typeof vault.file('bridge.json').keyRetiresAt).toBe('number')
})
it('Harness\'s key is replaced once, on the first start that has a socket', () => {
const before = harnessKey(vault)
rotateHarnessKey(vault)
const after = harnessKey(vault)
expect(after).not.toBe(before)
rotateHarnessKey(vault)
expect(harnessKey(vault)).toBe(after)
})
it('the agents\' old key lasts a day from the first start that has a socket, then goes for good', () => {
const key = bridgeKey(vault)
const start = 1_000_000
expect(retireBridgeKey(vault, start)).toBe(key)
expect(retireBridgeKey(vault, start + KEY_GRACE_MS - 1)).toBe(key)
expect(retireBridgeKey(vault, start + KEY_GRACE_MS)).toBe('')
expect(vault.file('bridge.json').key).toBeUndefined()
expect(retireBridgeKey(vault, start + 2 * KEY_GRACE_MS)).toBe('')
})
it('a machine with no key has nothing to retire, and its saved port is kept', () => {
vault.file('bridge.json')
expect(retireBridgeKey(vault, 5)).toBe('')
expect(vault.file('bridge.json').keyRetiresAt).toBeUndefined()
})
})
// Task #2162 (Reed's review of #2605): on Windows Harness's own route went to the port, which the Team account can hold from boot,
// and took its answers. It goes over the bridge's pipe, which proves itself (serveBridgePipe). A socket named as a pipe stands for it.
describe('Harness\'s own route on Windows: the bridge\'s pipe', () => {
const pipePath = (): string => {
mkdirSync(join(home, 'p'), { recursive: true })
return join(home, 'p', `harness-${randomBytes(16).toString('hex')}`)
}
it('list, API and MCP calls all go over the pipe; a holder of the port hears nothing', async () => {
const hold = await holder()
vi.stubEnv('HARNESS_CONNECTIONS_PORT', String(hold.port))
closers.push(() => vi.unstubAllEnvs())
const api = await service((url) => ({ body: JSON.stringify({ url }) }))
const mcp = await service((_url, body) => {
const message = JSON.parse(body) as { id?: number; method: string }
return { body: JSON.stringify({ jsonrpc: '2.0', id: message.id, result: message.method === 'tools/list' ? { tools: [{ name: 'a' }] } : { protocolVersion: '2025-06-18' } }) }
})
vault.save('devin', { access_token: 't', source: 'custom', transport: 'none', api_entry: { origin: api } } as never)
vault.save('fo', { access_token: 't', source: 'dcr', mcp_entry: { url: `${mcp}/mcp`, headers: {} } })
const listening = await serveBridgePipe(vault, pipePath())
closers.push(() => listening.close())
const route = bridgeRoute(vault, 'win32')
expect(route.base).toMatch(/^http:\/\/connections\.invalid\//)
const bridge = connectionsBridge(() => route)
expect((await bridge.connections()).map(c => c.code).sort()).toEqual(['devin', 'fo'])
expect((await bridge.api('devin', 'GET', '/v3/self')).status).toBe(200)
const client = new McpClient(bridge.mcpUrl('fo'), 'Fo', bridge.fetch)
expect((await client.tools()).map(t => t.name)).toEqual(['a'])
expect(hold.heard).toEqual([])
})
it('with no live pipe says Connections is not running, and sends nothing to the port', async () => {
const hold = await holder()
vi.stubEnv('HARNESS_CONNECTIONS_PORT', String(hold.port))
closers.push(() => vi.unstubAllEnvs())
await expect(connectionsBridge(() => bridgeRoute(vault, 'win32')).connections()).rejects.toThrow()
const listening = await serveBridgePipe(vault, pipePath())
await listening.close()
// The record outlives a bridge that stopped; its process must still run for it to be dialled.
writePrivate(bridgePipeRecord(vault), { ...vault.file('bridge-pipe.json'), pid: 2 ** 22 + 1 })
await expect(connectionsBridge(() => bridgeRoute(vault, 'win32')).connections()).rejects.toThrow()
expect(hold.heard).toEqual([])
})
it('takes no answer that does not prove the token: a pipe made under the bridge\'s name lists nothing for Harness', async () => {
const path = pipePath(), heard: string[] = []
const squatter = createServer((request, response) => {
heard.push(request.url ?? '')
response.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ connections: [{ code: 'fake' }] }))
})
await new Promise<void>(ready => squatter.listen(path, ready))
closers.push(() => new Promise(done => { squatter.closeAllConnections(); squatter.close(done) }))
writePrivate(bridgePipeRecord(vault), { pipe: path, pid: process.pid, token: randomBytes(32).toString('hex') })
await expect(connectionsBridge(() => bridgeRoute(vault, 'win32')).connections()).rejects.toThrow()
expect(heard).toHaveLength(1)
})
})