2426b7662c
The gate has been red on main independent of any feature work. Three hits: - jouledesk/README.md — "8 tests", a real codebase-count. Dropped; the sentence describes the teammate loop fine without it. - jcp-efficiency/MAPPING.md ×2 — false positives. The scanner's regex reads "509 adapter" out of "X.509 adapter" as a count, but X.509 is the ITU-T certificate standard's name. Marked with the scanner's own `<!-- allow-vanity: ... -->` opt-out, which is exactly what it is for. Scanner now passes clean across every Markdown file. Co-Authored-By: Claude Opus 4.8 <[email protected]>
84 lines
4.8 KiB
Markdown
84 lines
4.8 KiB
Markdown
# 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.
|