143 lines
4.5 KiB
Markdown
143 lines
4.5 KiB
Markdown
# Cypraea
|
|
|
|
## Overview
|
|
|
|
Cypraea is a Bash-compatible shell implemented as a client-server architecture with a focus on persistent sessions, robust command execution, and extensive logging. It is designed not only as a shell but as an observability and behavioral insight tool for terminal usage.
|
|
|
|
The goal is to provide infrastructure for:
|
|
|
|
1. Persistent, resumable shell sessions.
|
|
2. Detailed logging of all commands, including timing, results, and output.
|
|
3. Analysis of command behavior for ML systems, diagnostics, and real-time assistance.
|
|
|
|
Cypraea draws architectural inspiration from tmux and semantic goals from observability and telemetry systems.
|
|
|
|
## Goals
|
|
|
|
- Bash-compatible command behavior
|
|
- Client-server architecture
|
|
- Session-based shell state management
|
|
- Commands persist through disconnects (like SSH dropouts)
|
|
- Real-time command streaming and output
|
|
- Comprehensive, always-on command logging
|
|
- Future capability for behavioral analysis and assistance
|
|
|
|
## Core Architecture
|
|
|
|
Cypraea consists of:
|
|
|
|
- A **daemon process** (`cypraeadd`) running per user, managing all sessions.
|
|
- A **client frontend** (`cypraea`) that connects to the daemon and attaches to a session.
|
|
- Communication over a **Unix domain socket** using **line-delimited JSON**.
|
|
|
|
The daemon is responsible for:
|
|
|
|
- Managing named shell sessions
|
|
- Executing commands
|
|
- Capturing and streaming stdout/stderr
|
|
- Logging metadata and command output
|
|
- Retaining session state (cwd, env, aliases, etc.)
|
|
|
|
## Sessions
|
|
|
|
- Sessions are per-user but **multiple per user** (like tmux).
|
|
- Each session is identified by a numeric or later symbolic name.
|
|
- Sessions contain their own state:
|
|
- Current working directory
|
|
- Environment variables
|
|
- Aliases and other shell-local information
|
|
- Sessions are created automatically when referenced.
|
|
- Clients attach to sessions and may disconnect without terminating them.
|
|
|
|
## Client-Server Communication
|
|
|
|
- Communication happens over a Unix domain socket, at `$XDG_RUNTIME_DIR/cypraea.sock`.
|
|
- Only accessible by the user, controlled via file permissions.
|
|
- Messages are newline-delimited JSON, encoded in UTF-8.
|
|
|
|
Example Request (client → server):
|
|
|
|
```json
|
|
{ "type": "run_command", "session": "1", "cmd": "ls -la", "cwd": "/tmp", "env": { "FOO": "bar" } }
|
|
```
|
|
|
|
Example Response (server → client):
|
|
|
|
```json
|
|
{ "type": "stdout", "data": "file1.txt\n" }
|
|
{ "type": "stderr", "data": "warning: something\n" }
|
|
{ "type": "exit", "code": 0 }
|
|
```
|
|
|
|
- Output is streamed in real time.
|
|
- Messages may be chunked arbitrarily.
|
|
|
|
## Command Execution
|
|
|
|
- Commands are run using `tokio::process::Command`.
|
|
- stdout and stderr are piped back to the client in real time.
|
|
- Command output is also captured for logging.
|
|
- Execution occurs within the context of the session (cwd, env, etc.).
|
|
- Support for concurrent execution of commands across sessions and clients.
|
|
|
|
## Logging System
|
|
|
|
- Logs are stored in a SQLite database at `$XDG_DATA_HOME/cypraea/log.sqlite`.
|
|
- Every command execution is logged, including:
|
|
- Timestamps (start/end)
|
|
- Duration
|
|
- Command text
|
|
- Working directory
|
|
- Environment (optional, partial)
|
|
- Exit code
|
|
- stdout and stderr output
|
|
|
|
Example table schema:
|
|
|
|
```sql
|
|
CREATE TABLE commands (
|
|
id INTEGER PRIMARY KEY,
|
|
session TEXT,
|
|
timestamp_start DATETIME,
|
|
timestamp_end DATETIME,
|
|
duration_ms INTEGER,
|
|
cmd TEXT,
|
|
cwd TEXT,
|
|
exit_code INTEGER,
|
|
stdout TEXT,
|
|
stderr TEXT
|
|
);
|
|
```
|
|
|
|
- Logging is always on.
|
|
- Output size may be truncated or compressed in future versions.
|
|
- No retention or cleanup policy yet (by design).
|
|
|
|
## Security
|
|
|
|
- Access to the daemon is limited to the user by standard Unix file permissions.
|
|
- No multi-user access is allowed or supported.
|
|
- Future: socket authentication and encryption can be explored.
|
|
|
|
## Implementation Stack
|
|
|
|
- Language: Rust
|
|
- Async Runtime: Tokio
|
|
- IPC: Unix domain sockets via `tokio::net::UnixStream`
|
|
- Message Serialization: `serde_json`
|
|
- Command Parsing: `shell-words`
|
|
- Logging: SQLite using `rusqlite`
|
|
|
|
## Future Ideas
|
|
|
|
- Terminal emulator integration or attach/detach model
|
|
- Web dashboard or analytics viewer
|
|
- Error recognition and command recommendations
|
|
- LSP integration for intelligent shell completions
|
|
- Integration with OpenTelemetry or observability pipelines
|
|
- Plugin system and event hooks
|
|
|
|
## Summary
|
|
|
|
Cypraea is a shell for users and systems that want to *learn* from what happens at the command line. With real-time execution, logging, and stateful sessions, it serves as a durable, intelligent layer between user behavior and system insight.
|