diff --git a/README.md b/README.md index 82e74f6..947feee 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,9 @@ Scope: [docs/objective.md](docs/objective.md). +Architecture: [system overview and Mermaid diagram](docs/architecture/system-overview.md), +[service lifecycle and storage](docs/architecture/service-lifecycle.md). + `soze` is a local HTTPS proxy between a coding agent and its model API. It forwards every byte as it arrives and taps a copy into a JSONL file in one common format ([docs/common-format.md](docs/common-format.md)). The tap never delays the agent: when it falls behind it drops events and counts them. Hosts an adapter claims (Codex: `chatgpt.com`, `api.openai.com`; Claude Code: `api.anthropic.com`) are decrypted with a local CA. Every other host is tunnelled untouched. diff --git a/docs/architecture/service-lifecycle.md b/docs/architecture/service-lifecycle.md new file mode 100644 index 0000000..a219992 --- /dev/null +++ b/docs/architecture/service-lifecycle.md @@ -0,0 +1,136 @@ +# Service lifecycle and storage + +The installed Soze service is a local proxy owned by one user. It runs the foreground binary +under an OS supervisor, keeps agent content in that user's files and does not change system +proxy or certificate-trust settings. See the [system overview](system-overview.md) for the +architecture diagram and capture pipeline. + +## Platform support + +**macOS service management is implemented. Linux service management is proposed, not +implemented.** The current installer calls `launchctl` directly; `task service:*` is not a +cross-platform service interface. + +| Concern | Current macOS behavior | Proposed Linux equivalent | +| --- | --- | --- | +| Supervisor | `launchd` user LaunchAgent | `systemd --user` service | +| Definition | `~/Library/LaunchAgents/com.killallgit.soze.plist` | `~/.config/systemd/user/soze.service` | +| Startup | GUI user login; job uses `RunAtLoad` | User-manager startup, normally login | +| Automatic recovery | `KeepAlive` | `Restart=on-failure` with a restart delay | +| Run without a login session | Not supplied by the current GUI-domain installer | Explicitly enable user lingering | +| Logging reload | SIGHUP | SIGHUP through `ExecReload` | + +The current macOS installer targets `gui/`, not a machine-level LaunchDaemon. It does not +provide unattended boot-time operation on a headless Mac. For Linux without systemd, no +service backend is implemented; the foreground binary can be managed by another supervisor. + +One service per user avoids sharing CA private keys and captured conversations across users. +The default port is still shared by the machine: two users cannot both bind +`127.0.0.1:48731`. Multi-user deployment would need distinct ports and matching wrapper +settings; the macOS installer currently fixes its service port at 48731. + +## macOS operations + +Run these commands from a checkout with Task installed: + +```sh +task service:install # build a debug binary, copy it into place and (re)start +task service:status # supervisor state, PID and installed-build provenance +task service:logs # follow the service log, never the capture files +task service:reload # SIGHUP: reload live logging settings +task service:restart # abruptly restart the process +task service:uninstall # remove the job and binary; keep captures, logs and config +``` + +Installation copies the binary to `~/.local/share/soze/bin/soze`, so changing checkout branches +or rebuilding a development binary does not replace the running installation. Re-running +`task service:install` updates the installed binary and restarts the service. It records the +source SHA, branch, dirty flag and installation time in `bin/install.json`. + +Restart and update cut in-flight streams. The supervisor can restore the service, but it does +not restore those connections or transparently move an existing agent onto a direct route. +A new process receives a fresh capture `run_id`. + +SIGHUP reloads live logging settings only. Other configuration changes, including retention, +require a restart. The installer's explicit port and output-path flags take precedence over +configuration-file values. See [configuration](../../README.md#configuration) for precedence +and the complete option contract. + +The shared installed service uses port 48731; `task dev` uses 48732, so both can run at once. +Use `SOZE_PORT=48732` when launching a wrapped agent against the development proxy. + +## Installed file layout + +| Path | Contents | +| --- | --- | +| `~/Library/LaunchAgents/com.killallgit.soze.plist` | macOS supervisor definition | +| `~/.local/share/soze/bin/soze` | Installed executable | +| `~/.local/share/soze/bin/install.json` | Installed-build provenance | +| `~/.local/share/soze/tap.jsonl` and numbered segments | Captured events, content, records and graph edges | +| `~/.local/share/soze/shapes.jsonl` and numbered segments | Request/reply keys and types without values | +| `~/.local/share/soze/debug.jsonl` | Disposable debug metadata | +| `~/.local/share/soze/logs/soze.log`, `soze.log.1` | Service stdout/stderr and the previous generation | +| `~/.config/soze/config.toml` | User configuration | +| `~/.config/soze/` | Local CA certificate and private key, alongside configuration | + +The first install creates `config.toml` with `log_format = "human"` and `live = true` if the +file is absent. Later installs preserve it. The CA is made on the binary's first run, not +installed into a trust store. + +Normal uninstall keeps captures, logs, configuration and CA material. +`task service:uninstall -- --purge` additionally lists and deletes the entire +`~/.local/share/soze/` directory. It still keeps `~/.config/soze/`. + +## Storage and retention + +| Output | Current policy | +| --- | --- | +| Tap captures | Defaults: 64 MiB segments, 1024 MiB total capacity, 14 days; configurable under `[retention]` | +| Shape output | Fixed: 4 MiB segments, 32 MiB total capacity, 14 days | +| Debug metadata | Stops accepting records at 16 MiB per run; reset on the next start | +| Service log | One previous generation retained when the service installer rotates it; no continuous size-based rotation | + +Tap and shape files rotate before a line would exceed the segment size, when the active file +is non-empty. A non-empty active file also rotates at startup. Cleanup runs after successful +rotation and removes the oldest closed segments by capacity or age; it never deletes the +active file. An idle process does not periodically expire files, so age and capacity settings +are not continuously enforced hard ceilings. See the [tap-file +contract](../../README.md#the-tap-file) for failure behavior and oversized-file handling. + +Agent sessions are logical identities within captures, not directories or files. Several +sessions can share a segment, and one session can span several segments and capture runs. +Retention removes segments, not whole sessions, so the retained portion of a session can be +incomplete. Session counts and per-session sizes cannot be inferred from file counts. + +## Management and visibility + +The `soze` CLI starts the proxy; it has no `status`, storage-usage or session-listing +subcommands and exposes no management or health API. + +| Information | Available interface | +| --- | --- | +| Supervisor state and PID | `task service:status`, macOS only | +| Installed source SHA, branch, dirty flag and installation time | Same command, from `bin/install.json` | +| Content-free operational activity | `task service:logs` | +| Capture and log disk usage | Filesystem tools; no built-in aggregate report | +| Retained session count or per-session size | No built-in report or persistent session index | + +Supervisor state and a listening TCP port do not prove successful upstream requests or +complete capture. The existing status command reports the supervisor and installation, not +an application-level health assessment. + +These commands report disk usage without printing captured content: + +```sh +du -sh "$HOME/.local/share/soze" +du -sh "$HOME/.local/share/soze/logs" +``` + +The first total includes the installed binary, captures, shape output, debug output and +service logs. The second isolates the service-log directory. Disk allocation reported by `du` +is not an exact serialized byte count for a session. + +A future cross-platform status command could report service state, build, port, disk usage +and retention settings, even when the proxy is stopped. Session summaries would require +metadata scanning or an index. Neither interface is implemented; no new API, index or +transport is assumed here. diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md new file mode 100644 index 0000000..d4b0e43 --- /dev/null +++ b/docs/architecture/system-overview.md @@ -0,0 +1,164 @@ +# System architecture overview + +Soze is a local, per-user HTTPS proxy with a non-blocking capture pipeline. Coding agents +communicate with their providers through it; a separate tap converts copied traffic into the +[common event format](../common-format.md). + +This document describes the current implementation. The Linux service supervisor in the +diagram is a proposal, not an implemented service backend. See [service lifecycle and +storage](service-lifecycle.md) for platform behavior, commands and retention. + +## Architecture diagram + +```mermaid +flowchart TB + subgraph Local["Local machine — user account"] + Wrappers["Shell wrappers / soze-wrap
Set agent-specific proxy and CA variables"] + Agents["Coding agents
Claude Code · Codex · Cursor"] + + subgraph Service["soze process — one Rust binary"] + Listener["HTTP CONNECT listener
127.0.0.1:48731 for the installed service"] + Route{"Adapter claims
the destination host?"} + Intercept["TLS interception
Forward request and reply streams"] + Tunnel["Opaque TCP tunnel
No content decryption"] + Queue["Bounded tap queue
Non-blocking offer; count dropped inputs"] + Adapters["Agent-specific parsers
Claude Code · Codex"] + Common["Common-format events
Reply assembly · identity and graph edges"] + Writer["Asynchronous JSONL writer
Sequence numbers · rotation · retention"] + Shapes["Optional shape observer
Keys and types, not values"] + Logging["Independent metadata logging
No message content"] + end + + Config["~/.config/soze/config.toml"] + CA["Local CA certificate and private key
~/.config/soze/"] + Captures[("Capture files
tap.jsonl + rotated segments")] + ShapeFiles[("Shape files
shapes.jsonl + rotated segments")] + LogFiles[("Operational and debug logs
soze.log · debug.jsonl")] + Mac["macOS launchd LaunchAgent
Implemented"] + Linux["Linux systemd user service
Proposed, not implemented"] + + Wrappers -->|"Launch with environment settings"| Agents + Agents <-->|"HTTPS CONNECT"| Listener + Listener --> Route + Route -->|"Yes"| Intercept + Route -->|"No"| Tunnel + Intercept -.->|"Copy request and response data
Never wait for capture"| Queue + Queue --> Adapters + Adapters --> Common + Common --> Writer + Writer --> Captures + Adapters -.->|"Observe request and reply structure"| Shapes + Shapes --> ShapeFiles + Intercept -.->|"Safe operational metadata"| Logging + Common -.->|"Safe capture metadata"| Logging + Logging --> LogFiles + Config --> Service + CA --> Intercept + Mac -->|"Start and supervise"| Service + Linux -.->|"Proposed supervision"| Service + end + + Models["Model APIs
Anthropic · OpenAI / ChatGPT"] + Other["Other destinations
Including Cursor servers"] + Intercept <-->|"Upstream TLS"| Models + Tunnel <-->|"Encrypted traffic"| Other + + classDef proposed fill:#fff4d6,stroke:#9a6700,stroke-dasharray:5 5; + class Linux proposed; +``` + +Dashed data-path arrows show copied traffic, observations or metadata, not forwarding +dependencies. The separately styled Linux supervisor is the only proposed component. +The diagram groups related responsibilities; it is not a task-by-task execution graph. + +## Agent integration + +The shell wrappers configure individual processes rather than changing system proxy settings: + +| Agent | Process environment | Capture support | +| --- | --- | --- | +| Claude Code | `HTTPS_PROXY`, `NODE_EXTRA_CA_CERTS` | Anthropic Messages requests and streamed replies | +| Codex | `HTTPS_PROXY`, `CODEX_CA_CERTIFICATE` | OpenAI Responses requests and streamed replies | +| Cursor (`agent`) | `HTTPS_PROXY` | Opaque tunnelling only; no model-content parsing | + +The wrappers add these settings only when the proxy port is listening, the CA certificate is +readable and neither `HTTPS_PROXY` nor `https_proxy` is already set. Otherwise, they launch the +real command without adding Soze settings. A listening-port check does not establish that the +process on that port is a healthy Soze instance. + +This decision happens when the agent starts. It is not mid-session failover: an agent already +using the proxy loses its connection if Soze stops. `SOZE_OFF=1` bypasses the wrappers for one +command; `command claude` and `command codex` bypass the corresponding shell functions. + +## Forwarding and TLS + +The binary listens on IPv4 loopback and accepts HTTP `CONNECT` requests. The installed service +uses port 48731; `task dev` uses 48732, and the binary can use another configured port. + +An adapter names the hosts Soze may decrypt. Claude Code claims `api.anthropic.com`; Codex +claims `chatgpt.com` and `api.openai.com`. Host matching includes subdomains of those names. + +- **Claimed host:** Soze terminates agent-side TLS using its local CA and establishes upstream + TLS to the provider. Request and response data are forwarded without waiting for capture. +- **Unclaimed host:** Soze tunnels encrypted bytes without decrypting the content. +- **Claimed host, unsupported endpoint:** Forwarding continues, with an `unsupported` capture + note rather than a parsed model exchange. + +The CA is created on first run, constrained to adapter hosts and never installed into a system +trust store. Only explicitly configured agents trust it. Credential headers are redacted before +capture output is written. + +## Capture pipeline + +The forwarding path offers copies of request and response data to a bounded queue without +waiting for a parser or disk. Slow or failed capture must not delay forwarding. + +Adapters interpret each agent's wire format, including SSE and WebSocket traffic. They emit +common-format conversation, block, usage and reply-completion events. The assembler builds a +whole conversation/reply record, and identity tracking adds project, session, thread, exchange, +step, turn and tool-call relationships where the traffic supplies them. + +These graph edges are records in the JSONL capture output, not a separate graph database. +Optional shape output records keys and types without values. Operational and debug logging +use independent bounded transports and exclude message content. + +The tap writer assigns emitted lines a `run_id` and monotonically increasing `sequence`. +Every proxy instance has a fresh `run_id`; restarting Soze starts a new capture run, not +necessarily a new agent session. See the [capture identity and delivery-order +contract](../common-format.md#capture-identity-and-delivery-order). + +If capture falls behind, inputs can be dropped and counted. Records report incomplete capture +where detected. Contiguous output sequences do not prove complete capture, because refused +inputs never receive sequence numbers. This is best-effort observation, not an exactly-once +or durable audit system. Invalid configuration or initialization failures can still prevent +the proxy from starting. + +## Scope and management boundaries + +Soze is one Rust crate and one binary. It does not own the agent's tool-execution loop or run +the model. The intended service deployment is one proxy per user, without root privileges; +the current installer implements that on macOS only. + +The CLI starts the proxy and accepts configuration flags, but has no status, storage-usage or +session-listing subcommands. The macOS task commands query the supervisor separately; see +[management and visibility](service-lifecycle.md#management-and-visibility). + +How other applications receive the common format remains undecided. This architecture assumes +no message bus, database, replay service or live-consumer transport. The [project +objective](../objective.md) defines that boundary. + +## Implementation map + +| Responsibility | Entry point | +| --- | --- | +| Startup, configuration and reload | [`src/main.rs`](../../src/main.rs), [`src/cli.rs`](../../src/cli.rs), [`src/config.rs`](../../src/config.rs), [`src/reload.rs`](../../src/reload.rs) | +| CONNECT routing, TLS, HTTP and WebSocket forwarding | [`src/proxy.rs`](../../src/proxy.rs), [`src/proxy/`](../../src/proxy/) | +| Adapter interface and agent parsers | [`src/adapter/`](../../src/adapter/) | +| Exchange lifecycle and non-blocking tap | [`src/exchange/`](../../src/exchange/) | +| Reply assembly and graph relationships | [`src/assembler/`](../../src/assembler/), [`src/graph/`](../../src/graph/) | +| JSONL writing, rotation and retention | [`src/sink.rs`](../../src/sink.rs) | +| Metadata-only logging | [`src/logging/`](../../src/logging/) | +| Service installation and shell integration | [`scripts/service.sh`](../../scripts/service.sh), [`scripts/soze-wrappers.sh`](../../scripts/soze-wrappers.sh) | + +For a source-level view of the forwarding and capture seams, see the +[detailed Mermaid diagram](2026-11-06_current-architecture.mmd).