ADR-010: Preserve v0.4 JSON-RPC 2.0 IPC Contract¶

Status: Accepted
Date: 2026-05-18
Deciders: Mohsen Seyedkazemi Ardebili

Context¶

YazSes v0.4 uses JSON-RPC 2.0 over newline-delimited JSON on a Unix socket (Linux/macOS) or named pipe (Windows). This IPC contract is consumed by the CLI (yazses status, yazses start, yazses stop), the tray application, and any editor plugin or tooling that drives the daemon programmatically. The schema is documented and has strong test coverage. Changing the contract in v1.0 would be a breaking change for every existing consumer, requiring coordinated updates across the CLI, tray, and all external integrations.

Decision¶

The v0.4 JSON-RPC 2.0 IPC contract is preserved exactly in v1.0. The server is reimplemented in Rust using jsonrpsee, but all existing method names, parameter schemas, and event-payload shapes remain identical.

New methods added in v1.0 are purely additive: - memory.init(passphrase), memory.status(), memory.commit(text, tags, ttl), memory.forget_last(minutes), memory.recall(query, k) — personal memory operations. - model.pull(model_id), model.list(), model.rm(model_id) — model management. - subscribe_tool_calls() — allows editor plugins to observe and intercept agent tool calls.

The IPC socket binds owner-only (mode 0600 on Unix; restricted to the calling user on Windows named pipe).

Consequences¶

Positive: - All v0.4 IPC consumers — CLI, tray, editor plugins, integration tests — work against the v1.0 daemon without modification. - JSON-RPC 2.0 is well-understood and has client libraries in every language. - The v0.4 test suite for the IPC surface carries forward directly as v1.0 regression tests. - Owner-only socket binding maintains the existing security posture.

Negative / trade-offs: - JSON-RPC over newline-delimited JSON is verbose compared to binary protocols (gRPC, Cap'n Proto). For high-frequency streaming events this overhead may matter in v2+; the decision is deferred, as streaming partial transcripts are not in v1.0. - Manual JSON schema versioning will be required if any v2+ method needs a breaking change. Mitigation: additive-only changes in v1.0 establish a clean compatibility baseline.

Implementation¶

The IPC server is in yazses-ipc/src/server.rs, using jsonrpsee with a Unix socket transport on Linux/macOS and a named-pipe transport on Windows. Method handlers are registered in yazses-core/src/daemon.rs. Existing v0.4 Python tests in tests/test_ipc.py run against the v1.0 server as integration tests.