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
/** Bounded native evidence. An unfinished lookup cannot prove that a conversation is unique. */
import { constants, type Dirent, type Stats } from 'node:fs'
import { open, opendir } from 'node:fs/promises'
export class IdentityReadUnavailable extends Error {
readonly code = 'IDENTITY_UNAVAILABLE'
constructor(reason: string, message = `Conversation identity is held: ${reason}.`) { super(message) }
}
/** The engine's executable was replaced on disk (a package manager updated it) while the process kept
* running, so the kernel no longer reports its image and no native read can succeed until it restarts. */
export const REPLACED_PROGRAM = 'the agent\u2019s program was replaced on disk while it was running; restart the agent'
/** A conversation was seen and then could not be read: never a reason to stop its process without it
* (lib/stopAgentService.ts `withoutConversation`). */
export class ObservedConversationUnavailable extends IdentityReadUnavailable {
constructor(message: string) { super('', message) }
}
export type IdentityVersion = Pick<Stats, 'dev' | 'ino' | 'size' | 'mtimeMs' | 'ctimeMs'> & {
/** Descriptor numbers can exceed Number's exact range; never round kernel ownership evidence. */
fileKey?: { device: bigint; inode: bigint }
}
/** Shared across every directory/root in one lookup, including entries that are not transcripts. */
export const identityScanBudget = () => ({ remaining: 4096 })
/** A regular file only. Nonblocking open prevents a native-store FIFO from hanging session control. */
export async function identityBytes(path: string, maxBytes: number, expected?: IdentityVersion,
budget?: { step(bytes?: number): void },
): Promise<Buffer> {
budget?.step()
const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK)
try {
budget?.step()
const before = await handle.stat()
if (!before.isFile()) throw new IdentityReadUnavailable('the native record is not a regular file')
if (expected?.fileKey) {
const exact = await handle.stat({ bigint: true })
if (exact.dev !== expected.fileKey.device || exact.ino !== expected.fileKey.inode) {
throw new IdentityReadUnavailable('the opened native record is not the file held by the process')
}
}
// A pathname can switch to another inode and back while a caller awaits its header. The
// opened descriptor must be the candidate that authorized this read, not only the path at return.
if (expected && (before.dev !== expected.dev || before.ino !== expected.ino || before.size !== expected.size
|| before.mtimeMs !== expected.mtimeMs || before.ctimeMs !== expected.ctimeMs)) {
throw new IdentityReadUnavailable('the opened native record differs from the inspected candidate')
}
const length = Math.min(before.size, maxBytes)
const bytes = Buffer.alloc(length)
let read = 0
let calls = 0
while (read < length) {
budget?.step()
if (budget && ++calls > 64) throw new IdentityReadUnavailable('the native header read-operation limit was reached')
const next = await handle.read(bytes, read, length - read, read)
budget?.step(next.bytesRead)
if (!next.bytesRead) throw new IdentityReadUnavailable('the native record ended during the read')
read += next.bytesRead
}
const after = await handle.stat()
budget?.step()
if (after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) {
throw new IdentityReadUnavailable('the native record changed during the read')
}
// Atomic rename leaves the old descriptor perfectly readable. Reopen the path without
// waiting for a writer and verify that it still names the record we just read.
const current = await open(path, constants.O_RDONLY | constants.O_NONBLOCK).catch(() => {
throw new IdentityReadUnavailable('the native record disappeared during the read')
})
try {
const now = await current.stat()
budget?.step()
if (now.dev !== before.dev || now.ino !== before.ino || now.size !== before.size
|| now.mtimeMs !== before.mtimeMs || now.ctimeMs !== before.ctimeMs) {
throw new IdentityReadUnavailable('the native record was replaced during the read')
}
} finally { await current.close() }
return bytes
} finally { await handle.close() }
}
/**
* A regular file's opening lines, read in bounded chunks with the same change checks as `identityBytes`.
* `skip` sees the first bytes of each line (up to SKIP_PROBE); a skipped line is passed over without being kept or
* counted, so a run of large bookkeeping records cannot hide the lines that follow it. `visit` gets each kept line in
* order and returns true to stop. The result says why reading ended: `stopped` by `visit`, the file's `end`, or a
* `limit` (kept lines, kept characters, or `maxBytes` read). A final line without a newline is visited only at `end`.
*/
const SKIP_PROBE = 64
export async function identityLines(path: string, limits: { maxBytes: number; maxLines: number; maxChars: number },
skip: (start: string) => boolean, visit: (line: string) => boolean | Promise<boolean>,
): Promise<'stopped' | 'end' | 'limit'> {
const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK)
try {
const before = await handle.stat()
if (!before.isFile()) throw new IdentityReadUnavailable('the native record is not a regular file')
const length = Math.min(before.size, limits.maxBytes), chunk = Buffer.alloc(64 * 1024)
let position = 0, lines = 0, chars = 0
let parts: Buffer[] = [], size = 0, decided = false, skipping = false
const keep = async (): Promise<'stopped' | 'limit' | null> => {
const text = Buffer.concat(parts).toString('utf8')
parts = []; size = 0
// A line's own newline counts only once a later line is read, as in a character slice of the head.
if (++lines > limits.maxLines || (chars += text.length) > limits.maxChars) return 'limit'
const stop = await visit(text)
chars += 1
return stop ? 'stopped' : null
}
const outcome = await (async (): Promise<'stopped' | 'end' | 'limit'> => {
while (position < length) {
const read = (await handle.read(chunk, 0, Math.min(chunk.length, length - position), position)).bytesRead
if (!read) throw new IdentityReadUnavailable('the native record ended during the read')
position += read
for (let from = 0; from < read;) {
const found = chunk.indexOf(10, from), newline = found !== -1 && found < read
const to = newline ? found : read
if (!skipping) {
parts.push(Buffer.from(chunk.subarray(from, to))); size += to - from
if (!decided && (size >= SKIP_PROBE || newline)) {
decided = true
skipping = skip(Buffer.concat(parts).subarray(0, SKIP_PROBE).toString('utf8'))
if (skipping) { parts = []; size = 0 }
}
if (!skipping && size > limits.maxChars * 4) return 'limit'
}
if (!newline) break
if (!skipping) { const done = await keep(); if (done) return done }
decided = false; skipping = false
from = to + 1
}
}
if (length < before.size) return 'limit'
if (!skipping && size && !skip(Buffer.concat(parts).subarray(0, SKIP_PROBE).toString('utf8'))) {
const done = await keep(); if (done) return done
}
return 'end'
})()
const after = await handle.stat()
if (after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) {
throw new IdentityReadUnavailable('the native record changed during the read')
}
const current = await open(path, constants.O_RDONLY | constants.O_NONBLOCK).catch(() => {
throw new IdentityReadUnavailable('the native record disappeared during the read')
})
try {
const now = await current.stat()
if (now.dev !== before.dev || now.ino !== before.ino || now.size !== before.size
|| now.mtimeMs !== before.mtimeMs || now.ctimeMs !== before.ctimeMs) {
throw new IdentityReadUnavailable('the native record was replaced during the read')
}
} finally { await current.close() }
return outcome
} finally { await handle.close() }
}
/** opendir bounds the directory buffer too; readdir followed by slice would still read the whole tree. */
export async function* identityEntries(path: string, budget: { remaining: number }, missingOkay = true): AsyncGenerator<Dirent> {
// An empty or missing directory still costs a filesystem operation.
if (budget.remaining-- <= 0) throw new IdentityReadUnavailable('the directory entry limit was reached')
let directory
try { directory = await opendir(path, { bufferSize: 32 }) }
catch (error) {
if (missingOkay && (error as NodeJS.ErrnoException).code === 'ENOENT') return
throw new IdentityReadUnavailable('a session directory could not be read')
}
try {
// The iterator closes the directory on completion, exceptions and early return.
for await (const entry of directory) {
if (budget.remaining-- <= 0) throw new IdentityReadUnavailable('the directory entry limit was reached')
yield entry
}
} catch (error) {
if (error instanceof IdentityReadUnavailable) throw error
throw new IdentityReadUnavailable('a session directory could not be read completely')
}
}
/** Small whole-file identity, never a prefix that could omit a conflicting field. */
export async function identityFile(path: string, maxBytes = 64 * 1024): Promise<string> {
let bytes: Buffer
try { bytes = await identityBytes(path, maxBytes + 1) }
catch (error) {
if (error instanceof IdentityReadUnavailable) throw error
if ((error as NodeJS.ErrnoException).code === 'ENOENT') throw error
throw new IdentityReadUnavailable('the native record could not be read')
}
if (bytes.length > maxBytes) throw new IdentityReadUnavailable('the native record exceeds the read limit')
return bytes.toString('utf8')
}
/** Only complete lines from a bounded prefix; EOF may complete the final line without a newline. */
export async function identityHead(path: string, lines: number, maxBytes = 256 * 1024, expected?: IdentityVersion): Promise<{ lines: string[]; complete: boolean }> {
const bytes = await identityBytes(path, maxBytes + 1, expected).catch(error => {
if (error instanceof IdentityReadUnavailable) throw error
throw new IdentityReadUnavailable('the native header could not be read')
})
const complete = bytes.length <= maxBytes
const head = bytes.subarray(0, maxBytes).toString('utf8').split('\n')
if (!complete) head.pop()
return { lines: head.slice(0, lines), complete: complete && head.length <= lines }
}