Dashboard › opencode › Distillation
1970bd0c-17e4-4018-bc8a-f2f8550cb2f3["lore_tm_v1_HOqbe5ls9-DXY3elyueWl5aqRb9uDFznxVwGYyf_Drk"]
Date: Sep 8, 2026
/home/byk/.local/share/opencode-v2-pilot/config/opencode/plugins/pty-transport.ts (319 lines), which implements a Unix-socket PTY supervisor transport using spawn, createConnection, a privileged helper, framed binary messages, buffered output, structured exits, and stop handling.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, TYPE_INPUT = 2, TYPE_OUTPUT = 3, TYPE_EXIT = 4, TYPE_ERROR = 5, TYPE_STARTED = 6, TYPE_STOP = 7, and TYPE_STOPPED = 8.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 UNIT_NAME = /^opencode-pty-[0-9a-f]{32}\.service$/.pty-transport.ts defines SupervisorExit with result, execMainCode, and execMainStatus; SupervisorTransport with unitName, write(data: Buffer), close(), exited, and onOutput(listener); and SupervisorOptions with optional socketPath, helperPath, verifyRootHelper, helperTimeoutMs, and stopTimeoutMs.assertSupervisorAvailable() skips checks only when verifyRootHelper === false; otherwise it verifies the helper is a root-owned regular file, has no group/world write bits (helper.mode & 0o022), and has an execute bit (helper.mode & 0o111), then connects to the supervisor socket and validates its descriptor via connectedSocketFD().openSupervisorTransport(binding, command, args, runtimeSeconds, options) connects to the Unix socket, launches options.helperPath ?? DEFAULT_HELPER_PATH, and passes arguments as String(runtimeSeconds), followed by the command and each argument encoded as base64url with an a prefix. Its stdio passes the connected supervisor socket descriptor and binding.fd as file descriptors 3 and 4.OPTY, version 1, reserved bytes 6 and 7 equal to zero, and payload length no greater than MAX_FRAME_SIZE; malformed headers, oversized frames, invalid UTF-8, invalid payload lengths, invalid transient unit names, and unexpected frame types destroy the socket with specific errors.TYPE_OUTPUT frames must contain 1..MAX_IO_PAYLOAD_SIZE bytes. Output arriving before onOutput() is registered is retained in pendingOutput; when buffered output exceeds MAX_BUFFER_SIZE = 1_000_000, the oldest bytes are discarded, including partial trimming of the oldest buffer. Registering onOutput() flushes buffered chunks in order and resets pendingOutputBytes to 0.TYPE_STARTED accepts exactly one nonempty UTF-8 unit name matching /^opencode-pty-[0-9a-f]{32}\.service$/; TYPE_ERROR requires a nonempty UTF-8 payload of at most MAX_IO_PAYLOAD_SIZE; TYPE_EXIT carries execMainCode in byte 0, a big-endian execMainStatus at bytes 1–4, a big-endian result length at bytes 5–8, and a UTF-8 result beginning at byte 9.TYPE_STOPPED frame is accepted only while stopping and with an empty payload; it resolves the exit as { execMainCode: 2, execMainStatus: 15, result: "stopped" }. If the socket closes before a structured exit, the transport fails with "PTY supervisor connection closed before a structured exit.".MAX_IO_PAYLOAD_SIZE and send each as TYPE_INPUT under the helper timeout. close() sends one empty TYPE_STOP frame when not already stopping or settled, awaits exited and socket closure, and enforces options.stopTimeoutMs ?? STOP_TIMEOUT_MS, destroying the socket on timeout.connectedSocketFD() accesses Node’s private socket _handle.fd, requires a nonnegative integer descriptor for which fstatSync(fd).isSocket() is true, and otherwise destroys the socket with either "Node runtime does not expose the connected Unix socket descriptor." or "Node runtime returned an invalid connected Unix socket descriptor.".connect(path) uses createConnection(path) and a fixed HELPER_TIMEOUT_MS timeout, failing with "PTY supervisor connection timed out."; notably, this connection timeout does not use SupervisorOptions.helperTimeoutMs.frame(type, payload) rejects payloads larger than MAX_FRAME_SIZE, allocates HEADER_SIZE + payload.length, writes MAGIC, VERSION, the frame type, and a big-endian payload length at offset 8, then copies the payload at offset HEADER_SIZE.waitForHelper(helper, timeout) requires a stderr pipe, kills the helper with "SIGKILL" on timeout, captures at most MAX_HELPER_ERROR_BYTES = 2_000 based on cumulative chunk size, rejects signal termination as "PTY client helper terminated by ${signal}.", rejects nonzero exit using captured stderr or "PTY client helper exited with code ${code}.", and succeeds only on exit code 0.