Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion packages/process-daemon/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 2 additions & 1 deletion packages/process-daemon/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "opencode-pty"
version = "0.5.2"
version = "0.6.0"
edition = "2024"
rust-version = "1.90"
description = "Persistent PTY service for OpenCode"
Expand All @@ -20,6 +20,7 @@ serde_json = "1.0"
shell-words = "1.1"

[target.'cfg(unix)'.dependencies]
crossbeam-utils = "0.8"
libc = "0.2"
nix = { version = "0.28", features = ["poll", "process", "term", "user"] }
sha2 = "0.10"
Expand Down
8 changes: 4 additions & 4 deletions packages/process-daemon/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ terminals. Observer commands connect to an existing daemon without taking owners
The service uses a private authenticated local byte stream (Unix socket or Windows
named pipe) and an atomic registration file.

Integrations launch `opencode-pty daemon --name NAME [--runtime-dir DIR]` (protocol 8).
Integrations launch `opencode-pty daemon --name NAME [--runtime-dir DIR]` (protocol 9).
The server must claim the daemon within 5 seconds by sending the authenticated
framed envelope `{"token":"...","request":{"op":"own","instance_id":"..."}}`.
The response is `{"type":"owned"}`; that connection stays open as the sole
Expand Down Expand Up @@ -70,7 +70,7 @@ socket pair until a connection arrives, a stop or ownership change wakes it, an
ownership deadline is due, or a two-second safety net elapses. Windows still
polls every 25 ms.

The Windows named-pipe backend keeps protocol 8 and the registration fields
The Windows named-pipe backend uses protocol 9 and the registration fields
`instance_id`, `pid`, `protocol`, `socket`, `token`, and `features`. Treat `socket` as an opaque
local endpoint: on Windows it is `\\.\pipe\opencode-pty-<instance_id>`, not a
filesystem socket. A random per-instance name, exclusive first pipe instance,
Expand Down Expand Up @@ -111,7 +111,7 @@ so the runtime directory must be on a local NTFS volume (Windows 10 1709 or
later); there is no non-atomic fallback.

The Windows Rust `TerminalClient` and interactive CLI are not ported. Integrations
can use protocol 8 directly and the minimal `daemon::PipeConnection` byte-stream
can use protocol 9 directly and the minimal `daemon::PipeConnection` byte-stream
helper. Connect with `PipeConnection::connect_to(socket, pid)`, which rejects a
pipe whose server is not the registered daemon process: after a crash the stale
registration's pipe name is free for another local user to create. Integrations
Expand Down Expand Up @@ -211,7 +211,7 @@ return all available rows. Soft-wrapped rows stay separate, trailing whitespace
is trimmed, and blank rows (including trailing blank rows) are empty strings.
The alternate screen never exposes primary-screen history.

The protocol 8 request is `{"op":"read_rows","id":1,"rows":30}`;
The protocol 9 request is `{"op":"read_rows","id":1,"rows":30}`;
omitted or `null` `rows` uses the current height. Its response is
`{"type":"rows","process":{...},"lines":[...],"cursor_x":0,"cursor_y":0}`.
Metadata, lines, and zero-based active-screen cursor coordinates come from one
Expand Down
32 changes: 19 additions & 13 deletions packages/process-daemon/SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -181,14 +181,16 @@ starts a pipe process: any command without a terminal. Both return
`"SIGTERM"`, when a signal ended the process (on Windows, when the daemon
signalled it); `exit_code` is then null. `signal` is left out when there is
none.
- On Unix an exited pipe process stays listed, as a zombie, until `terminate`.
The zombie keeps its PID and process group ID reserved, so killing the group
can never reach an unrelated process. On Windows the process object and job
handle stay open until `terminate`, so the PID is not reused either.
`terminate` kills the whole tree (SIGKILL on Unix; the job on Windows),
reaps it and removes the process; it never waits on a descendant that left
the process group or job and still holds the pipe. The daemon never deletes
output files.
- A successful command may leave background processes running untracked.
On Unix a non-zero exit code sends SIGTERM to the process group before the
waiter reaps the leader, then SIGKILL after three seconds if the group
survives. A signal death has no numeric exit code and does not trigger this
cleanup. On Windows a non-zero exit terminates the job immediately. The
waiter clears kill-on-close and releases the job and process handles at exit.
- The finished record (including exit status, output path and metadata) stays
listed until `terminate`. Its PID is historical metadata. `terminate` kills
a running tree and removes its record; after exit it only removes the record.
The daemon never deletes output files.

### Line count

Expand Down Expand Up @@ -225,9 +227,8 @@ process group and the child, as a real signal. **On Windows every signal is a
hard kill** of the job: there is no console, so SIGTERM and SIGINT cannot be
caught, and the exit reports the signal that was sent, not a platform exit
code. Unlike `terminate`, `signal` keeps the process: `wait` then gets a normal
`Exited` with `signal`. Signalling an exited process is allowed and reaches
whatever is left of its group or job (an empty group is not an error); after
`terminate` the process is gone and `signal` fails.
`Exited` with `signal`. Signalling an exited process returns `Ok` without
sending a signal; after `terminate` the record is gone and `signal` fails.

If an outer job refuses the child (`ERROR_ACCESS_DENIED`, for example a job
with UI restrictions), the daemon runs the command anyway without a job, logs
Expand Down Expand Up @@ -256,7 +257,7 @@ connected owner; the superseded connection can no longer prepare handoffs or
stop the daemon, and its disconnect does not affect the new owner. The playground holds ownership until it exits; other CLI commands
only observe or operate an existing daemon and never start one.

Protocol v8 uses four-byte big-endian framing with bounded UTF-8 JSON control
Protocol v9 uses four-byte big-endian framing with bounded UTF-8 JSON control
frames and tagged raw binary output frames. Requests (`op`): `ping`, `own`,
`prepare_handoff`, `create_pty`, `create_pipe`, `list`, `get`, `wait`,
`signal`, `set_metadata`, `write`, `resize`, `control` (atomic interaction
Expand All @@ -271,7 +272,7 @@ connection, once the token has been checked. Clients can therefore probe for
a request.

`Pong` and the registration carry `features` (required), the daemon's additive
capabilities. Protocol 8 needs none, so the list is empty. Later additive
capabilities. Protocol 9 needs none, so the list is empty. Later additive
changes, such as a new request or field older clients can ignore, extend
`features` and keep the protocol version. Only breaking changes bump
`PROTOCOL_VERSION`, which clients reject on mismatch.
Expand Down Expand Up @@ -310,3 +311,8 @@ the database. It starts the daemon only when the first terminal or pipe
process is created.
Only an explicit restart handoff descriptor lets a replacement server reuse
the previous daemon's runtime directory and claim its ownership.

On upgrade to protocol 9, OpenCode discovers protocol-8 daemons under its
runtime root and in its inherited handoff directory. It authenticates each
live instance and requests shutdown. This one-time replacement ends its
running commands and persistent terminals. A new daemon still starts lazily.
18 changes: 9 additions & 9 deletions packages/process-daemon/npm/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@opencode/pty",
"version": "0.5.2",
"version": "0.6.0",
"description": "Persistent PTY service for OpenCode",
"type": "module",
"license": "MIT",
Expand All @@ -25,14 +25,14 @@
"index.js"
],
"optionalDependencies": {
"@opencode/pty-darwin-arm64": "0.5.2",
"@opencode/pty-darwin-x64": "0.5.2",
"@opencode/pty-linux-arm64-gnu": "0.5.2",
"@opencode/pty-linux-arm64-musl": "0.5.2",
"@opencode/pty-linux-x64-gnu": "0.5.2",
"@opencode/pty-linux-x64-musl": "0.5.2",
"@opencode/pty-win32-arm64": "0.5.2",
"@opencode/pty-win32-x64": "0.5.2"
"@opencode/pty-darwin-arm64": "0.6.0",
"@opencode/pty-darwin-x64": "0.6.0",
"@opencode/pty-linux-arm64-gnu": "0.6.0",
"@opencode/pty-linux-arm64-musl": "0.6.0",
"@opencode/pty-linux-x64-gnu": "0.6.0",
"@opencode/pty-linux-x64-musl": "0.6.0",
"@opencode/pty-win32-arm64": "0.6.0",
"@opencode/pty-win32-x64": "0.6.0"
},
"publishConfig": {
"access": "public"
Expand Down
2 changes: 1 addition & 1 deletion packages/process-daemon/src/client.rs
Original file line number Diff line number Diff line change
Expand Up @@ -894,7 +894,7 @@ mod tests {
let _ = std::fs::remove_dir_all(&directory);
assert_eq!(
error.to_string(),
"opencode-pty protocol mismatch: service=7, client=8"
"opencode-pty protocol mismatch: service=7, client=9"
);
}
}
12 changes: 6 additions & 6 deletions packages/process-daemon/src/protocol.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ use crate::service::{
PipeMetadata, ProcessExit, ProcessInfo, ProcessMode, ProcessSignal, TerminalId,
};

pub const PROTOCOL_VERSION: u32 = 8;
pub const PROTOCOL_VERSION: u32 = 9;
/// Additive capabilities of this daemon. Breaking changes bump
/// `PROTOCOL_VERSION`; everything in protocol 8 needs no feature.
/// `PROTOCOL_VERSION`; everything in protocol 9 needs no feature.
pub const FEATURES: &[&str] = &[];

pub fn features() -> Vec<String> {
Expand Down Expand Up @@ -363,18 +363,18 @@ mod tests {
}

#[test]
fn version_8_has_no_features() {
assert_eq!(PROTOCOL_VERSION, 8);
fn version_9_has_no_features() {
assert_eq!(PROTOCOL_VERSION, 9);
assert!(features().is_empty());
// `features` is required.
assert!(
serde_json::from_value::<Response>(
json!({"type": "pong", "instance_id": "a", "pid": 1, "protocol": 8})
json!({"type": "pong", "instance_id": "a", "pid": 1, "protocol": 9})
)
.is_err()
);
round_trip::<Response>(
json!({"type": "pong", "instance_id": "a", "pid": 1, "protocol": 8, "features": []}),
json!({"type": "pong", "instance_id": "a", "pid": 1, "protocol": 9, "features": []}),
);
}

Expand Down
33 changes: 19 additions & 14 deletions packages/process-daemon/src/service.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ use std::time::{Duration, Instant};

use anyhow::{Context, Result, anyhow, bail};
use crossbeam_channel::{Receiver, Sender, bounded};
#[cfg(unix)]
use crossbeam_utils::sync::WaitGroup;
use portable_pty::{ChildKiller, CommandBuilder, MasterPty, PtySize, native_pty_system};
use serde::{Deserialize, Serialize};

Expand Down Expand Up @@ -284,6 +286,9 @@ pub struct CreatePipe {

pub struct TerminalService {
terminals: Mutex<HashMap<TerminalId, Arc<TerminalHandle>>>,
/// Failed-command escalation outlives record deletion. Shutdown waits for it.
#[cfg(unix)]
escalations: WaitGroup,
created: AtomicU64,
replay_capacity: usize,
}
Expand All @@ -298,6 +303,8 @@ impl TerminalService {
pub fn new(replay_capacity: usize) -> Self {
Self {
terminals: Mutex::new(HashMap::new()),
#[cfg(unix)]
escalations: WaitGroup::new(),
created: AtomicU64::new(0),
replay_capacity,
}
Expand All @@ -322,7 +329,15 @@ impl TerminalService {
bail!("output_path must be absolute");
}
validate_metadata(&request.metadata)?;
self.insert(|id, order| TerminalHandle::spawn_pipe(id, order, request))
self.insert(|id, order| {
TerminalHandle::spawn_pipe(
id,
order,
request,
#[cfg(unix)]
self.escalations.clone(),
)
})
}

fn insert(
Expand Down Expand Up @@ -393,7 +408,7 @@ impl TerminalService {
}

/// Signals a pipe process and its process group. The process stays
/// listed; signalling one that already exited is allowed.
/// listed; signalling one that already exited is a no-op.
pub fn signal(&self, id: TerminalId, signal: ProcessSignal) -> Result<()> {
self.pipe(id)?
.process
Expand Down Expand Up @@ -615,6 +630,8 @@ impl TerminalService {
impl Drop for TerminalService {
fn drop(&mut self) {
self.shutdown();
#[cfg(unix)]
std::mem::take(&mut self.escalations).wait();
}
}

Expand All @@ -630,8 +647,6 @@ struct TerminalHandle {
/// Dropped at shutdown, before the joins, to cancel a pipe reader that a
/// surviving descendant would otherwise keep blocked.
cancel: Mutex<Option<Box<dyn Send>>>,
/// Runs after the joins; reaps a pipe process kept as a zombie until now.
reap: Mutex<Option<Box<dyn FnOnce() + Send>>>,
/// Pipe only: the child, for `signal`.
process: Option<Arc<pipe::Process>>,
info: Arc<RwLock<ProcessInfo>>,
Expand Down Expand Up @@ -867,7 +882,6 @@ impl TerminalHandle {
shutdown_tx: Mutex::new(Some(actor.shutdown_tx)),
killer: Mutex::new(killer),
cancel: Mutex::new(None),
reap: Mutex::new(None),
process: None,
info,
joins: Mutex::new(Some(vec![
Expand Down Expand Up @@ -929,14 +943,6 @@ impl TerminalHandle {
for join in handles {
let _ = join.join();
}
if let Some(reap) = self
.reap
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
.take()
{
reap();
}
Ok(())
}
}
Expand Down Expand Up @@ -2270,7 +2276,6 @@ mod tests {
shutdown_tx: Mutex::new(Some(shutdown_tx)),
killer: Mutex::new(Box::new(TestKiller)),
cancel: Mutex::new(None),
reap: Mutex::new(None),
process: None,
info,
joins: Mutex::new(Some(vec![
Expand Down
28 changes: 6 additions & 22 deletions packages/process-daemon/src/service/pipe.rs
Original file line number Diff line number Diff line change
@@ -1,10 +1,8 @@
//! Non-PTY ("pipe") processes: a command with no terminal, stdin closed and
//! stdout and stderr sharing one pipe so their bytes keep their order.
//!
//! The platform modules own the child, its process tree and the output pipe:
//! Unix keeps a zombie so the PID and process group stay reserved, and Windows
//! keeps the process and its kill-on-close job. Everything the two must do the
//! same way lives here:
//! The platform waiters clean up a failed command's tree and release the
//! child at exit. The actor keeps its record available for late waiters.
//!
//! - The reader writes every byte to the output file before handing it to the
//! actor, which keeps no replay buffer: the file is the only copy of the
Expand Down Expand Up @@ -105,7 +103,7 @@ impl OutputSink {
/// How a pipe child ended.
enum Exit {
Code(u32),
/// The daemon terminated the process; the value is the signal it sent.
/// The Unix terminating signal, or the signal sent by the daemon on Windows.
Signal(String),
}

Expand Down Expand Up @@ -149,24 +147,16 @@ fn new_pipe_info(id: TerminalId, pid: u32, request: CreatePipe) -> ProcessInfo {
}
}

/// The waiter's result, and something dropped only after the exit message is
/// sent (Unix starts the reader's drain by dropping a pipe writer).
struct Waiter {
exit: io::Result<Exit>,
after: Box<dyn Send>,
}

/// Registers a spawned pipe process with its actor, then runs the platform's
/// reader and waiter. Both are started in that order, and the waiter last, so
/// it is joined before the process is reaped.
/// reader and waiter. If startup fails before the waiter starts, reap here.
fn start_pipe(
id: TerminalId,
order: u64,
request: CreatePipe,
process: Arc<Process>,
cancel: Box<dyn Send>,
reader: impl FnOnce(Sender<ActorMessage>) + Send + 'static,
waiter: impl FnOnce() -> Waiter + Send + 'static,
waiter: impl FnOnce(Sender<ActorMessage>) + Send + 'static,
) -> Result<TerminalHandle> {
let info = Arc::new(RwLock::new(new_pipe_info(id, process.pid(), request)));
// Nothing is ever written to a pipe process; a disconnected queue
Expand Down Expand Up @@ -213,11 +203,7 @@ fn start_pipe(
let wait_actor_tx = actor_tx.clone();
let waiter = thread::Builder::new()
.name(format!("opencode-pty-wait-{id}"))
.spawn(move || {
let Waiter { exit, after } = waiter();
let _ = wait_actor_tx.send(exit_message(exit));
drop(after);
})
.spawn(move || waiter(wait_actor_tx))
.context("failed to spawn terminal child waiter");
let waiter = match waiter {
Ok(waiter) => waiter,
Expand All @@ -227,7 +213,6 @@ fn start_pipe(
}
};
joins.push(waiter);
let reap = Arc::clone(&process);
Ok(TerminalHandle {
order,
mode: ProcessMode::Pipe,
Expand All @@ -236,7 +221,6 @@ fn start_pipe(
shutdown_tx: Mutex::new(Some(shutdown_tx)),
killer: Mutex::new(Box::new(ProcessKiller(Arc::clone(&process)))),
cancel: Mutex::new(Some(cancel)),
reap: Mutex::new(Some(Box::new(move || reap.reap()))),
process: Some(process),
info,
joins: Mutex::new(Some(joins)),
Expand Down
Loading
Loading