4b5583430d
New crate at agor-pty/ (standalone, not in workspace — portable to Tauri/Electrobun): - Rust daemon (agor-ptyd) with Unix socket IPC, JSON-framed protocol - PTY session lifecycle: create, resize, write, close, output fanout - 256-bit token auth, multi-client support, session persistence - TypeScript IPC client at clients/ts/pty-client.ts (Bun + Node.js) - Protocol: 9 client messages, 7 daemon messages - Based on tribunal ruling (78% confidence, 4 rounds, 55 objections) WIP: Rust implementation in progress (protocol.rs + auth.rs done)
90 lines
2.6 KiB
Markdown
90 lines
2.6 KiB
Markdown
# agor-pty — PTY Multiplexer Daemon
|
|
|
|
Standalone Rust daemon that manages terminal sessions via Unix socket IPC.
|
|
Portable across Tauri and Electrobun frontends.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Frontend (Electrobun/Tauri)
|
|
↕ Unix Socket IPC (JSON-framed)
|
|
agor-ptyd (Rust daemon)
|
|
↕ PTY master FDs
|
|
Shell processes (/bin/bash, etc.)
|
|
```
|
|
|
|
## Features
|
|
|
|
- **PTY multiplexing**: single daemon manages all terminal sessions
|
|
- **Session persistence**: sessions survive frontend disconnects/restarts
|
|
- **Multi-client**: multiple frontends can connect and subscribe to session output
|
|
- **Auth**: 256-bit token authentication per connection
|
|
- **Output fanout**: PTY output fanned to all subscribed clients (non-blocking)
|
|
- **Graceful shutdown**: SIGTERM/SIGINT cleanup
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# Build
|
|
cd agor-pty && cargo build --release
|
|
|
|
# Run daemon
|
|
./target/release/agor-ptyd --verbose
|
|
|
|
# Custom socket directory
|
|
./target/release/agor-ptyd --socket-dir /tmp/agor-test
|
|
|
|
# Custom default shell
|
|
./target/release/agor-ptyd --shell /bin/zsh
|
|
```
|
|
|
|
## IPC Protocol
|
|
|
|
JSON messages over Unix socket, newline-delimited.
|
|
|
|
### Client → Daemon
|
|
- `Auth { token }` — authenticate (must be first message)
|
|
- `CreateSession { id, shell, cwd, env, cols, rows }` — spawn shell
|
|
- `WriteInput { session_id, data }` — send input to PTY
|
|
- `Resize { session_id, cols, rows }` — resize terminal
|
|
- `Subscribe { session_id }` — receive output from session
|
|
- `Unsubscribe { session_id }` — stop receiving output
|
|
- `CloseSession { session_id }` — kill session
|
|
- `ListSessions` — get all active sessions
|
|
- `Ping` — keepalive
|
|
|
|
### Daemon → Client
|
|
- `AuthResult { ok }` — auth response
|
|
- `SessionCreated { session_id, pid }` — session spawned
|
|
- `SessionOutput { session_id, data }` — PTY output (base64)
|
|
- `SessionClosed { session_id, exit_code }` — session ended
|
|
- `SessionList { sessions }` — list response
|
|
- `Pong` — keepalive response
|
|
- `Error { message }` — error
|
|
|
|
## Integration
|
|
|
|
### As library (for Tauri)
|
|
```rust
|
|
use agor_pty::protocol::{ClientMessage, DaemonMessage};
|
|
```
|
|
|
|
### TypeScript client (for Electrobun)
|
|
See `clients/ts/` for the IPC client module.
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
agor-pty/
|
|
├── Cargo.toml
|
|
├── README.md
|
|
├── src/
|
|
│ ├── main.rs — daemon entry, CLI, signals
|
|
│ ├── lib.rs — library re-exports
|
|
│ ├── protocol.rs — IPC message types
|
|
│ ├── session.rs — PTY session management
|
|
│ ├── daemon.rs — Unix socket server
|
|
│ └── auth.rs — token authentication
|
|
└── clients/
|
|
└── ts/ — TypeScript IPC client (for Electrobun/Bun)
|
|
```
|