# Joule Desk — The Open, Energy-Accounted Agent Teammate

The agent-teammate shape — a persistent principal you tag in a shared channel to
delegate work under scoped access — is the right shape. Joule Desk is the open standard
for it, with the three things that shape needs and a closed product cannot give you:

> **Authority that is a signed, enforced grant — not an admin setting. Work that is
> energy-metered and attested — not merely reported. And a shared, signed ledger
> the whole channel can *verify* — not just watch.**

You add `@joule` to a channel; an admin issues it a **grant chain** (the tools and data
it may touch, and a **joule budget**). Any member tags it 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 completed unit to a ledger
anyone can verify — which principal did what, under which capability, at what cost.

Joule Desk is the **collaboration/teammate binding of [Joule Table](../jouletable)**
(`jt.transaction.science`); its sibling binding [Joule Hook](../joulehook) covers coding
editors — and Joule Desk's own `editor` class *is* Joule Hook. It does not reinvent — it
**composes** the sibling standards: **JCP** (identity, grants, the shared channel,
orchestration), **`jcp-efficiency`** (the energy receipt), **Sandbox** (attested
execution), and **Joule Hook** (when the teammate works in a coding editor). It is one of
the [Transaction Science open standards](../README.md).

- **Licence:** Apache-2.0 for reference code ([`LICENSE`](LICENSE)); CC-BY-4.0 for the
  specification text ([`LICENSE-SPEC`](LICENSE-SPEC)).
- **Status:** v0.1.0 draft. Specification published ([`SPEC.md`](SPEC.md)); reference
  workspace `jouledesk-rs/` ships the **teammate loop** (`Teammate` + `Skill` over
  `jcp-orchestrate` + `jcp-efficiency`): grant a skill → tag it → authorise outside the
  model → seal to a per-receipt-verifiable ledger, with **`efficiency/1` energy
  accounting** (`energy_summary` → joules per completed unit, charging waste).

## What Joule Desk adds over a closed teammate

| Property | Closed teammate | Joule Desk |
|---|---|---|
| Authority | admin config, trusted | a **signed grant**, decided outside the model, enforced |
| 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 |
| Portability | one product | **any surface** (chat / forge / editor / api), one standard |

## Conformance profiles (surfaces)

`chat` (team chat + mentions) · `forge` (git issues/PRs) · `editor` (a coding editor via
[JouleHook](../joulehook)) · `api` (a service). See [`SPEC.md §8`](SPEC.md).

The reference `jouledesk-bind` binary targets real **discrete-message** services —
**Slack**, **GitHub**, **GitLab**, **Discord**, **Matrix**, and a neutral shape — each a
thin parse+render pair over one event→tag→reply transform:

```bash
echo '{"comment":{"user":{"login":"alice"},"body":"@joule summarize the thread"}}' \
  | jouledesk-bind --surface github
# → {"body":"✅ **@joule** completed it, @alice — decision sealed. _ledger: 1 decisions, all verified…_"}
```

And a **real-time (media) binding class** (`room`, [`SPEC.md §8.1`](SPEC.md)) for when
`@joule` joins a *live voice/video meeting* — Zoom, Teams, Meet, or a LiveKit/WebRTC
room. The loop is four seams — **join** under a signed grant, **gate** each turn outside
the model, **meter** each model call at the model-call boundary, **seal** one
`efficiency/1` per session anchored to the room. `RealtimeSession` (`jouledesk-rs`) is the
reference (target: **LiveKit Agents**); its meter reuses the *same* model-call proxy that
meters a text session, so the joule ceiling holds whether `@joule` is typing or talking.
`examples/room` runs a live call — turns gated outside the model, metered at the boundary,
and sealed into one verifiable session receipt.

## What's here

```
jouledesk/
├── SPEC.md          — the normative standard (§1–§10)
├── README.md        — this file
├── jouledesk-rs/     — ✅ reference implementation: the teammate loop (Teammate + Skill +
│                      parse_mention/tag_mention for the chat/forge binding, §8) over
│                      jcp-orchestrate. `examples/channel` runs a multiplayer channel;
│                      `examples/vector` regenerates the conformance vector.
└── conformance/v1/  — ✅ a byte-deterministic sealed decision receipt (summarize-allow.hex)
                        + its verified-decode target (receipt.json)
```

Transaction Science is the steward, not the proprietor: the wire and the right to fork
are public.