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
/**
* The hosts of one home: the target's makes new panes, and every other drains.
*
* Each host build is its own instance (`p<protocol>-<version>`, or `p<protocol>` for a host from before that,
* instance.ts): its own discovery file, endpoint, lock and pane ids. The target is the build this daemon would start
* (launch.ts `targetHost`, read once as the core starts). An update leaves the previous build's host running with the
* person's panes in it, as a tmux server of an older tmux keeps running. This daemon reaches it too, as a drain
* backend (ptyHostBackend.ts): its panes are listed, streamed and controlled, their registry rows keep their
* `ptyhost:<instance>` runtimes, and the route keys name the instance, so every host's panes are reached at once.
* Nothing new goes to it. Once it has no pane on two reconcile passes in a row it is shut down (protocol 2 on, and only
* when `mayShutDown`: never a host newer than a dev build's target, nor any with no target; an older protocol's host,
* which has no `shutdown`, is left running idle, ptyHostBackend.ts `shutdownHost`), and the backend leaves the daemon's
* backends (`TerminalBackendCoordinator.replaceBackends`). A drain host proven to have exited (the process table) is
* gone, its panes with it: its inventory is then empty for certain, so the reconciler counts its rows' runtimes
* missing, and the backend leaves once no row names its instance. Then the runtime's host binaries no running host
* uses are deleted (launch.ts `removeUnusedPtyVersions`, which keeps every folder newer than `current-pty`). No drain
* host is shut down while the create backend has no host of its own (`createAvailable`): it may be the only one left.
*
* While a host is on probation (`ptyHostOnProbation`), the core is ready only once the create backend is attached to it
* (`untilHostAttached`): the master's probation judges the core's ready, and so the host's.
*/
import { existsSync } from 'node:fs'
import path from 'node:path'
import type { TerminalBackend } from '../terminalBackend.js'
import { terminalInstanceId } from '../terminalRuntime.js'
import type { TerminalRuntimeRef } from '../terminalTypes.js'
import { PtyHostBackend, type PtyHostBackendOptions } from '../ptyHostBackend.js'
import { instanceProtocol } from './instance.js'
import { listDiscoveries, type PtyHostTarget } from './launch.js'
import { SUPPORTED_PTY_PROTOCOLS } from './protocol.js'
/** How many reconcile passes in a row must find a drain host with no pane before it is shut down. */
export const EMPTY_PASSES = 2
export interface PtyHostBackends {
/** The target's host: new panes go there, and it is started when there is none. */
create: PtyHostBackend
/** Every other host's, oldest first, then those only registry rows name. */
drain: PtyHostBackend[]
}
export interface PtyHostBackendsOptions extends Omit<PtyHostBackendOptions, 'home' | 'instance' | 'target'> {
/** The daemon's target host (`targetHost`); null when it cannot be known. */
target?: PtyHostTarget | null
/**
* The `ptyhost:<instance>` instances registry rows name (`rowInstancesOf`): a drain backend is made for one with no
* discovery file too, so those rows go gone rather than stay on no backend.
*/
rowInstances?: () => string[]
}
const PTYHOST = 'ptyhost:'
/** Whether [instance] is a host instance of a protocol this daemon speaks. */
function supported(instance: string): boolean {
const protocol = instanceProtocol(instance)
return protocol !== null && SUPPORTED_PTY_PROTOCOLS.includes(protocol)
}
/**
* One backend per host instance of [home]: the create backend for the target, and a drain backend for each other
* instance of a supported protocol that has a discovery file, or rows still on it. With no target, every discovered
* host is a drain backend's, including the one the create backend will take (`withoutCreateHost` drops that one once
* they are prepared).
*/
export function ptyHostBackends(home: string, options: PtyHostBackendsOptions = {}): PtyHostBackends {
const { target = null, rowInstances, ...backendOptions } = options
const discovered = listDiscoveries(home).map((discovery) => discovery.instance)
const named = (rowInstances?.() ?? []).flatMap((id) => id.startsWith(PTYHOST) ? [id.slice(PTYHOST.length)] : [])
// By instance, never by version: a folder `current-pty` names may hold a binary stamped otherwise, and the instance
// is the name its host publishes (launch.ts `targetHost`).
const instances = [...new Set([...discovered, ...named])].filter((instance) => supported(instance) && instance !== target?.instance)
const drain = instances.map((instance) => new PtyHostBackend({ ...backendOptions, home, instance, target }))
return { create: new PtyHostBackend({ ...backendOptions, home, target }), drain }
}
/** The `ptyhost:<instance>` instances [rows] have runtimes on, once each. */
export function rowInstancesOf(rows: ReadonlyArray<{ runtimes: readonly TerminalRuntimeRef[] }>): string[] {
const instances = rows.flatMap((row) => row.runtimes.filter((runtime) => runtime.backend === 'ptyhost').map(terminalInstanceId))
return [...new Set(instances)]
}
/**
* [backends] without a drain backend on the host [create] reached, which is disposed (its connection only). Only with
* no target can there be one: the create backend then took whichever host of `PTY_PROTOCOL` answered, which was a
* drain backend's too. Two backends of one instance would list its panes twice, and the coordinator would route them to
* the later one.
*/
export function withoutCreateHost(backends: readonly TerminalBackend[], create: PtyHostBackend): TerminalBackend[] {
return backends.filter((backend) => {
if (!isDrainBackend(backend) || backend.instanceId !== create.instanceId) return true
backend.dispose()
return false
})
}
/** Whether [backend] is a drain backend: never the one new panes are made on (main.ts `createBackend`). */
export function isDrainBackend(backend: TerminalBackend): backend is PtyHostBackend {
return backend instanceof PtyHostBackend && backend.draining
}
/** Whether any of [rows] has a runtime on [instanceId]. */
export function rowsOnInstance(rows: ReadonlyArray<{ runtimes: readonly TerminalRuntimeRef[] }>, instanceId: string): boolean {
return rows.some((row) => row.runtimes.some((runtime) => terminalInstanceId(runtime) === instanceId))
}
export interface PtyHostDrainDeps {
/** The drain backends that are among [backends]. */
drain: readonly PtyHostBackend[]
/** The daemon's ready backends: the very list the reconciler and the probe read, a drained one taken out of it. */
backends: TerminalBackend[]
coordinator: { replaceBackends(backends: readonly TerminalBackend[]): void }
/** Whether a registry row still has a runtime on [instanceId] (`rowsOnInstance`). */
inUse: (instanceId: string) => boolean
/** After a drained host has gone and its backend left: `removeUnusedPtyVersions`. */
cleanup?: () => void
/** Whether the create backend is attached to its host. While it is not, no drain host is shut down: new panes have
* nowhere else to go, and a probation that rolls the target back needs a host to come back to. Left out, always. */
createAvailable?: () => boolean
}
/** The drain, one `step` after each reconcile pass (main.ts `onReconciled`). */
export class PtyHostDrain {
private readonly deps: PtyHostDrainDeps
private readonly draining: PtyHostBackend[]
private readonly empty = new Map<PtyHostBackend, number>()
private stepping = false
constructor(deps: PtyHostDrainDeps) {
this.deps = deps
this.draining = [...deps.drain]
}
/** The drain backends not yet removed. */
get pending(): readonly PtyHostBackend[] {
return this.draining
}
/**
* One pass's look at each drain host. An empty one (no pane of any owner) on `EMPTY_PASSES` passes in a row is
* shut down; a host that refuses (a pane came meanwhile) starts the count again. One of a protocol without
* `shutdown`, or one it may not shut down (`mayShutDown`), stays running, idle, and only its backend leaves. A backend leaves once no row names its instance: a
* gone host's rows go gone through the reconciler first, which a backend taken out early would strand on no
* backend. A step while one runs is skipped: the count is of passes.
*/
async step(): Promise<void> {
if (this.stepping) return
this.stepping = true
try {
for (const backend of [...this.draining]) await this.look(backend)
} finally {
this.stepping = false
}
}
private async look(backend: PtyHostBackend): Promise<void> {
const state = await backend.drainState().catch(() => 'unknown' as const)
if (state === 'busy' || state === 'unknown') {
this.empty.delete(backend)
return
}
if (state === 'empty' && this.deps.createAvailable && !this.deps.createAvailable()) {
this.empty.delete(backend)
return
}
const passes = (this.empty.get(backend) ?? 0) + 1
this.empty.set(backend, passes)
if (passes < EMPTY_PASSES) return
// A host it may not shut down (`mayShutDown`) stays running, as one without `shutdown` does; its backend leaves
// all the same once no row names it.
if (state === 'empty' && backend.mayShutDown) {
const shutdown = await backend.shutdownHost().catch(() => 'failed' as const)
if (shutdown === 'refused') this.empty.delete(backend)
// `unsupported`: the host stays, never signalled; its backend leaves all the same.
if (shutdown !== 'exited' && shutdown !== 'unsupported') return
}
if (this.deps.inUse(backend.instanceId)) return
this.remove(backend)
}
private remove(backend: PtyHostBackend): void {
this.draining.splice(this.draining.indexOf(backend), 1)
this.empty.delete(backend)
const at = this.deps.backends.indexOf(backend)
if (at >= 0) this.deps.backends.splice(at, 1)
this.deps.coordinator.replaceBackends(this.deps.backends)
backend.dispose()
console.log(`[terminal] ptyhost: ${backend.instanceId} drained and removed (${backend.hostGone ?? 'its host is idle and left running'})`)
try {
this.deps.cleanup?.()
} catch (error) {
console.error(`[terminal] ptyhost: cleanup after the drain failed: ${error instanceof Error ? error.message : String(error)}`)
}
}
/** Drop every drain backend's connection, as the daemon exiting does: the hosts and their panes stay. */
dispose(): void {
for (const backend of this.draining) backend.dispose()
}
}
/** A host is on probation: `<runtime>/pty/pty-pending.json` (lib/windows/ptyInstall.ts `PTY_PENDING`) exists. */
export function ptyHostOnProbation(runtimeDir: string): boolean {
return existsSync(path.join(runtimeDir, 'pty', 'pty-pending.json'))
}
/**
* Wait until [attached] (the create backend reached the target's host, [instance]; null when there is no target), polled
* every [pollMs]: how a core whose host is on probation holds back its ready (core/main.ts). The master judges the host
* by that ready, and a version that says it runs proves nothing about serving. One that never attaches keeps the core
* not ready for good: the master's ready timeout ends it, and its probation rolls the host back. Said once, if it waits.
*/
export async function untilHostAttached(attached: () => boolean, instance: string | null, log: (line: string) => void, pollMs = 250): Promise<void> {
if (attached()) return
const host = instance ?? 'no target'
log(`[terminal] ptyhost: the host on probation (${host}) is not attached — not ready until it is; the master rolls it back if it never is`)
while (!attached()) await new Promise((resolve) => setTimeout(resolve, pollMs))
log(`[terminal] ptyhost: the host on probation (${host}) is attached`)
}