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
/**
* Hosting services in the core's process so that a failing one cannot take the core down with it
* (docs/design/2026-10-03-harnessd.md, the core boundary). In process, a service shares the core's
* heap and event loop; this is the isolation a function boundary can give, and a service moved out
* of process gets the rest.
*
* - **Start.** A service whose start throws is left off: its port stays null, it is logged, and the
* core starts without it.
* - **Calls.** Every call into a port is guarded. One that throws, or whose promise rejects, is logged
* and answered with that member's fallback, so the core's caller (the event funnel, restore, a
* frame being built) carries on. A member whose fallback is `FAIL` answers a request: its failure
* goes back to that one request, which the socket answers with an error.
* - **Requests.** A service answers the apps through the requests it declares when it is started;
* its start returns their handlers, and the socket asks `route` before its own switch, so a feature
* adds a request without touching the socket. While the service is off they are answered
* `SERVICE_UNAVAILABLE`, never `UNSUPPORTED`, which the apps read as "update the CLI": that is why
* the types are declared before the start that could fail. A handler that throws or rejects is
* answered `SERVICE_FAILED`, and counts as a failure of the service like a call into its port.
* - **Switching off.** A service that fails `maxFailures` times within `windowMs` is switched off
* for the rest of the daemon's life: it is stopped when its port can stop, its port goes null, the
* core's calls answer their fallbacks without reaching it, its requests are answered unavailable,
* and the `onOff` handlers unbind what clients reach it through. A restart of the daemon starts it
* again.
*/
import type { Asker, CoreApi, CorePorts, ServiceRequest, ServiceRequests } from './api.js'
/** The fallback of a member whose failure belongs to its caller: it throws (or rejects). */
export const FAIL = Symbol('fail')
const LATER = Symbol('later')
/** The fallback of a member that returns a promise: resolve to `value` (or reject, for `FAIL`). */
export interface Later<T> { readonly [LATER]: T }
export function later<T>(value: T): Later<T> {
return { [LATER]: value }
}
/** A fallback read: whether its member returns a promise (`later`), and what it answers. A service that
* guards parts of its own the way this host guards services reads its fallbacks with this
* (services/devicesGuard.ts). */
export function readFallback(fallback: unknown): { deferred: boolean; value: unknown } {
const deferred = typeof fallback === 'object' && fallback !== null && LATER in fallback
return { deferred, value: deferred ? (fallback as Later<unknown>)[LATER] : fallback }
}
/** For every member of a port, what the core gets when that member fails or its service is off. */
export type PortFallbacks<P> = {
[K in keyof P]-?: P[K] extends (...args: never[]) => infer R
? R extends PromiseLike<infer T> ? Later<T | typeof FAIL> : R | typeof FAIL
: never
}
/** Why a call into a service was not answered: the service is off, or the call failed. */
export class ServiceUnavailableError extends Error {
constructor(readonly service: string, readonly cause?: unknown) {
super(`the ${service} service is unavailable`)
this.name = 'ServiceUnavailableError'
}
}
export interface ServiceHostOptions {
/** Failures within `windowMs` that switch a service off. */
maxFailures?: number
windowMs?: number
now?: () => number
log?: (line: string) => void
/**
* Faults to inject, for the end-to-end suite only (`HARNESSD_TEST_FAULTS`): `name` makes that
* service's start throw, `name.member` makes that member throw on every call.
*/
faults?: ReadonlySet<string>
}
type PortName = keyof CorePorts
type Port<K extends PortName> = NonNullable<CorePorts[K]>
type Member = (...args: unknown[]) => unknown
const describe = (error: unknown): string => (error instanceof Error ? error.message : String(error))
/** `HARNESSD_TEST_FAULTS`: a comma-separated list of `service` and `service.member` names. */
export function testFaults(value: string | undefined): ReadonlySet<string> {
return new Set((value ?? '').split(',').map((entry) => entry.trim()).filter(Boolean))
}
export function createServiceHost(ports: CorePorts, options: ServiceHostOptions = {}) {
const maxFailures = options.maxFailures ?? 5
const windowMs = options.windowMs ?? 60_000
const now = options.now ?? Date.now
const log = options.log ?? ((line: string) => console.warn(line))
const faults = options.faults ?? new Set<string>()
const off = new Set<string>()
const failures = new Map<string, number[]>()
const offHandlers = new Map<string, Array<() => void>>()
const stoppers = new Map<string, () => void>()
/** The service that answers each request type, and its handler once it has started. */
const owners = new Map<string, { service: string; answer: ServiceRequest | null }>()
/** The requests still being answered, each with the connection that asked: what its closing aborts. */
const answering = new Map<AbortController, string | undefined>()
const inject = (target: string): void => {
if (faults.has(target)) throw new Error(`injected fault: ${target}`)
}
const switchOff = (name: string, failed: number): void => {
if (off.has(name)) return
off.add(name)
if (Object.hasOwn(ports, name)) ports[name as PortName] = null
log(`[services] ${name} switched off after ${failed} failures in ${Math.round(windowMs / 1000)}s · it stays off until the daemon restarts`)
for (const handler of [stoppers.get(name), ...offHandlers.get(name) ?? []]) {
try { handler?.() } catch (error) { log(`[services] switching ${name} off: ${describe(error)}`) }
}
}
const failed = (name: string, member: string, error: unknown): void => {
log(`[services] ${name}.${member} failed · ${describe(error)}`)
const at = now()
const recent = (failures.get(name) ?? []).filter((t) => at - t < windowMs)
recent.push(at)
failures.set(name, recent)
if (recent.length >= maxFailures) switchOff(name, recent.length)
}
const guard = <K extends PortName>(name: K, port: Port<K>, fallbacks: PortFallbacks<Port<K>>): Port<K> => {
const guarded: Record<string, Member> = {}
for (const [member, fallback] of Object.entries(fallbacks) as Array<[string, unknown]>) {
const { deferred, value } = readFallback(fallback)
const answer = (cause?: unknown): unknown => {
if (value === FAIL) {
const error = new ServiceUnavailableError(name, cause)
if (deferred) return Promise.reject(error)
throw error
}
return deferred ? Promise.resolve(value) : value
}
guarded[member] = (...args: unknown[]): unknown => {
if (off.has(name)) return answer()
let result: unknown
try {
inject(`${name}.${member}`)
result = ((port as unknown as Record<string, Member>)[member]).apply(port, args)
} catch (error) {
failed(name, member, error)
return answer(error)
}
if (!deferred) return result
return Promise.resolve(result).catch((error: unknown) => {
failed(name, member, error)
return answer(error)
})
}
}
return guarded as unknown as Port<K>
}
/** Take the request types a service declares, before its start: a type another service answers is a
* mistake in the code, and leaves this one off rather than taking the other's requests. */
const claim = (name: string, requests: readonly string[]): void => {
for (const type of requests) {
const owner = owners.get(type)
if (owner) throw new Error(`${type} is answered by ${owner.service}`)
}
for (const type of requests) owners.set(type, { service: name, answer: null })
}
/** Install a started service's handlers: exactly the types it declared, no more and no fewer. */
const install = (name: string, requests: readonly string[], answers: ServiceRequests | void): void => {
const given = Object.keys(answers ?? {})
const undeclared = given.filter((type) => !requests.includes(type))
const unanswered = requests.filter((type) => !given.includes(type))
if (undeclared.length) throw new Error(`it answers ${undeclared.join(', ')} without declaring ${undeclared.length > 1 ? 'them' : 'it'}`)
if (unanswered.length) throw new Error(`it declares ${unanswered.join(', ')} without answering ${unanswered.length > 1 ? 'them' : 'it'}`)
for (const type of requests) owners.set(type, { service: name, answer: (answers as ServiceRequests)[type] })
}
const didNotStart = (name: string, error: unknown): void => {
off.add(name)
if (Object.hasOwn(ports, name)) ports[name as PortName] = null
log(`[services] ${name} did not start · ${describe(error)} · the core runs without it`)
}
return {
/**
* Start one service. It fills its own port (`ports[name]`) in a staging copy; what it filled is
* installed guarded, and anything else it wrote is ignored. A service that leaves its port null
* has said why itself and is simply off. `requests` are the types it answers for the apps; its
* start returns their handlers.
*/
start<K extends PortName>(
name: K,
start: (core: CoreApi, ports: CorePorts) => ServiceRequests | void,
core: CoreApi,
fallbacks: PortFallbacks<Port<K>>,
requests: readonly string[] = [],
): void {
const staging: CorePorts = { ...ports, [name]: null }
let answers: ServiceRequests | void
try {
claim(name, requests)
inject(name)
answers = start(core, staging)
} catch (error) {
didNotStart(name, error)
return
}
const port = staging[name] as Port<K> | null
if (!port) {
off.add(name)
ports[name] = null
return
}
try {
install(name, requests, answers)
} catch (error) {
didNotStart(name, error)
return
}
const stop = (port as unknown as { stop?: () => unknown }).stop
if (typeof stop === 'function') stoppers.set(name, () => { void Promise.resolve(stop.call(port)).catch(() => {}) })
ports[name] = guard(name, port, fallbacks) as CorePorts[K]
},
/**
* Start a service the core never calls: it has no port, and only answers the apps' `requests`.
* Most features are this.
*/
serve(name: string, start: (core: CoreApi) => ServiceRequests, core: CoreApi, requests: readonly string[]): void {
try {
if (Object.hasOwn(ports, name)) throw new Error('it has a port: start it with start()')
claim(name, requests)
inject(name)
install(name, requests, start(core))
} catch (error) {
didNotStart(name, error)
}
},
/**
* Answer a request a service in this process declared: false when none did, and the socket answers
* it. Never waits in line: the reply goes when the handler's promise settles.
*/
route(type: string, payload: Record<string, unknown>, asker: Asker, reply: (result: Record<string, unknown>) => void): boolean {
const owner = owners.get(type)
if (!owner) return false
const { service, answer } = owner
if (off.has(service) || !answer) {
reply({ error: 'SERVICE_UNAVAILABLE', service, retryable: false })
return true
}
const failedWith = (error: unknown): void => {
failed(service, type, error)
reply({ error: 'SERVICE_FAILED', service })
}
// Aborted when its connection closes (`closeConnection`); a request with none is its own, never closed.
const closed = new AbortController()
answering.set(closed, asker.connection)
const settled = (): void => { answering.delete(closed) }
let result: ReturnType<ServiceRequest>
try {
inject(`${service}.${type}`)
result = answer(payload, asker, closed.signal)
} catch (error) {
settled()
failedWith(error)
return true
}
void Promise.resolve(result).then((value) => {
if (typeof value === 'object' && value !== null) reply(value)
else failedWith(new Error(`${type} was answered with no reply`))
}, failedWith).finally(settled)
return true
},
/** A connection closed: abort what it asked that is still being answered. Its answers go nowhere. */
closeConnection(connection: string): void {
for (const [closed, asked] of answering) if (asked === connection) closed.abort()
},
/**
* Leave a service this computer turned off (harnessd/services.ts `servicesOn`) off: nothing of it is started, its
* port stays empty, and its requests are answered `SERVICE_UNAVAILABLE`, as for one that did not start.
*/
leaveOff(name: string, requests: readonly string[]): void {
claim(name, requests)
off.add(name)
if (Object.hasOwn(ports, name)) ports[name as PortName] = null
log(`[services] ${name} is turned off on this computer`)
},
/** Run `handler` once, when `name` is switched off. */
onOff(name: string, handler: () => void): void {
offHandlers.set(name, [...offHandlers.get(name) ?? [], handler])
},
/** Whether `name` is off: it did not start, or it was switched off. */
isOff(name: string): boolean {
return off.has(name)
},
}
}
export type ServiceHost = ReturnType<typeof createServiceHost>