# 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](../jouletable)** (`jt.transaction.science`) — the umbrella standard for a metered, gated, attested agent at *every* surface; its sibling binding [Joule Hook](../joulehook) covers coding editors, and Joule Desk's own `editor` class *is* Joule Hook. Joule Desk is one of the [Transaction Science open standards](../README.md). 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 *measured*, not asserted. --- ## §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 ` | 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.