# agent-zed as the Joule Code reference consumer

agent-zed is the flagship **consumer** of the [Joule Code](https://github.com/transaction-science/open-standards/tree/main/joule-code) standard — the SOTA editor surface for it. The protocol itself is the lean `joule-code-rs` library in the open-standards repository; agent-zed imports it and is one (high-quality) implementation, the way `wai-rs` is the standard and CommunicationOS is a consumer.

This document maps agent-zed's modules to the Joule Code `SPEC.md` clauses and states, honestly, what is implemented versus pending. It is the conformance map a reviewer reads to check the claim.

## Dependency on the standard

The panel depends on the standard's reference crates as **path dependencies** against a sibling `open-standards/` checkout (see `crates/agent_zed_panel/Cargo.toml`):

```
joule-code-schema  = { path = ".../joule-code-rs/crates/joule-code-schema" }
joule-code-receipt = { path = ".../joule-code-rs/crates/joule-code-receipt" }
```

At publish these become a git or crates.io dependency on `transaction-science/open-standards`. The standard is the single source of truth; agent-zed does not vendor a copy.

## SPEC clause → module map

| SPEC clause | Requirement | Where in agent-zed | Status |
|---|---|---|---|
| §1.3 No capture | core function never requires a steward's servers; frontier credential lives in the vendor's client; no protocol token | the whole privacy-hardening pass — see [`PRIVACY_HARDENING.md`](PRIVACY_HARDENING.md): sign-in/telemetry/crash/auto-update removed, egress backstop, ACP-registry auto-fetch killed; ACP legs drive the vendor's own logged-in CLI (`crates/agent_servers`), credential never transported | **Implemented & verified** (tshark-confirmed network-silent startup) |
| §6 Receipt | two-part `measured + estimated` µJ with honest `Provenance`, per operation | `crates/agent_zed_panel` `session_receipt()` emits a `joule_code_receipt::Receipt` from real ACP `token_usage`: tier `L4`, `Energy::from_tokens` → `Estimator`, surfaced as `⚡ N J this session (est.) · L4`. **Phase 3a:** the host's energy is now read from a real `jouleclaw_energy::EnergyCounter` (`host_energy()`), surfaced as a separate `host N J (provenance)` line, with `jouleclaw`→`joule_code` provenance mapped 1:1. The honesty split: an L4 op's receipt energy is the *remote* agent's inference (token-estimated — we cannot read a vendor's shunt); the host line is *our* machine's measured energy and becomes a local-tier op's receipt energy once L0–L3 land | **Implemented** (estimated + host-counter path). On RAPL/NVML the host reads `HwShunt` (measured); on Apple Silicon it is a load-avg `Estimator` until JouleClaw wires IOReport |
| §1.1 / §5 Cascade | dispatch L0→L4, stop at first close; L4 = frontier agent over ACP | `crates/agent_zed_panel` federation legs (Claude Code / Gemini / Codex) are the **L4 (Wire)** tier, reached over ACP via `agent_servers` + `acp_thread` | **Partial** — L4 implemented; L0–L3 (cache / lawful / embed / local model) land with the JouleClaw cascade integration (Phase 3) |
| §2 / §3 / §4 Cargo, identity, canonical form | coding operations as content-addressed, signed transitions | not yet — agent-zed currently exchanges ACP chat-style turns, not per-operation `CodingOp`s. The receipt's `op_id` content-addresses the turn's token usage as a placeholder | **Pending** (cargo integration) |
| §8 Conformance | round-trip the C1–C4 wire vectors | the harness lives in `joule-code-rs` (`joule-code-conformance`); agent-zed will run it in CI against the published pack | **Pending** (CI wiring) |
| §7 Collaboration | federated, ownerless multi-endpoint editing | not in scope for the v0.1 single-endpoint surface; classified Research in the SPEC | **Deferred** (Research) |

## What "reference consumer" means here

agent-zed does not have to implement every tier to be a faithful consumer of v0.1 — a runtime with only an L4 stage is conformant (SPEC §5), it has simply opted out of the cascade's energy benefit, not its rules. agent-zed's distinctive contributions to the standard are:

1. **The no-capture posture, made real and verified** — the hardest commitment to honor, demonstrated end-to-end (`PRIVACY_HARDENING.md`).
2. **A live receipt surface** — the joule meter is a real `Receipt` emitter wired to real traffic, with honest provenance labeling, not a mock.

The roadmap from here (cascade lower tiers, measured energy, per-operation cargo, CI conformance) is tracked against the standard's own `ROADMAP.md`.

## Live validation (Phase 3c)

The full cascade was validated end-to-end against a real Claude Code turn:

1. `cmd-alt-1` connects Claude Code over ACP ("Connected to Claude Code").
2. Prompt "create hello.txt …" → Claude emits a Write tool call with a diff.
3. agent-zed captures it as a real `CodingOp` and shows `op b3:Ynpl53wU4pwfokr… · 1 edit · L4` — a genuine BLAKE3 content address from real agent output (the §2/§3 cargo gap, closed).
4. Repeating the identical request → `⚡ L0 cache hit — closed at L0 (…), no agent launched`; the conversation is unchanged. **Stop-at-first-close, proven live: L4 on first request, L0 on the repeat.**

## Known interaction: registry agents vs. the no-phone-home posture

A `type: "registry"` ACP agent (e.g. `claude-acp`) resolves its launch command from the on-disk ACP registry catalog. The Step-4 privacy hardening disables the registry's automatic network fetch, so on a **fresh** profile the catalog is empty and `connect` fails with "Custom agent server … is not registered". This is expected, not a bug: the catalog is populated by either an **explicit, user-initiated** registry refresh (allowed — it is not a background phone-home) or by configuring the agent as `type: "custom"` with an explicit command (no registry needed). The conflict is inherent to "no unprompted egress" + "registry-resolved agents"; the standard's stance is that catalog population must be an explicit act.

## Upstream

agent-zed is a hard fork of the [Zed](https://zed.dev) editor and inherits its GPL-3.0-or-later licence. See [`LICENSE-GPL`](LICENSE-GPL) and the upstream notice in [`README.md`](README.md). The Joule Code standard and its `joule-code-rs` library are separately and permissively licensed (Apache-2.0 / CC-BY-4.0); a GPL reference editor consuming a permissive standard is intentional.