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
/**
* harnessd's services, in processes of their own, kept running by the master beside the core.
*
* A service is a feature the core can run without (search, devices, models, …). In the core's process a
* service's exception is caught (core/serviceHost.ts), but a native crash, a hung event loop or a leak
* would still take the core with it. Out here a service can only take its own process down, and the
* services that share it (`SERVICE_HOSTS`): the master restarts it with backoff, kills it when it stops
* beating (hung) or outgrows its memory budget (leaking), parks it when it keeps crashing, and the core
* answers its services' requests SERVICE_UNAVAILABLE meanwhile.
*
* The same shape as ./supervisor.ts, for many children and fewer promises: a service has no port to
* bind and no update to prove; it beats, or it is restarted. Everything that touches the operating
* system is injected, so every decision here is tested without one.
*/
import { SERVICE_EXIT_RESTART, describeStaged, heartbeatGraceMs, isCoreMessage, isUpdaterMessage, type StagedUpdate } from './protocol.js'
import { describeExit, type CoreHandle } from './supervisor.js'
import { SWARM_ENV, swarmOn } from './swarmSwitch.js'
export interface ServiceSpec {
/** The process's name: what the master logs it as and the process is titled (`harnessd <name>`). */
name: string
/** The services it runs, as `harness __service <a>,<b>` names them, each on its own link to the core. */
services: readonly string[]
/** The V8 heap limit it runs with, MiB; its budget is a share of it. */
heapLimitMiB: number
/** Resident memory past which it is restarted, MiB; 0: off. */
rssLimitMiB: number
/** A process on demand (an experiment's, the devices', the viewers'): not started with the others, only once
* the core asks for one of its services (`want`), and then kept running like any other. */
onDemand?: boolean
/** The core protocol (./protocol.ts) from which a core asks for this process on demand; 3, the experiments',
* when unset. A core that speaks an older one never asks for it, and it is started as that core binds. */
askedSince?: number
}
export interface ServiceSupervisorDeps {
/** Start a process with these extra environment variables, running every service its spec names. */
spawnService(spec: ServiceSpec, env: Record<string, string>): CoreHandle
/** A monotonic clock, in ms. */
now(): number
/** The wall clock, in ms: what the status says things happened at. */
wallClock(): number
setTimer(run: () => void, ms: number): unknown
clearTimer(timer: unknown): void
log(line: string): void
/** The updater staged a CLI build, a terminal host or both on disk (`harnessd:staged`): the core is to hand over. */
staged?(staged: StagedUpdate): void
/** Stop a service with `harnessd:shutdown` rather than SIGTERM: Windows, where Node's `kill` is TerminateProcess
* and the service's own stop never runs (./supervisor.ts `SupervisorDeps.stopByMessage`). */
stopByMessage?: boolean
}
export interface ServiceSupervisorOptions {
/** A service that sends no heartbeat for this long — from its start, too — is hung: killed, restarted. */
heartbeatTimeoutMs: number
/** How long a service gets to stop after SIGTERM before SIGKILL. */
stopGraceMs: number
/** Restart delay: starts here, doubles per crash, caps at `maxBackoffMs`. */
initialBackoffMs: number
maxBackoffMs: number
/** A service that stayed up this long earns the next crash the initial delay again. */
backoffResetMs: number
/** Past this share of its heap limit a service is restarted cleanly, before V8 aborts it. */
heapRestartPercent: number
/** This many crashes inside `parkWindowMs` park the service: reported, and not respawned in a loop. */
parkCrashes: number
parkWindowMs: number
/** A parked service is tried again after this long. */
parkRetryMs: number
}
export const DEFAULT_SERVICE_OPTIONS: ServiceSupervisorOptions = {
heartbeatTimeoutMs: 30_000,
stopGraceMs: 1_500,
initialBackoffMs: 1_000,
maxBackoffMs: 60_000,
backoffResetMs: 60_000,
heapRestartPercent: 75,
parkCrashes: 5,
parkWindowMs: 600_000,
parkRetryMs: 1_800_000,
}
/** `off`: an experiment's process that no one has asked for yet, and so was never started. */
export type ServiceState = 'off' | 'starting' | 'running' | 'restarting' | 'parked' | 'stopping' | 'stopped'
export type ServiceExitReason = 'crashed' | 'hung' | 'memory' | 'stopped' | 'restart'
export interface ServiceStatus {
name: string
state: ServiceState
pid: number | null
restarts: number
lastExit: string | null
lastExitReason: ServiceExitReason | null
/** When the state last changed, wall clock ms. */
since: number
}
const MIB = 1024 * 1024
/** One service's process, restarted for as long as the master runs. */
class Service {
state: ServiceState
private since: number
private child: CoreHandle | null = null
private restarts = 0
private backoff: number
private upAt = 0
private crashes: number[] = []
private lastExit: string | null = null
private lastExitReason: ServiceExitReason | null = null
/** Why the master killed the running process, when it did. */
private killReason: ServiceExitReason | null = null
private ending = false
private heartbeatTimer: unknown = null
private killTimer: unknown = null
private restartTimer: unknown = null
private onStopped: Array<() => void> = []
private refusedStaged = false
constructor(
readonly spec: ServiceSpec,
private readonly deps: ServiceSupervisorDeps,
private readonly options: ServiceSupervisorOptions,
private readonly env: Record<string, string>,
) {
this.backoff = options.initialBackoffMs
this.since = deps.wallClock()
this.state = spec.onDemand ? 'off' : 'starting'
}
status(): ServiceStatus {
return {
name: this.spec.name,
state: this.state,
pid: this.child?.pid ?? null,
restarts: this.restarts,
lastExit: this.lastExit,
lastExitReason: this.lastExitReason,
since: this.since,
}
}
start(): void {
const child = this.deps.spawnService(this.spec, {
...this.env,
HARNESSD_SERVICE: this.spec.name,
HARNESSD_RESTARTS: String(this.restarts),
HARNESSD_WATCHDOG_MS: String(this.options.heartbeatTimeoutMs),
})
this.child = child
this.killReason = null
this.ending = false
this.upAt = this.deps.now()
child.onMessage((message) => { if (this.child === child) this.onMessage(child, message) })
child.onExit((code, signal) => { if (this.child === child) this.onExit(code, signal) })
this.deps.log(`[harnessd] service ${this.spec.name} started (pid ${child.pid ?? '?'})${this.restarts ? ` · restart ${this.restarts}` : ''}`)
this.setState(this.restarts === 0 ? 'starting' : 'restarting')
this.watchHeartbeat(child)
}
/** Start a process on demand the core asked for: once, while it is off. One already started is the
* master's to keep running, parked included. */
want(): void {
if (this.state === 'off') this.start()
}
/** A process on demand stopped with the others and started again with them: off, for whoever needs it next to
* ask. Left stopped, no `want` started it again for the rest of the master's life. */
rest(): void {
if (this.state === 'stopped') this.setState('off')
}
/** SIGTERM, then SIGKILL after the grace; `done` once it is gone. A parked or waiting one is simply stopped. */
stop(done: () => void): void {
if (this.state === 'stopped') { done(); return }
this.onStopped.push(done)
if (this.state === 'stopping') return
this.clearTimer('restartTimer')
if (!this.child) { this.setState('stopped'); this.stopped(); return }
this.setState('stopping')
this.end('SIGTERM')
}
private stopped(): void {
const waiting = this.onStopped
this.onStopped = []
for (const done of waiting) done()
}
private onMessage(child: CoreHandle, message: unknown): void {
if (isUpdaterMessage(message)) {
// It restarts the core: from any other service than the updater, a bug or worse, said once and ignored.
const staged: StagedUpdate = {
...(message.version ? { version: message.version } : {}), ...(message.ptyVersion ? { ptyVersion: message.ptyVersion } : {}),
}
if (this.spec.name !== UPDATER_PROCESS) { if (!this.refusedStaged) this.deps.log(`[harnessd] service ${this.spec.name} said it staged ${describeStaged(staged)}, which only the updater may — ignored`); this.refusedStaged = true; return }
this.deps.log(`[harnessd] service ${this.spec.name} staged ${describeStaged(staged)}`)
this.deps.staged?.(staged)
return
}
if (!isCoreMessage(message) || message.type !== 'harnessd:heartbeat') return
this.watchHeartbeat(child)
if (this.state === 'starting' || this.state === 'restarting') this.setState('running')
if (this.ending) return
const heapBudget = this.spec.heapLimitMiB * MIB * this.options.heapRestartPercent / 100
if (heapBudget && message.heapUsedBytes > heapBudget) {
this.restartForMemory(`its heap is at ${Math.round(message.heapUsedBytes / MIB)} MiB, past ${this.options.heapRestartPercent}% of its ${this.spec.heapLimitMiB} MiB limit`)
} else if (this.spec.rssLimitMiB && message.rssBytes > this.spec.rssLimitMiB * MIB) {
this.restartForMemory(`it is using ${Math.round(message.rssBytes / MIB)} MiB, over its ${this.spec.rssLimitMiB} MiB budget`)
}
}
private restartForMemory(why: string): void {
this.deps.log(`[harnessd] service ${this.spec.name}: ${why} — restarting it`)
this.killReason = 'memory'
this.end('SIGTERM')
}
private onExit(code: number | null, signal: NodeJS.Signals | null): void {
const exit = describeExit(code, signal)
this.clearTimer('heartbeatTimer')
this.clearTimer('killTimer')
this.child = null
this.lastExit = exit
if (this.state === 'stopping') {
this.lastExitReason = 'stopped'
this.deps.log(`[harnessd] service ${this.spec.name} stopped (${exit})`)
this.setState('stopped')
this.stopped()
return
}
if (code === SERVICE_EXIT_RESTART && this.spec.name === UPDATER_PROCESS && !this.killReason) {
// Asked for: the updater, once it has staged a build, so that it next runs as that build (a lean bundle
// that no longer matches cli.js is not used, ./leanServices.ts). Not a crash, and not delayed; from any
// other service, 75 is a crash, or a loop of them would never be parked.
this.lastExitReason = 'restart'
this.restarts++
this.deps.log(`[harnessd] service ${this.spec.name} asked to start again (${exit}) — restarting`)
this.setState('restarting')
this.armTimer('restartTimer', () => { this.restartTimer = null; this.start() }, 0)
return
}
const reason = this.killReason ?? 'crashed'
this.lastExitReason = reason
this.restarts++
const now = this.deps.now()
if (this.upAt && now - this.upAt >= this.options.backoffResetMs) this.backoff = this.options.initialBackoffMs
// A memory restart counts like a crash: a service over budget from the start must not spin.
this.crashes = [...this.crashes.filter((at) => now - at < this.options.parkWindowMs), now]
if (this.crashes.length >= this.options.parkCrashes) {
this.crashes = []
this.backoff = this.options.initialBackoffMs
this.deps.log(`[harnessd] service ${this.spec.name} ended ${this.options.parkCrashes} times in ${Math.round(this.options.parkWindowMs / 60_000)} min (${exit}, ${reason}) — parked; trying again in ${Math.round(this.options.parkRetryMs / 60_000)} min`)
this.setState('parked')
this.armTimer('restartTimer', () => { this.restartTimer = null; this.start() }, this.options.parkRetryMs)
return
}
const delay = this.backoff
this.backoff = Math.min(this.backoff * 2, this.options.maxBackoffMs)
this.deps.log(`[harnessd] service ${this.spec.name} exited (${exit}, ${reason}) — restarting in ${delay} ms`)
this.setState('restarting')
this.armTimer('restartTimer', () => { this.restartTimer = null; this.start() }, delay)
}
private end(signal: NodeJS.Signals): void {
const child = this.child!
this.ending = true
this.clearTimer('heartbeatTimer')
// Called with SIGTERM only: a stop, or a restart for memory.
if (this.deps.stopByMessage) child.send({ type: 'harnessd:shutdown' })
else child.kill(signal)
this.armTimer('killTimer', () => {
this.deps.log(`[harnessd] service ${this.spec.name} outlived its ${this.options.stopGraceMs} ms to stop — killing it`)
child.kill('SIGKILL')
}, this.options.stopGraceMs)
}
/** A silence that runs out gets one beat's time more, in case the master was paused too: see
* `Supervisor.watchHeartbeat`, where a 40 s pause cost the core and an app's message. */
private watchHeartbeat(child: CoreHandle): void {
const timeout = this.options.heartbeatTimeoutMs
const grace = heartbeatGraceMs(timeout)
this.armTimer('heartbeatTimer', () => {
this.armTimer('heartbeatTimer', () => {
this.deps.log(`[harnessd] service ${this.spec.name} sent no heartbeat for ${timeout + grace} ms — it is hung; killing it`)
this.killReason = 'hung'
child.kill('SIGKILL')
}, grace)
}, timeout)
}
private setState(state: ServiceState): void {
this.state = state
this.since = this.deps.wallClock()
}
private armTimer(name: 'heartbeatTimer' | 'killTimer' | 'restartTimer', run: () => void, ms: number): void {
this.clearTimer(name)
this[name] = this.deps.setTimer(run, ms)
}
private clearTimer(name: 'heartbeatTimer' | 'killTimer' | 'restartTimer'): void {
if (this[name] !== null) this.deps.clearTimer(this[name])
this[name] = null
}
}
/** Every enabled service's process, started together and stopped together. */
export class ServiceSupervisor {
private readonly services: Service[]
constructor(
specs: readonly ServiceSpec[],
deps: ServiceSupervisorDeps,
options: ServiceSupervisorOptions = DEFAULT_SERVICE_OPTIONS,
/** What every service is started with: the token that lets the core know it, for one. */
env: Record<string, string> = {},
) {
this.services = specs.map((spec) => new Service(spec, deps, options, env))
}
/** Start every service but those on demand, which wait to be asked for again; none waits on another, or on the
* core. Found end to end (e2e/reexec.e2e.ts): a master whose re-execution was refused stops its services and
* starts them again, and a process on demand stayed stopped, so a core too old to ask never got models. */
start(): void {
for (const service of this.services) {
if (!service.spec.onDemand) service.start()
else service.rest()
}
}
/** Start the process on demand that hosts [service], if it is not running yet: the core asked for it (`harnessd:want`). */
want(service: string): void {
for (const each of this.services) if (each.spec.services.includes(service)) each.want()
}
/**
* A core bound that speaks [protocol], older than this master's: every process that became on demand after it
* starts now, since that core never asks for one and ran it as it ran every other service. A core from before
* `want` (2) asks for none; one from before the devices were on demand (3) never asks for theirs, and one from
* before the viewers were (4) never for theirs.
*/
unasked(protocol: number): void {
for (const each of this.services) if (each.spec.onDemand && (each.spec.askedSince ?? 3) > protocol) each.want()
}
/** Stop every service; `done` once all are gone. */
stop(done: () => void): void {
let left = this.services.length
if (!left) { done(); return }
for (const service of this.services) service.stop(() => { if (--left === 0) done() })
}
status(): ServiceStatus[] {
return this.services.map((service) => service.status())
}
}
/** A process the services run in: the services it hosts, and its memory budget. */
export type ServiceHostSpec = Omit<ServiceSpec, 'name'>
/**
* The processes this build runs its services in, with their memory budgets: every one, unless
* `HARNESSD_SERVICES` names a subset (`search,viewers`) or `none` (see `serviceSpecs`). A service that
* is not out here runs inside the core's process, behind the service host's guard, as before.
*
* A process per risk, not per feature (docs/design/2026-10-06-core-boundary-next.md, "The target
* shape"): native code (search's `node:sqlite`), memory and child-process herds (the viewers' servers)
* each get their own, so one feature cannot take another down. The light services are pure JavaScript
* answering requests, and share one: a fault in one can cost the others in the edge host, never the
* core, and the master restarts the host. Each is one process of about 60 MiB at idle; apart, they
* would cost that four times.
*/
export const SERVICE_HOSTS: Readonly<Record<string, ServiceHostSpec>> = {
// Engine workers have no older-core startup obligation: old cores run these facets inline and never ask.
// Each holds at most four reads, a 128-entry pager and replies capped at 4 MiB. The heap limit
// contains transient parsing; RSS additionally bounds file buffers outside V8's heap.
'engine-claude': { services: ['engine-claude'], heapLimitMiB: 512, rssLimitMiB: 1_024, onDemand: true, askedSince: 0 },
'engine-codex': { services: ['engine-codex'], heapLimitMiB: 512, rssLimitMiB: 1_024, onDemand: true, askedSince: 0 },
search: { services: ['search'], heapLimitMiB: 1_024, rssLimitMiB: 2_048 },
// Its file watches on every harness's workspace; the viewer servers it starts are processes of their
// own, outside this budget. The Store beside them: its installs run git and the harnesses' toolchains
// in their own processes too, and take minutes, which is what it must not spend in the core.
// Started only once something needs it (core/viewersWake.ts): a harness here, a Store or viewer request, or
// the release's own harnesses to put in place. It idled at about 96 MiB on every computer, and few harnesses
// have a viewer: 1 of 14 on one real machine, 2 of 35 on another (2026-10-12).
viewers: { services: ['viewers', 'store'], heapLimitMiB: 512, rssLimitMiB: 1_024, onDemand: true, askedSince: 5 },
// The git work (workspaces, the project readers) runs in git's own processes, and the monitor's
// samples in ps's and ioreg's; what it holds is the agents the core sent it and one parsed sample.
// The monitor parses up to 8 MB of ioreg output per Monitor poll on a Mac with a GPU, hence more
// than workspaces alone had. The recaps hold each session's last three recaps, answers (8 KiB each at
// most) and asks, as the core did while they ran in it, and a few timers per open turn. The window
// names hold at most 400 short names; their model runs in its own process (lib/oneshot.ts). The agent cleanup
// holds the harnesses the person joined (a thousand ids at most) and looks at the live ones once a minute.
// Agent Messages (services/messagesProcess.ts) holds its mailbox, the last 2,000 messages of each tab and the
// account's tabs, and runs no timer while it is off here or this computer is signed out. It had a process of its
// own as an experiment, 62 MiB resident at idle on every computer it was on, nearly all of it a second Node and
// the bundle rather than messaging: here it costs the edge host about 1 MiB on, and 0.4 MiB off
// (e2e/footprint.e2e.ts, 2026-10-12). The Harness OS computer's management (services/osDevice.ts) holds one
// timestamp and runs its commands bounded, or detached when they must outlive this process.
edge: { services: ['workspaces', 'usage', 'monitor', 'projects', 'handoff', 'recaps', 'windowNames', 'shell', 'connectors', 'sharedMachines', 'agentCleanup', 'messages', 'osDevice'], heapLimitMiB: 384, rssLimitMiB: 768 },
// The orchestrator (services/orchestratorProcess.ts), an experiment: started only once it is on, for a
// saved project or a request (core/api.ts `EXPERIMENTS`). Its projects' files and the frames of their
// Directors; the agents it runs are the core's.
orchestrator: { services: ['orchestrator'], heapLimitMiB: 256, rssLimitMiB: 512, onDemand: true },
// Memories (services/memoryProcess.ts), an experiment: started at its first request, another machine's
// Memories pane asking. It runs the Memories package's own command: writes one at a time, snapshots
// asked together as one read, each answer at most 8 MB.
memory: { services: ['memory'], heapLimitMiB: 128, rssLimitMiB: 384, onDemand: true },
// The router (services/routerProcess.ts), an experiment: started at its first request. A few decisions in
// flight, each one bounded Jev answer.
router: { services: ['router'], heapLimitMiB: 128, rssLimitMiB: 384, onDemand: true },
superTabs: { services: ['superTabs'], heapLimitMiB: 128, rssLimitMiB: 384, onDemand: true },
// Cloud agents (services/cloudProcess.ts), an experiment: started once one is on, for a saved harness or a
// request. A timer and a bounded look per working harness, and each conversation read a file at a time.
cloud: { services: ['cloud'], heapLimitMiB: 128, rssLimitMiB: 384, onDemand: true },
// Share, an experiment (services/sharingProcess.ts): its invitations, its observers' sessions and their
// ciphers; the headless Chrome it captures a shared viewer in is a process of its own, outside this budget.
sharing: { services: ['sharing'], heapLimitMiB: 256, rssLimitMiB: 512, onDemand: true },
// The relay and its E2EE (gateway/gatewayProcess.ts): the backend link, every remote client's session,
// the terminals' WebRTC channels and their queues. Network, crypto and pure-JS WebRTC, the attack surface,
// where a fault costs the remote clients and nothing else (docs/design/2026-10-06-core-boundary-next.md).
// Started as the core starts when it is signed in or anything is paired here, and otherwise by the first
// thing that needs it (core/gatewayWake.ts): about 75 MiB at idle a computer signed out with nothing
// paired never pays.
gateway: { services: ['gateway'], heapLimitMiB: 512, rssLimitMiB: 1_024, onDemand: true, askedSince: 4 },
// Grid's pictures, the Model Manager's catalog and the models found on this machine. Its downloads, model
// servers and `grid` commands run in processes of their own, outside this budget. Started only once grid is
// in use here or a request needs it (core/modelsWake.ts): about 70 MiB at idle, which a computer that uses
// no grid never pays.
models: { services: ['models'], heapLimitMiB: 512, rssLimitMiB: 1_024, onDemand: true, askedSince: 4 },
// The devices (services/devicesProcess.ts): the dials on USB (pure-JS serial, a frame decoder whose buffer
// is bounded per dial), the window bridges, the fleet's router and its lane, the voice router's engine
// worker (a process of its own, outside this budget). Hardware that speaks whatever its firmware says:
// what it costs, it costs here, never a session. The Wi-Fi device beside them (services/wifiProcess.ts),
// on a link of its own: its receipts, its streams and its Store preparations. Started only once there is
// a device, or a request for one (core/devicesWake.ts): about 72 MiB at idle, which a computer with none
// never pays.
devices: { services: ['devices', 'wifi', 'machineAddons'], heapLimitMiB: 256, rssLimitMiB: 512, onDemand: true, askedSince: 4 },
}
/** Every service this build can run outside the core's process: what `HARNESSD_SERVICES` names. */
export const KNOWN_SERVICES: readonly string[] = Object.values(SERVICE_HOSTS).flatMap((host) => host.services)
/**
* The updater's process (services/updaterProcess.ts): checks for a newer build of the CLI and of hn, and
* downloads, verifies, canaries and stages it, then tells the master, which has the core hand over. Its own
* process and never the core's: the core never downloads a build, and a core that cannot start (safe mode)
* or a host whose services keep crashing must not stop the fix from arriving. Not one of `SERVICE_HOSTS`:
* the core neither routes to it nor runs it, and `HARNESSD_SERVICES` does not turn it off; the master runs
* it when it runs the installed copy with updates on (masterProcess.ts). It holds one download at a time.
*/
export const UPDATER_HOST: ServiceHostSpec = { services: ['updater'], heapLimitMiB: 256, rssLimitMiB: 512 }
export const UPDATER_PROCESS = 'updater' // the name the master runs it under: the one whose staged build counts
/** Service timings from the environment (for tests and support); anything unset or invalid keeps its default. */
export function serviceOptions(env: NodeJS.ProcessEnv): ServiceSupervisorOptions {
const read = (name: string, fallback: number, min: number): number => {
const value = Number(env[name])
return env[name] !== undefined && Number.isFinite(value) && value >= min ? value : fallback
}
const d = DEFAULT_SERVICE_OPTIONS
return {
// A second at least: below that a GC pause reads as a hang.
heartbeatTimeoutMs: read('HARNESSD_SERVICE_HEARTBEAT_TIMEOUT_MS', d.heartbeatTimeoutMs, 1_000),
stopGraceMs: read('HARNESSD_SERVICE_STOP_GRACE_MS', d.stopGraceMs, 1),
initialBackoffMs: read('HARNESSD_SERVICE_INITIAL_BACKOFF_MS', d.initialBackoffMs, 0),
maxBackoffMs: read('HARNESSD_SERVICE_MAX_BACKOFF_MS', d.maxBackoffMs, 0),
backoffResetMs: read('HARNESSD_SERVICE_BACKOFF_RESET_MS', d.backoffResetMs, 0),
heapRestartPercent: Math.min(100, read('HARNESSD_SERVICE_HEAP_RESTART_PERCENT', d.heapRestartPercent, 1)),
parkCrashes: read('HARNESSD_SERVICE_PARK_CRASHES', d.parkCrashes, 1),
parkWindowMs: read('HARNESSD_SERVICE_PARK_WINDOW_MS', d.parkWindowMs, 0),
parkRetryMs: read('HARNESSD_SERVICE_PARK_RETRY_MS', d.parkRetryMs, 0),
}
}
/** How a master tells the core it starts which services it runs in their own processes. */
export const SERVICE_PROCESSES_ENV = 'HARNESSD_SERVICE_PROCESSES'
/** Version of the live engine methods hosted by this master, independent of reader-only hosts. */
export const ENGINE_LIVE_ENV = 'HARNESSD_ENGINE_LIVE'
/** Runtime profile methods, negotiated independently from live transcript parsing. */
export const ENGINE_RUNTIME_ENV = 'HARNESSD_ENGINE_RUNTIME'
export const ENGINE_SCREEN_ENV = 'HARNESSD_ENGINE_SCREEN'
export const ENGINE_MODEL_CONTROL_ENV = 'HARNESSD_ENGINE_MODEL_CONTROL'
export const ENGINE_QUESTION_CONTROL_ENV = 'HARNESSD_ENGINE_QUESTION_CONTROL'
export const ENGINE_SUBMISSION_ENV = 'HARNESSD_ENGINE_SUBMISSION'
export const ENGINE_NATIVE_CONTROL_ENV = 'HARNESSD_ENGINE_NATIVE_CONTROL'
/**
* What a master puts in its core's environment about the services it runs in their own processes: the
* list, and `HARNESSD_SERVICES` set to the same (`none` for none), so that a core from before the list,
* one this master finds back on disk after a rollback, reads the same answer for the services it knows
* and runs none of them a second time.
*/
export function serviceProcessesEnv(specs: readonly ServiceSpec[], masterPid: number): Record<string, string> {
// The services, not the processes: a core knows what it routes by service, and one from before the
// edge host still finds the services it knows here (workspaces) and runs the rest itself.
const names = specs.flatMap((spec) => spec.services).join(',')
return { [SERVICE_PROCESSES_ENV]: names, HARNESSD_SERVICES: names || 'none', [ENGINE_LIVE_ENV]: `${masterPid}:1`, [ENGINE_RUNTIME_ENV]: `${masterPid}:1`, [ENGINE_SCREEN_ENV]: `${masterPid}:1`, [ENGINE_MODEL_CONTROL_ENV]: `${masterPid}:1`, [ENGINE_QUESTION_CONTROL_ENV]: `${masterPid}:1`, [ENGINE_SUBMISSION_ENV]: `${masterPid}:1`, [ENGINE_NATIVE_CONTROL_ENV]: `${masterPid}:1` }
}
/** An older master may inherit a newer master's environment after rollback. Trust only this parent. */
export function masterRunsLiveEngines(env: NodeJS.ProcessEnv, parentPid: number): boolean {
return env.HARNESSD_SUPERVISED === '1' && !!env.HARNESSD_SERVICE_TOKEN
&& env[ENGINE_LIVE_ENV] === `${parentPid}:1`
}
export function masterRunsEngineRuntime(env: NodeJS.ProcessEnv, parentPid: number): boolean {
return env.HARNESSD_SUPERVISED === '1' && !!env.HARNESSD_SERVICE_TOKEN
&& env[ENGINE_RUNTIME_ENV] === `${parentPid}:1`
}
/**
* The services the core's master runs in their own processes, which the core routes to and does not
* run itself: what the master says it runs (`serviceProcessesEnv`), never what this build would choose.
* A master too old to say runs exactly the services `HARNESSD_SERVICES` names, as every master did; a
* core that worked it out from its own default instead took every service for out of process under a
* released master that ran none, and answered search, the viewers, workspaces and the experiments
* SERVICE_UNAVAILABLE until the master restarted (e2e/releaseRehearsal.e2e.ts). None without a master.
*/
export function servicesTheMasterRuns(env: NodeJS.ProcessEnv, known: readonly string[]): Set<string> {
if (env.HARNESSD_SUPERVISED !== '1' || !env.HARNESSD_SERVICE_TOKEN) return new Set()
const said = env[SERVICE_PROCESSES_ENV] ?? env.HARNESSD_SERVICES ?? ''
return new Set(said.split(',').map((name) => name.trim()).filter((name) => known.includes(name)))
}
/** The Swarm switch (harnessd/swarmSwitch.ts): off, the Swarm's service is left out of every process the master starts. */
export { SWARM_ENV, swarmOn }
const SWARM_SERVICES: ReadonlySet<string> = new Set(['superTabs'])
/** The services of `known` that run on this computer, wherever they run: all of them, but the Swarm's while it is off. */
export function servicesOn(env: NodeJS.ProcessEnv, known: readonly string[]): string[] {
return swarmOn(env) ? [...known] : known.filter((name) => !SWARM_SERVICES.has(name))
}
/**
* The processes to run the services in: every service this build knows, unless `HARNESSD_SERVICES`
* names a subset, by service (`search,workspaces`) or by process (`edge`, every service it hosts); `none`
* (or empty) runs them all inside the core's process, for debugging or a quick way back. Isolation is
* the point of the split (one service failing costs only its process), so it is the default, not an
* opt-in. Each process hosts the services named of its own, and is not started for none. A process
* named as one of its services is named whole: `viewers` runs the viewers' process, the Store beside
* them, as it ran the viewers' before the Store joined it. `HARNESSD_SERVICE_HEAP_LIMIT_MIB` gives every
* one the same heap limit instead (tests, support). A process on demand (`onDemand`: an experiment's, the
* devices', the viewers') waits for the core to ask for it; named in `HARNESSD_SERVICES`, it starts with the others.
*/
export function serviceSpecs(env: NodeJS.ProcessEnv, hosts: Readonly<Record<string, ServiceHostSpec>>): ServiceSpec[] {
const named = env.HARNESSD_SERVICES === undefined ? null
: new Set(env.HARNESSD_SERVICES.split(',').map((name) => name.trim()).filter((name) => name && name !== 'none'))
const heap = Number(env.HARNESSD_SERVICE_HEAP_LIMIT_MIB)
const on = new Set(servicesOn(env, Object.values(hosts).flatMap((host) => host.services)))
return Object.entries(hosts).flatMap(([name, host]) => {
const services = host.services.filter((service) => on.has(service) && (!named || named.has(service) || named.has(name)))
// A process on demand named outright runs from the start, as every service named does (a test, support).
const onDemand = host.onDemand && !named ? { onDemand: true } : {}
const { onDemand: _given, ...rest } = host
return services.length ? [{ name, ...rest, services, ...onDemand, ...(Number.isInteger(heap) && heap > 0 ? { heapLimitMiB: heap } : {}) }] : []
})
}
export function masterRunsEngineScreen(env: NodeJS.ProcessEnv, parentPid: number): boolean {
return masterRunsLiveEngines(env, parentPid) && env[ENGINE_SCREEN_ENV] === `${parentPid}:1`
}
/** A new core must not route controls through an older worker host. */
export function masterRunsEngineModelControl(env: NodeJS.ProcessEnv, parentPid: number): boolean {
return masterRunsLiveEngines(env, parentPid) && env[ENGINE_MODEL_CONTROL_ENV] === `${parentPid}:1`
}
export function masterRunsEngineQuestionControl(env: NodeJS.ProcessEnv, parentPid: number): boolean {
return masterRunsLiveEngines(env, parentPid) && env[ENGINE_QUESTION_CONTROL_ENV] === `${parentPid}:1`
}
/** A new core must not ask an older worker host for submission readings it does not serve. */
export function masterRunsEngineSubmission(env: NodeJS.ProcessEnv, parentPid: number): boolean {
return masterRunsLiveEngines(env, parentPid) && env[ENGINE_SUBMISSION_ENV] === `${parentPid}:1`
}
/** A new core must not send an older worker host a stop its Codex worker cannot speak. */
export function masterRunsEngineNativeControl(env: NodeJS.ProcessEnv, parentPid: number): boolean {
return masterRunsLiveEngines(env, parentPid) && env[ENGINE_NATIVE_CONTROL_ENV] === `${parentPid}:1`
}