agent-joule/JOULE_CODE.md

agent-zed as the Joule Code reference consumer

agent-zed is the flagship consumer of the 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: 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 CodingOps. 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 editor and inherits its GPL-3.0-or-later licence. See LICENSE-GPL and the upstream notice in 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.