Dashboard › opencode › Distillation
4dc8cd01-f83b-416f-b73e-42ae3f198f1f["lore_tm_v1_2atuux5XmQlYpkX3ty0TE2kWNPH_NCxLYV8cbWq9opo"]
Date: Sep 8, 2026
/home/byk/.local/share/opencode-v2-pilot/config/opencode/plugins/pty-transport.ts (319 lines), which implements the Node-side Unix-socket supervisor transport, helper launch, protocol framing/parsing, buffered output delivery, input writes, STOP/exit handling, and helper/readiness checks.pty-transport.ts protocol constants are MAGIC = Buffer.from("OPTY"), VERSION = 1, HEADER_SIZE = 12, MAX_FRAME_SIZE = 70 * 1024, MAX_IO_PAYLOAD_SIZE = 32 * 1024, and frame types TYPE_INPUT = 2, TYPE_OUTPUT = 3, TYPE_EXIT = 4, TYPE_ERROR = 5, TYPE_STARTED = 6, TYPE_STOP = 7, TYPE_STOPPED = 8 (pty-transport.ts:10-21).pty-transport.ts operational constants are DEFAULT_SOCKET_PATH = "/run/opencode-pty/supervisor.sock", DEFAULT_HELPER_PATH = "/usr/local/libexec/opencode-pty-client", HELPER_TIMEOUT_MS = 5_000, STOP_TIMEOUT_MS = 25_000, MAX_HELPER_ERROR_BYTES = 2_000, exported MAX_BUFFER_SIZE = 1_000_000, and transient-unit validation regex /^opencode-pty-[0-9a-f]{32}\.service$/ (pty-transport.ts:22-27,51).SupervisorTransport exposes unitName, asynchronous write(data: Buffer), asynchronous close(), exited: Promise<SupervisorExit>, and onOutput(listener); SupervisorExit contains result, execMainCode, and execMainStatus. SupervisorOptions supports socketPath, helperPath, verifyRootHelper, helperTimeoutMs, and stopTimeoutMs (pty-transport.ts:29-49).assertSupervisorAvailable() skips helper verification only when verifyRootHelper === false; otherwise it requires the helper to be a root-owned regular executable file with no group/world write bits, connects to the supervisor socket, validates the connected socket fd, and destroys the probe socket (pty-transport.ts:53-62).openSupervisorTransport() connects first, tracks started and exited promises, and retains output received before listener registration in pendingOutput; queued output is tail-bounded to exactly MAX_BUFFER_SIZE = 1_000_000 bytes by dropping complete oldest buffers or slicing the oldest buffer’s excess prefix (pty-transport.ts:64-97,114-132).pty-transport.ts requires magic OPTY, version 1, zero bytes at header offsets 6 and 7, and payload length no greater than MAX_FRAME_SIZE; malformed headers or oversized frames destroy the socket (pty-transport.ts:98-113).TYPE_OUTPUT requires a nonempty payload no larger than MAX_IO_PAYLOAD_SIZE; TYPE_STARTED requires one nonempty valid-UTF-8 unit name matching UNIT_NAME; TYPE_ERROR requires nonempty valid UTF-8 no larger than MAX_IO_PAYLOAD_SIZE; violations destroy the socket (pty-transport.ts:114-147).TYPE_EXIT requires at least 9 payload bytes and an exact total length of 9 + resultLength; it decodes execMainCode from byte 0, execMainStatus as a big-endian uint32 at offset 1, and valid-UTF-8 result from offset 9, then resolves exited and calls socket.end() (pty-transport.ts:148-157).TYPE_STOPPED is accepted only with an empty payload while stopping is true; it resolves exited as { execMainCode: 2, execMainStatus: 15, result: "stopped" } and ends the socket. Any unexpected frame type destroys the socket (pty-transport.ts:158-165).exited if unsettled; socket closure before a structured TYPE_EXIT or TYPE_STOPPED produces PTY supervisor connection closed before a structured exit. (pty-transport.ts:93-97,168-171).options.helperPath ?? DEFAULT_HELPER_PATH with arguments ordered as runtime seconds, then command and each argument encoded as base64url with an a prefix. Its stdio mapping is ["pipe", "pipe", "pipe", connectedSocketFD(socket), binding.fd], passing the connected supervisor socket and cwd binding fd as inherited descriptors 3 and 4 (pty-transport.ts:172-185).helperTimeoutMs ?? 5_000; helper errors destroy the supervisor socket, and successful helper completion must be followed by the TYPE_STARTED acknowledgement within the same configured timeout (pty-transport.ts:186-198).onOutput(listener) marks the listener ready, synchronously replays all retained buffers in order via pendingOutput.splice(0).forEach(listener), and resets pendingOutputBytes to 0 (pty-transport.ts:204-209).write(data) chunks input into at most MAX_IO_PAYLOAD_SIZE = 32 * 1024 bytes per TYPE_INPUT frame; every socket write is independently wrapped in withTimeout(..., helperTimeout, "PTY supervisor input write timed out."), and timeout/error destroys the socket (pty-transport.ts:210-217).close() sets stopping = true and writes exactly one empty TYPE_STOP frame when not already stopping or settled, then awaits structured exit and socket closure. The entire stop operation is wrapped by withTimeout(..., options.stopTimeoutMs ?? STOP_TIMEOUT_MS, "PTY supervisor stop timed out."); timeout/error destroys the socket (pty-transport.ts:218-230).connectedSocketFD() accesses Node’s private socket._handle.fd through Reflect.get, requires a nonnegative integer fd whose fstatSync(fd).isSocket() is true, and destroys the socket before throwing if Node does not expose a valid connected Unix-socket descriptor (pty-transport.ts:235-247).connect(path) uses createConnection(path) and a fixed HELPER_TIMEOUT_MS = 5_000 timer; timeout destroys the socket and reports PTY supervisor connection timed out. (pty-transport.ts:265-280).frame(type, payload) rejects payloads above MAX_FRAME_SIZE, allocates HEADER_SIZE + payload.length, writes magic/version/type and a big-endian uint32 payload length at offset 8, and copies the payload after the 12-byte header (pty-transport.ts:283-292).waitForHelper() requires a stderr pipe, kills the helper with SIGKILL after its timeout, counts all stderr bytes but retains chunks only while cumulative size is at most MAX_HELPER_ERROR_BYTES = 2_000, rejects signal termination, and reports retained trimmed stderr or PTY client helper exited with code ${code}. for nonzero exit (pty-transport.ts:298-318).