open-standards/jouledesk/SPEC.md

Joule Desk — The Open, Energy-Accounted Agent Teammate

Version: 0.1.0-draft.1 · Status: Draft · Profile: jouledesk/1 Specification text: CC-BY-4.0 · Reference code (jouledesk-rs/): Apache-2.0

Joule Desk is the open standard for a persistent agent teammate you delegate to in a shared channel — the shape a proprietary "tag @the-assistant in Slack" product made familiar — built with the properties that shape needs and a closed product cannot give you: authority that is a signed, enforced grant rather than an admin setting, work that is energy-metered and attested, and a shared, signed ledger the whole channel can verify rather than merely watch.

You add @joule to a channel. An administrator issues it a grant chain — the tools and data it may touch, and a joule budget. Any member tags @joule to delegate a task; it decides every action against those grants outside the model, runs the work in an attested sandbox, meters the energy, and seals every decision and every completed unit to the channel's ledger. Everyone in the channel can not only see what it did — they can verify it: which principal, under which capability, at what energy cost, with a signature that holds up.

Joule Desk is the collaboration/teammate binding of Joule Table (jt.transaction.science) — the umbrella standard for a metered, gated, attested agent at every surface; its sibling binding Joule Hook covers coding editors, and Joule Desk's own editor class is Joule Hook. Joule Desk is one of the Transaction Science open standards. It does not reinvent; it composes the siblings — JCP (identity, grants, the shared channel, orchestration), jcp-efficiency (the energy receipt), Sandbox (attested execution), and, where the teammate works in an editor, Joule Hook.

---

§1 Why Joule Desk exists

The agent-teammate shape is right: a persistent principal, tagged in a shared space, that plans and executes delegated work under scoped access. But in its proprietary form three things are weaker than the shape deserves:

• Authority is configured, not enforced. "These tools, this data, in this channel" is an admin setting a relying party has to trust. Nothing outside the model decides each action against a capability, and nothing proves afterward what the agent was allowed to do.
• The work is unmeasured. When a teammate produces the majority of a team's output, "did it work" is the wrong question; "what did it cost per completed unit, and where is the waste" is the right one — and there is no energy figure.
• The audit is visibility, not verifiability. Everyone can watch the agent work; no one can verify, later and independently, that a given action happened under a given authority at a given cost.

Joule Desk closes all three: the authority is a JCP grant decided outside the model and sealed; the work carries an efficiency/1 receipt; the channel keeps a signed ledger anyone holding the steward key can verify.

---

§2 The teammate

@joule is a persistent principal — a stable did:key identity, not a session — advertised by an agent card (§jcp-a2a) listing the skills it offers. The same identity persists across tasks and across restarts, so its ledger is one continuous, attributable chain. A deployment MAY run several teammates in a channel; each is a distinct principal with its own card, grants, and ledger head.

---

§3 The channel and its grants

A channel binds the teammate and its human members over a shared JCP channel (§jcp-channel). It has:

• an administrator who issues the teammate a grant chain — a set of [SignedGrant]s, each content-addressed to a (surface, tool/skill) audience and carrying a joule budget;
• a set of members authorized to delegate;
• a steward who seals the ledger (§5) and whose public key verifies it.

The grant chain is the whole access model, and it is enforceable and portable: a tool or datum the chain does not name is denied, whoever asks and however the request was phrased. Reducing a teammate's authority is re-issuing (or revoking) grants, not editing a console — and the change is itself a sealed, dated event.

---

§4 The tag → the delegation loop

Tagging @joule with an intent submits a task (§jcp-orchestrate). For each task the teammate, in order:

1. Authorises each action against its channel grants, in the runtime, never in the model (JCP): the action's content-addressed resource MUST be permitted by a held capability, and the grant's joule budget MUST cover the action's estimated cost. A failure denies before any side effect.
2. Executes the admitted work in an attested sandbox (Sandbox S-tier), so what ran is verifiable, not merely reported.
3. Meters the energy the work consumed (honest provenance).
4. Seals every dispatched decision — the allow, and any grant-level deny — and every completed unit to the ledger (§5), debiting the budget on allow. (A tag the teammate holds no skill or budget for is refused at routing; see §5.)

Retries are bounded and every attempt is charged (§jcp-orchestrate): a task that never completes is spend the ledger attributes to no result, not silent loss.

---

§5 The shared ledger

Every dispatched decision seals to the channel's ledger as an independently-signed JCR-1 receipt — the allow that ran, and any grant-level deny. Alongside them the ledger carries the efficiency/1 receipt per completed unit (§6) and the grant events (issuance, revocation) that change the teammate's authority. A tag for a skill the teammate does not hold, or one with no remaining budget, is refused at routing — enforced and recorded as a denied outcome before any dispatch; sealing that refusal as a receipt too is a conformant extension.

The ledger is the multiplayer surface. Any member — and any third party holding the steward's public key — can verify it receipt by receipt: that each is signed by the steward, and therefore which principal did what, under which capability, at what energy cost, and in what order. That is the difference from a product where the work is merely visible: here it is non-repudiable and independently checkable. A deployment MAY seal the ledger in the chained form (tamper-evident ordering) where it wants the order itself — not only each entry — to be provable.

---

§6 Energy accounting

Each task that runs seals an efficiency/1 receipt (§jcp-efficiency) carrying its energy at honest provenance and its outcome anchor (completed). Rolled up (aggregate), a channel's ledger yields the figure a teammate's ROI actually turns on — joules per completed, verified unit — which charges the wasted energy of the tasks that ran but never completed against the results actually delivered. That is the number a "tasks handled" count hides. Where a skill's work is itself token-based (an LLM skill), the receipt also carries the per-token figures (µJ per accepted token, tokens per completed unit, waste fraction); for a general task, joules-per-completed- unit is the honest headline. The teammate's contribution is metered, not asserted: each task's figure carries the grade of the meter that produced it — a hardware reading only where a live counter read the task, otherwise an estimate, graded as one — and a rollup is no better than the weakest figure it sums.

---

§7 Settlement

The teammate's spend rides a settle-able channel (§jcp-channel): members and the administrator exchange signed statements and settle, so the shared budget is reconciled — who authorised what, what was spent, what remains — with an overdraft that is bounded and enforced, not discovered on an invoice. A joule budget here is a debited, settle-able quantity, the same object as the capability that spends it (JCP).

---

§8 Host bindings (the collaboration surface)

Joule Desk is surface-agnostic. A binding maps a collaboration surface's primitives onto the loop: "a member mentions @joule" → a task (§4), and the ledger (§5) → a view the members can read and verify. Conformance profiles per surface:

Profile	Surface	Tag	Ledger view
chat	a team chat (channels + mentions)	@joule <intent>	pinned/threaded receipts
forge	a git forge (issues/PRs)	@joule on an issue/PR	a checks/receipts view
editor	a coding editor via JouleHook	the editor's agent surface	JouleHook's receipt surface
api	a service	a task submission	the receipt log / MCP

A binding MUST NOT weaken the loop: it maps the surface, it does not move the decision into the model or drop the sealing.

The reference jouledesk-bind implements the chat profile for Slack, Discord, and Matrix, and the forge profile for GitHub and GitLab (plus a neutral {who,text} shape any other service maps onto), each as a thin event-parse + reply-render pair; the editor profile is JouleHook. Parsing the event and rendering the reply are pure and testable offline; delivering the reply is the operator's token/webhook wiring.

§8.1 The real-time (media) binding class

The bindings above are discrete-message: a mention becomes a task, and the reply is a message. A @joule that joins a live voice/video room — Zoom, Google Meet, Microsoft Teams, or a LiveKit/WebRTC room — is a different loop, because the work is a continuous session, not one task per mention. A real-time binding is four seams:

1. Join the room under a signed grant (the JOIN seam). The room's own admission credential — a LiveKit access token / RoomAgentDispatch, a Zoom RTMS handshake, a Teams calling permission — is where the capability already lives; a conformant binding fuses it with the grant's joule ceiling so nothing joins without authority and budget.
2. Gate each turn outside the model (the TURN seam): a turn whose capability the grant does not hold, or that would exceed the budget, is refused before the model generates (in LiveKit, on_user_turn_completed → StopResponse), and the decision seals.
3. Meter each model call at the model-call boundary (the METER seam): a base_url proxy for a cascaded STT→LLM→TTS pipeline, a WebSocket relay for a native speech-to-speech model, or the framework's own gen_ai.usage.* telemetry. Energy is derived from token/audio counts at honest provenance — never claimed as a physical measurement. (Media that flows peer-to-peer over WebRTC/SIP bypasses the meter; there the binding gates at the token mint and reconciles from the provider's usage after.)
4. Seal one efficiency/1 receipt per session (the RECEIPT seam), anchored to the room/meeting id — the verifiable, energy-accounted record of what @joule did in the call. A signed such receipt is a superset of the compliance recording these platforms already sanction.

Profile	Surface	Join seam	Meter seam
room (reference: LiveKit)	LiveKit / WebRTC room	access token + dispatch	llm_node override / OTel gen_ai.usage
room (Zoom)	Zoom RTMS + Meeting SDK	RTMS HMAC handshake + OAuth scope	RTMS socket / AI Studio tokens
room (Teams)	Graph Cloud Comms media bot	Calls.AccessMedia + RSC	per media-frame + STT/LLM

The reference RealtimeSession (jouledesk-rs) models the four seams; its METER seam reuses the same model-call proxy that meters a text session, so a joule ceiling is enforced identically whether @joule is typing or talking.

---

§9 What Joule Desk adds over a closed teammate

Property	Closed teammate	Joule Desk
Authority	admin configuration, trusted	a signed grant, decided outside the model, enforced
Access change	a console edit	a sealed, dated grant event
Work integrity	reported	attested (Sandbox)
Energy	none	efficiency/1 — µJ + cost per completed unit + waste
Audit	visible	verifiable — a signed ledger anyone can check
Budget	a quota	a debited, settle-able joule budget (§7)
Portability	one product	any surface, one standard (§8)
Openness	proprietary	forkable — the wire and the right to fork are public

---

§10 Relationship to the sibling standards

Joule Desk is a profile that composes, not a re-implementation:

• JCP supplies identity (Did), the grant model, the shared channel (jcp-channel), and orchestration (jcp-orchestrate); Joule Desk binds them to the teammate-in-a-channel shape and the tag→delegate loop.
• jcp-a2a supplies the teammate's advertised agent card and budget mandate.
• jcp-efficiency is the energy receipt the ledger carries per completed unit.
• Sandbox is where admitted work runs, attested.
• JouleHook is the editor binding — when the teammate works in a coding editor, its tool calls ride JouleHook's gate + meter + receipt seams.

The contribution of Joule Desk is the normative teammate-in-a-channel profile — the persistent principal, the channel grant chain, the tag→delegate→attest→meter→seal loop, and the shared verifiable ledger — that turns a pile of primitives into an accountable, energy-native teammate anyone can run and verify.