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 CLI's version folders on Windows (spec section 1, "Layout"; section 3, "Self-update and rollback"): each build
* in `cli\<version>\`, the one in use named by the pointer file `cli\current` (./installLayout.ts), and beside them the
* stable `cli\notify.mjs` the hooks' command lines name. On a Mac an update swaps files in place by rename and keeps
* `.prev` hard links to roll back to. Windows cannot replace a file a running process holds, and has no symlinks
* without Developer Mode, so a build is never touched once written: an update writes a new folder and moves the
* pointer, a rollback moves it back.
*/
import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import type { ProcessRow } from '../processTable.js'
import { CLI_POINTER, STABLE_NOTIFY, writePointer } from './installLayout.js'
import { windowsProcessRows } from './processTable.js'
/** A build's folder name under cli\: its version, as the release names it (`0.5.0`, `0.5.1-dev.ab12`). Semver's
* identifiers, none empty: Windows drops a name's trailing dot, and the pointer refuses `..` (./installLayout.ts). */
export const VERSION_FOLDER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
const CLI = 'cli.js'
const NOTIFY = 'notify.mjs'
const PACKAGE = 'package.json'
const RUNTIME_PACKAGE = `${JSON.stringify({ type: 'module' })}\n`
/** A hook reads notify.mjs for a moment; Defender scans a new file for longer. */
export const REPLACE_TRIES = 5
export const REPLACE_PAUSE_MS = 100
export function isVersionFolder(cliDir: string, version: string): boolean {
return VERSION_FOLDER.test(version) && existsSync(join(cliDir, version, CLI)) && existsSync(join(cliDir, version, NOTIFY))
}
/** Every build on disk, in no order. */
export function versionsOnDisk(cliDir: string): string[] {
try { return readdirSync(cliDir).filter((name) => isVersionFolder(cliDir, name)) } catch { return [] }
}
function sameBytes(file: string, bytes: Buffer): boolean {
try { return readFileSync(file).equals(bytes) } catch { return false }
}
/**
* Write [version]'s folder whole: into a folder beside it, renamed into place, so nothing ever runs half a build. One
* already there with these bytes is kept (a build staged again after a rollback, or by `harness update`); one with
* other bytes is moved aside, never written into, since a process may be running from it (the retirement removes it,
* lib/selfUpdate.ts `retireCliVersions`).
*/
export function writeVersionFolder(cliDir: string, version: string, cliBuf: Buffer, notifyBuf: Buffer): string {
if (!VERSION_FOLDER.test(version)) throw new Error(`not a version a folder can be named after: ${JSON.stringify(version)}`)
const folder = join(cliDir, version)
if (sameBytes(join(folder, CLI), cliBuf) && sameBytes(join(folder, NOTIFY), notifyBuf)) return folder
const temporary = join(cliDir, `.${version}.${process.pid}.tmp`)
try {
mkdirSync(cliDir, { recursive: true })
rmSync(temporary, { recursive: true, force: true })
mkdirSync(temporary)
writeFileSync(join(temporary, PACKAGE), RUNTIME_PACKAGE)
writeFileSync(join(temporary, CLI), cliBuf)
writeFileSync(join(temporary, NOTIFY), notifyBuf)
if (existsSync(folder)) renameSync(folder, join(cliDir, `.${version}.${Date.now()}.old`))
renameSync(temporary, folder)
} catch (error) {
try { rmSync(temporary, { recursive: true, force: true }) } catch { /* not this call's to clear */ }
throw error
}
return folder
}
const pause = (ms: number): void => { if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms) }
/** Replace [file] whole, by a file beside it and a rename, tried again while Windows says it is busy (a hook has it
* open, or an antivirus scan). */
export function replaceFile(
file: string, bytes: Buffer, rename: (from: string, to: string) => void = renameSync, tries = REPLACE_TRIES, pauseMs = REPLACE_PAUSE_MS,
): void {
const temporary = `${file}.${process.pid}.tmp`
try {
writeFileSync(temporary, bytes)
for (let attempt = 1; ; attempt++) {
try {
rename(temporary, file)
return
} catch (error) {
const code = (error as NodeJS.ErrnoException).code
if (attempt >= tries || (code !== 'EBUSY' && code !== 'EPERM' && code !== 'EACCES')) throw error
pause(pauseMs * attempt)
}
}
} catch (error) {
// Also a file the write left half-written (a full disk).
rmSync(temporary, { force: true })
throw error
}
}
/**
* Make [version] the build in use: `cli\current` first (what the next master and core start from), then the stable
* notify.mjs. A notify.mjs a hook keeps busy past the retries is left as it was, and said: the hooks keep reporting
* through the one before, as they do through any notify.mjs, until the next switch.
*/
export function switchTo(cliDir: string, version: string, log: (line: string) => void = (line) => console.error(line)): void {
writePointer(cliDir, CLI_POINTER, version)
try {
replaceFile(join(cliDir, STABLE_NOTIFY), readFileSync(join(cliDir, version, NOTIFY)))
} catch (error) {
log(`[update] the hooks' notify.mjs could not be refreshed yet (${error instanceof Error ? error.message : String(error)}) — they keep the one before until the next update`)
}
}
export interface RetireDeps {
rows(): Promise<readonly ProcessRow[] | null>
remove(path: string): void
log(line: string): void
}
/** This computer's: A's process table, a removal of the whole folder, the daemon log. */
export const processRetireDeps = (): RetireDeps => ({
rows: () => windowsProcessRows(null),
remove: (path) => rmSync(path, { recursive: true, force: true }),
log: (line) => console.log(line),
})
/** A folder a stage is still writing is left alone for this long. */
const STAGING_GRACE_MS = 60 * 60_000
/** A build moved aside by `writeVersionFolder`, and a folder a stage writes before its rename. */
const SET_ASIDE = /^\..+\.old$/
const STAGING = /^\..+\.tmp$/
function isFolder(path: string): boolean {
try { return statSync(path).isDirectory() } catch { return false }
}
/**
* Remove every build but [keep] (or the builds it names when asked, null for none), and the folders a stage set aside (`.old`) or left (`.tmp`, once it is an hour old),
* once no process runs from one: a core or a service of the build before may still be running from its folder, and a
* pane's `harness` command line names one too. Without a process table nothing is removed. A folder Windows will not
* remove yet (a file in it still open) is said and tried again at the next pass; so is what is left of one it removed
* only in part, which is why a build here is any folder named as one, with or without its cli.js.
*/
export async function retireUnused(
cliDir: string, keep: ReadonlySet<string> | (() => ReadonlySet<string> | null), deps: RetireDeps,
): Promise<string[]> {
const kept = typeof keep === 'function' ? keep : () => keep
// A first look: with nothing to retire, no process table to read.
if (!retirable(cliDir, kept()).length) return []
const rows = await deps.rows()
if (!rows) { deps.log('[update] the process table could not be read — the older CLI builds stay for now'); return [] }
// And again after the read, the only wait: a stage meanwhile (this process's own, which the spawn lock lets
// through) may have pointed cli\current at a build the first look would have removed. From here on nothing waits.
const candidates = retirable(cliDir, kept())
// What a process runs from: its image, and every path its command line names (node's own, cli.js, a hook's).
const lines = rows.flatMap((row) => [row.executable, row.imagePath ?? '', row.args, ...(row.nativeArgv ?? [])])
.map((line) => line.toLowerCase().replace(/\//g, '\\'))
const removed: string[] = []
for (const name of candidates) {
// By text: a path spelled as the launcher spelled it matches; one through an 8.3 short name, a junction or subst does not.
const folder = `${join(cliDir, name).toLowerCase().replace(/\//g, '\\')}\\`
if (lines.some((line) => line.includes(folder))) continue
try {
deps.remove(join(cliDir, name))
removed.push(name)
} catch (error) {
deps.log(`[update] ${name} could not be removed yet (${(error as NodeJS.ErrnoException).code ?? (error as Error).message}) — trying again later`)
}
}
return removed
}
/** The folders in [cliDir] `retireUnused` would remove, given [keep]; none without it. */
function retirable(cliDir: string, keep: ReadonlySet<string> | null): string[] {
if (!keep) return []
let names: string[]
try { names = readdirSync(cliDir) } catch { return [] }
const now = Date.now()
return names.filter((name) => {
if (keep.has(name)) return false
if (VERSION_FOLDER.test(name) || SET_ASIDE.test(name)) return isFolder(join(cliDir, name))
if (!STAGING.test(name)) return false
try { return now - statSync(join(cliDir, name)).mtimeMs > STAGING_GRACE_MS } catch { return false }
})
}