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
/** TypeScript mirror of the harness-pty wire protocol (pty/src/protocol.rs). */
import { createHash } from 'node:crypto'
/**
* The protocol this daemon's host speaks (protocol.rs `PROTOCOL`). A host's instance is `p<protocol>-<version>`, so
* hosts of one protocol and different builds run side by side (instance.ts); one from before that is `p<protocol>`.
*
* - 2: the `shutdown` op, for draining a host of the protocol before.
* - 1: the first.
*
* The rule for a bump: this daemon must keep a client for the protocol before it (`SUPPORTED_PTY_PROTOCOLS`). A host
* of that protocol may still hold the person's panes after an update; it is a drain backend (ptyHost/drain.ts) until
* they close, and this client speaks its protocol to it, the hello included. An op added at N is gated on the host's
* protocol (`PtyHostClient.protocol`, as `shutdown` is), and an op N changes must keep its N−1 form here.
*/
export const PTY_PROTOCOL = 2
/** The protocols whose hosts this daemon reaches: its own, which new panes go to, and the one before, drained. */
export const SUPPORTED_PTY_PROTOCOLS: readonly number[] = [PTY_PROTOCOL - 1, PTY_PROTOCOL].filter((p) => p >= 1)
/** The first protocol with the `shutdown` op. */
export const SHUTDOWN_PROTOCOL = 2
/**
* The feature a host lists (its hello reply's and `harness-pty version`'s `features`) when its `create` takes a
* `seed`: added within protocol 2, so a host's protocol does not say it. A host that lists no features has none.
*/
export const SEED_FEATURE = 'seed'
export const MAX_FRAME = 8 * 1024 * 1024
export enum FrameKind {
Subscribe = 1,
Input = 2,
Paste = 3,
Resize = 4,
Snapshot = 5,
Pause = 6,
Resume = 7,
Output = 16,
SnapshotReply = 17,
Closed = 18,
Ack = 19,
}
export type PtyErrorCode =
| 'no_pane'
| 'bad_request'
| 'spawn_failed'
| 'held_mismatch'
| 'unsupported'
| 'internal'
export function encodeFrame(kind: FrameKind, payload: Uint8Array): Buffer {
if (payload.length > MAX_FRAME) throw new Error('frame too large')
const out = Buffer.allocUnsafe(5 + payload.length)
out.writeUInt8(kind, 0)
out.writeUInt32BE(payload.length, 1)
out.set(payload, 5)
return out
}
export interface Frame {
kind: FrameKind
payload: Buffer
}
/**
* Accumulates socket chunks and yields complete frames. A frame whose length
* exceeds MAX_FRAME (8 MiB) or whose kind is unknown makes `push` throw; the
* reader is then unusable and the connection must be dropped.
*
* Chunks wait in a list and each byte is copied once more, into its frame: joining the
* whole backlog on every chunk would make an 8 MiB frame read in 1 KiB chunks quadratic.
*/
export class FrameReader {
private chunks: Buffer[] = []
/** Bytes of `chunks[0]` already consumed. */
private offset = 0
private size = 0
push(chunk: Uint8Array): Frame[] {
// A copy: the caller may reuse its buffer once push returns.
if (chunk.length > 0) {
this.chunks.push(Buffer.from(chunk))
this.size += chunk.length
}
const frames: Frame[] = []
while (this.size >= 5) {
const head = this.peekHeader()
const kind = head.readUInt8(0)
const len = head.readUInt32BE(1)
if (len > MAX_FRAME) throw new Error('frame too large')
if (FrameKind[kind] === undefined) throw new Error(`unknown frame kind ${kind}`)
if (this.size < 5 + len) break
this.take(5)
frames.push({ kind: kind as FrameKind, payload: this.take(len) })
}
return frames
}
private peekHeader(): Buffer {
const first = this.chunks[0]
if (first.length - this.offset >= 5) return first.subarray(this.offset, this.offset + 5)
const head = Buffer.allocUnsafe(5)
let at = 0
let offset = this.offset
for (let i = 0; at < 5; i++, offset = 0) {
at += this.chunks[i].copy(head, at, offset, Math.min(this.chunks[i].length, offset + 5 - at))
}
return head
}
/** Remove `n` bytes (n <= size) from the front, as a buffer of their own. */
private take(n: number): Buffer {
const out = Buffer.allocUnsafe(n)
let at = 0
let used = 0
while (at < n) {
const first = this.chunks[used]
const copied = first.copy(out, at, this.offset, Math.min(first.length, this.offset + n - at))
at += copied
this.offset += copied
if (this.offset === first.length) {
used++
this.offset = 0
}
}
if (used > 0) this.chunks.splice(0, used)
this.size -= n
return out
}
}
export type HelloRole = 'control' | 'stream'
/**
* A client's hello (pty/src/protocol.rs `Hello`). It never carries the token: whatever listens on the endpoint reads
* it, and that may be a process squatting on the name. `nonce` is 32 random bytes as 64 hex digits; `auth` is
* `helloAuth(token, nonce)`, and the reply's `proof` is `helloProof(token, nonce)`.
*/
export interface HelloLine {
hello: { auth: string; nonce: string; protocol: number; role: HelloRole; clientId: string }
}
export type HelloReply =
| { hello: { ok: true; instance: string; version: string; pid: number; features?: string[]; proof: string } }
| { hello: { ok: false; code: string; reason: string } }
const tokenDigest = (token: string, separator: string, nonce: string) =>
createHash('sha256').update(token).update(separator).update(nonce).digest('hex')
/** The client's `auth` for [nonce] (protocol.rs `hello_auth`): hex SHA-256(token || 0x01 || nonce). */
export function helloAuth(token: string, nonce: string): string {
return tokenDigest(token, '\u0001', nonce)
}
/**
* The `proof` a host's hello reply carries for [nonce] (protocol.rs `hello_proof`): hex SHA-256(token || 0x00 ||
* nonce). Only a host that knows the token can give it, so a process squatting on the endpoint cannot pass for the
* host; the separators differ from `helloAuth`'s, so neither can be passed off as the other.
*/
export function helloProof(token: string, nonce: string): string {
return tokenDigest(token, '\0', nonce)
}
export interface PaneInventoryRow {
pane: string
/** The current child's pid, or the last one's once it has exited (a held, dead pane), as tmux keeps a dead
* pane's `#{pane_pid}`; null only where the host never learned one. */
rootPid: number | null
cwd: string
title: string
dead: boolean
/** The `owner` and `label` given at `create`. */
owner: string
label: string | null
}
export interface PaneStateInfo {
dead: boolean
exitStatus: number | null
command: string[]
engineExit: number | null
/** `command` joined by single spaces: tmux's `#{pane_start_command}`, which a held shell is told by
* (nativePaneHold.ts `heldPaneFormat`). */
startCommand: string
}
export interface PaneInfo {
command: string
path: string
/** null once the pane's process has exited. */
pid: number | null
tty: string
}
/** `create`'s and `respawn`'s `afterExit` (pty/src/protocol.rs `AfterExit`): what the pane runs once its child exits by
* itself, the status recorded as its `engineExit` and given to it as `HARNESS_ENGINE_EXIT`. */
export interface PtyAfterExit {
command: string[]
env?: Record<string, string>
}
export type PtyOp =
| { op: 'create'; command: string[]; cwd?: string; env?: Record<string, string>; cols: number; rows: number; owner: string; label?: string; hold: boolean; afterExit?: PtyAfterExit; clearInherited?: string[]; /** Scrollback the pane starts with: lines separated by \n or \r\n. Send only to a host listing the `seed` feature. */ seed?: string }
| { op: 'kill'; pane: string; graceMs?: number }
| { op: 'inventory' }
| { op: 'titles' }
| { op: 'paneState'; pane: string }
| { op: 'paneInfo'; pane: string }
| { op: 'capture'; pane: string; historyLines?: number; ansi: boolean; visible: boolean }
| { op: 'write'; pane: string; data: string }
| { op: 'paste'; pane: string; text: string; bracketed: boolean }
| { op: 'key'; pane: string; key: string }
| { op: 'setTitle'; pane: string; title: string }
| { op: 'holdOpen'; pane: string }
| { op: 'releaseHold'; pane: string }
| { op: 'respawn'; pane: string; command: string[]; cwd?: string; env?: Record<string, string>; expectedHeldToken?: string; clearEnv?: string[]; clearInherited?: string[]; afterExit?: PtyAfterExit }
| { op: 'jobPids'; pane: string }
| { op: 'processes' }
| { op: 'setEngineExit'; pane: string; status: number }
/** Protocol 2 (`SHUTDOWN_PROTOCOL`): the host replies, then exits, but only with no pane at all; else `bad_request`. */
| { op: 'shutdown' }
export type PtyOpName = PtyOp['op']
export type PtyOpOf<K extends PtyOpName> = Extract<PtyOp, { op: K }>
export type PtyRequest = { id: number } & PtyOp
export interface PtyOpReplies {
create: { pane: string }
kill: Record<string, never>
inventory: { panes: PaneInventoryRow[] }
titles: { titles: Record<string, string> }
paneState: { state: PaneStateInfo | 'gone' }
/** A pane the host does not have is a `no_pane` failure, never a null `info`. */
paneInfo: { info: PaneInfo }
capture: { text: string }
write: Record<string, never>
paste: Record<string, never>
key: Record<string, never>
setTitle: Record<string, never>
holdOpen: Record<string, never>
releaseHold: Record<string, never>
respawn: Record<string, never>
jobPids: { pids: number[] }
processes: { rows: unknown[] }
setEngineExit: Record<string, never>
shutdown: Record<string, never>
}
/** The reply line to a request for op `K`. */
export type PtyResponse<K extends PtyOpName = PtyOpName> =
| ({ id: number; ok: true } & PtyOpReplies[K])
| { id: number; ok: false; code: PtyErrorCode; reason: string }
export type PtyEvent =
/** `status` is null when the host could not learn it. */
| { event: 'exit'; pane: string; status: number | null }
| { event: 'title'; pane: string; title: string }
/* Stream connection payloads (pty/src/stream.rs). */
/** `FrameKind.Subscribe`. A subscriber that is not read-only resizes the pane to itself. */
export interface StreamSubscribe {
pane: string
cols: number
rows: number
readOnly: boolean
}
/** `FrameKind.Resize`. */
export interface StreamResize {
cols: number
rows: number
}
/**
* `FrameKind.Snapshot`. `historyLines` defaults to 2000 for `conversation` and 500 otherwise;
* `none` sends no history.
*/
export interface StreamSnapshotRequest {
id: number
history: 'none' | 'plain' | 'conversation'
historyLines?: number
}
/** `PaneMeta` as the host sends it (snake_case). */
export interface PtyPaneMeta {
cols: number
rows: number
alternate_on: boolean
cursor_x: number
cursor_y: number
cursor_visible: boolean
mouse_standard: boolean
mouse_button: boolean
mouse_all: boolean
mouse_utf8: boolean
mouse_sgr: boolean
}
/**
* `FrameKind.SnapshotReply`. `capture` is `capture-pane -p -e -N` (one line per screen row) and
* `history` is `capture-pane -p -e -N -S -<n> -E -1`. Output frames with `seq <= seq` that arrive
* after the reply are already in it; every later output follows it.
*
* For `history: 'conversation'` the reply also carries the history as `capture-pane -p -e -J`
* prints it (`historyJoined`) and whether its last line continues into the screen
* (`lastContinues`, as read from `capture-pane -p -J -S -1 -E 0`). They are dropped, before any
* plain history, from a reply that would not fit a frame.
*/
export type StreamSnapshotReply =
| {
id: number
ok: true
seq: number
capture: string
history: string
historyJoined?: string
lastContinues?: boolean
meta: PtyPaneMeta
}
| { id: number; ok: false; reason: 'not_subscribed' | 'no_pane' | 'bad_request' }
/**
* `FrameKind.Ack`, one per Subscribe, Input, Paste and Resize, in order; `for` is the acknowledged
* frame's kind. A Resize ack's `seq` is the last output drawn at the old size. A Subscribe or Resize
* ack says whether the pane's size changed (`resized`): not for a read-only subscriber, nor for a
* size the pane already had (the host skips it, as tmux does, and the child gets no SIGWINCH).
*/
export type StreamAck =
| { for: FrameKind; ok: true; seq?: number; resized?: boolean }
| {
for: FrameKind
ok: false
reason: 'not_subscribed' | 'already_subscribed' | 'read_only' | 'no_pane' | 'exited' | 'bad_request'
}
/** `FrameKind.Closed`; the host ends the connection after it. */
export interface StreamClosed {
reason: 'exited' | 'killed' | 'overflow'
}