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
/** Backend HTTP and the single writer of machines.json, owned by the gateway. */
import { VERSION } from '../version.js'
import type { GatewayAccount, GatewayMachines, HttpAnswer } from '../core/api.js'
import { MachineListCache } from '../device/machineList.js'
import { AuthSessionError } from '../lib/authSession.js'
import { backendHttpBase, GRID_MINT_TIMEOUT_MS, PROXY_BACKEND_TIMEOUT_MS } from '../lib/controlPlane.js'
import { guestMachineList, withStaleMarker } from '../lib/machineListReply.js'
interface AccountHttpDeps {
tokens: { accessToken(): Promise<string> }
account(): GatewayAccount
computer: { id: string; name: string; hostname: string }
environment: string
dataDir?: string
request?: typeof fetch
base?: () => string
changed?(state: GatewayMachines): void
reachable?(machineIds: string[] | null): void
/** Every machine list the backend answered (its body), and null on a sign-out: the trust group reads which of the
* account's machines are team machines from it (lib/e2ee/machineKinds.ts). */
listed?(body: Record<string, unknown> | null): void
/** The machines the backend's list shows offline, and null when the list is not the backend's: the relay answers
* their selects without a dial (lib/remoteRelay.ts). */
offline?(machineIds: string[] | null): void
log?(line: string): void
}
const failure = (status: number, code: string, message: string): HttpAnswer =>
({ status, body: { success: false, error: { code, message } } })
const timedOut = (error: Error) => error?.name === 'TimeoutError' || error?.name === 'AbortError'
/** A Retry-After header as milliseconds from [now]: delta-seconds or an HTTP date; null when absent or unreadable. */
export function retryAfterMs(header: string | null, now = Date.now()): number | null {
const value = header?.trim()
if (!value) return null
if (/^\d{1,9}$/.test(value)) return Number(value) * 1000
const at = Date.parse(value)
return Number.isFinite(at) ? Math.max(0, at - now) : null
}
export function createAccountHttp(deps: AccountHttpDeps) {
const request = deps.request ?? fetch
const accountFence = () => {
const account = deps.account()
return [account.machineId, account.autonomousEnv, account.signIn?.epoch, account.signIn?.acct]
}
/** `retryAfterMs` comes with a busy or failing answer (429, 5xx) that says when to try again: the usage
* reports' backoff honours it (gateway/productUsage.ts). */
async function backend(method: string, path: string, body?: unknown, timeoutMs = PROXY_BACKEND_TIMEOUT_MS): Promise<HttpAnswer & { retryAfterMs?: number }> {
const owner = accountFence()
let accessToken: string
try { accessToken = await deps.tokens.accessToken() } catch (error) {
const signedOut = error instanceof AuthSessionError && error.code !== 'UNAVAILABLE'
return failure(signedOut ? 401 : 502, signedOut ? 'NOT_SIGNED_IN' : 'AUTH_UNAVAILABLE', error instanceof Error ? error.message : String(error))
}
// Token refresh can overlap sign-out/sign-in. In particular, a queued usage report must not
// be admitted under a different account's sharing choice after that await.
if (accountFence().some((value, index) => value !== owner[index])) {
return failure(409, 'ACCOUNT_CHANGED', 'The account changed. Refresh and try again.')
}
let res: Response
try {
res = await request(`${(deps.base ?? backendHttpBase)()}${path}`, {
method,
// The CLI and its version, as its sockets declare them (lib/declaredClient.ts): the backend's refusal log names the
// sender of a refused command with it (#2675, 615 refusals in 32 minutes nobody could attribute).
headers: { authorization: `Bearer ${accessToken}`, 'x-autonomous-env': deps.account().autonomousEnv ?? deps.environment,
'x-harness-client': `cli/${VERSION}`, ...(body !== undefined ? { 'content-type': 'application/json' } : {}) },
...(body !== undefined ? { body: JSON.stringify(body) } : {}),
signal: AbortSignal.timeout(timeoutMs),
})
} catch (error) {
const e = error as Error & { cause?: { message?: string } }
if (timedOut(e)) return timeout()
// An empty reason is no reason: no parentheses then (Scholes 10-29).
const reason = [e.cause?.message, e.message].map(text => text?.trim()).find(Boolean)
return failure(502, 'BACKEND_UNREACHABLE', `Could not reach the Harness backend${reason ? ` (${reason})` : ''}. Check the connection and try again.`)
}
// The timeout also covers the body: a success that stalls after the headers, or a proxy's HTML page, is not an empty
// success (Diego 10-29). A refusal keeps its status whatever its body does: 401/403 sign out, 426 asks for an update.
let answer: Record<string, unknown> = {}
if (res.body !== null && res.headers?.get?.('content-length') !== '0') {
try { answer = await res.json() as Record<string, unknown> } catch (error) {
if (res.status >= 200 && res.status < 300) {
return timedOut(error as Error) ? timeout()
: failure(502, 'BACKEND_BAD_RESPONSE', `The Harness backend answered ${method} ${path} with an unreadable reply. Try again in a moment.`)
}
}
}
const retry = res.status === 429 || res.status >= 500 ? retryAfterMs(res.headers?.get?.('retry-after') ?? null) : null
return { status: res.status, body: answer, ...(retry !== null ? { retryAfterMs: retry } : {}) }
function timeout(): HttpAnswer {
return failure(504, 'BACKEND_TIMEOUT', `The Harness backend did not answer ${method} ${path} within ${timeoutMs / 1000}s. Try again in a moment.`)
}
}
const cache = new MachineListCache(() => backend('GET', '/api/machines'), () => deps.computer.id,
deps.log ?? console.warn, deps.dataDir, () => deps.account().machineId)
cache.listen((body) => {
const { machines, source } = cache.list()
deps.reachable?.(source !== 'backend' ? null : machines.filter(m => m.state !== 'offline').map(m => m.machineId))
deps.listed?.(source === 'backend' ? body : null)
deps.offline?.(source !== 'backend' ? null : machines.filter(m => m.state === 'offline').map(m => m.machineId))
deps.changed?.({ owner: deps.account().machineId, body, fetchedAt: cache.lastResponse()?.fetchedAt ?? Date.now() })
})
const restored = cache.lastResponse()
if (restored) deps.changed?.({ owner: deps.account().machineId, ...restored })
async function machines(fallback = false): Promise<HttpAnswer> {
const owner = deps.account().machineId
if (!deps.account().machineId) {
const body = guestMachineList(deps.computer.id, deps.computer.name, deps.computer.hostname)
cache.adopt(body)
return { status: 200, body }
}
if (!fallback) return (await cache.refresh()) ?? { status: 502, body: { error: { code: 'BACKEND_UNREACHABLE' } } }
const res = await backend('GET', '/api/machines')
if (owner !== deps.account().machineId) return failure(409, 'ACCOUNT_CHANGED', 'The account changed. Refresh and try again.')
if (res.status === 200) { cache.adopt(res.body); return res }
if (res.status === 401 || res.status === 403) { cache.signedOut(); return res }
const cached = cache.lastResponse()
return cached ? { status: 200, body: withStaleMarker(cached.body, cached.fetchedAt) } : res
}
async function mintGridName(): Promise<string | null> {
const res = await backend('POST', '/api/grid/name', {}, GRID_MINT_TIMEOUT_MS)
if (res.status < 200 || res.status >= 300 || res.body.success === false) {
const error = res.body.error as { message?: string } | undefined
throw new Error(error?.message || `HTTP ${res.status}`)
}
return (res.body.data as { gridName?: string } | undefined)?.gridName ?? null
}
/** Read the list again unless it was read within `maxAgeMs`; a read in flight is shared. The relay asks this for
* the selects it holds on the list's word (lib/remoteRelay.ts). */
async function recheck(maxAgeMs: number): Promise<void> {
if (!deps.account().machineId) return
await cache.refresh({ maxAgeMs })
}
return { backend, machines, mintGridName, recheck }
}