opencode/packages/process-daemon/AGENTS.md

opencode-pty

Objective

Build a persistent Rust PTY service. The service owns multiple terminal child processes, continuously drains output, parses it with libghostty-vt, retains a bounded raw replay tail, and exposes thread-safe terminal operations.

Current Scope

• Use portable-pty directly.
• Give each terminal blocking reader, actor/parser, writer, and child-wait threads.
• Keep libghostty-vt on the actor thread that creates it.
• Bound raw output, input, and actor queues.
• Make libghostty authoritative for terminal-generated PTY responses.
• Provide an interactive local CLI for exercising multiple terminals.
• Do not add OpenCode IPC integration yet.
• Do not implement descriptor passing or live service replacement.

Engineering Rules

• Never block the service control path on PTY I/O.
• Never perform a blocking write from a libghostty callback.
• Keep exactly one PTY reader and one PTY writer per terminal.
• Preserve child-exit and PTY-EOF as distinct lifecycle signals.
• Treat PID as metadata, never terminal identity.
• Bound by bytes, not only message count.
• Do not expose borrowed libghostty values outside the actor thread.
• Keep terminal shutdown idempotent and join all worker threads.

Verification

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo run -- play