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: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
136 changes: 136 additions & 0 deletions docs/architecture/service-lifecycle.md
Original file line number Diff line number Diff line change
@@ -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/<uid>`, 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.
164 changes: 164 additions & 0 deletions docs/architecture/system-overview.md
Original file line number Diff line number Diff line change
@@ -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<br/>Set agent-specific proxy and CA variables"]
Agents["Coding agents<br/>Claude Code · Codex · Cursor"]

subgraph Service["soze process — one Rust binary"]
Listener["HTTP CONNECT listener<br/>127.0.0.1:48731 for the installed service"]
Route{"Adapter claims<br/>the destination host?"}
Intercept["TLS interception<br/>Forward request and reply streams"]
Tunnel["Opaque TCP tunnel<br/>No content decryption"]
Queue["Bounded tap queue<br/>Non-blocking offer; count dropped inputs"]
Adapters["Agent-specific parsers<br/>Claude Code · Codex"]
Common["Common-format events<br/>Reply assembly · identity and graph edges"]
Writer["Asynchronous JSONL writer<br/>Sequence numbers · rotation · retention"]
Shapes["Optional shape observer<br/>Keys and types, not values"]
Logging["Independent metadata logging<br/>No message content"]
end

Config["~/.config/soze/config.toml"]
CA["Local CA certificate and private key<br/>~/.config/soze/"]
Captures[("Capture files<br/>tap.jsonl + rotated segments")]
ShapeFiles[("Shape files<br/>shapes.jsonl + rotated segments")]
LogFiles[("Operational and debug logs<br/>soze.log · debug.jsonl")]
Mac["macOS launchd LaunchAgent<br/>Implemented"]
Linux["Linux systemd user service<br/>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<br/>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<br/>Anthropic · OpenAI / ChatGPT"]
Other["Other destinations<br/>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).
Loading