WIP 2.0.0: AI helper plumbing (status, usage, Site settings -> AI)

The site calls AI through the Hub (protocol 3b, Hub 1.6.0): src/ai
works out whether the AI buttons show (licence token first, then the
Hub, cached a minute), runs a helper call with per-helper switches and
a per-person daily limit, logs AiCall rows, and emails admins at 80%.
v2 /ai/status, /ai/usage, /ai/settings; useAiStatus, AiButton, AiTab.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-30 09:25:36 +02:00
co-authored by Claude Opus 5.5
parent 838a6b3c3d
commit dbec47aae3
19 changed files with 1760 additions and 19 deletions
+60 -6
View File
@@ -178,6 +178,65 @@ X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3)
history. Rate-limited with update requests. A Hub older than 1.4.0 answers `404 NOT_FOUND`.
- **"Not now"** (no reminders until the next version) stays on the install; the Hub isn't told.
## 3b. AI (Cross Events 2.0, Hub 1.6.0)
Installs never hold the Claude API key. Each AI helper call goes through the Hub, which adds the
key, checks the licence's monthly cap, calls Claude and meters the call. Both requests are signed
exactly like the heartbeat. The install keeps its prompts; the Hub stores **no prompt or response
text** — only the install, helper name, tokens, cost and time.
### Status
```
POST /api/installs/ai/status
X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3)
{ "protocolVersion": 1 }
→ 200 { "enabled": true, "capReached": false, "capCents": 5000, "usedCents": 812.4,
"usedPercent": 16, "renewsOn": "2026-12-01" }
```
- **`enabled: false`** — hide the AI buttons everywhere: the licence's cap is R0, the licence isn't
active (suspended, revoked, or past its grace days), or the Hub's AI isn't set up.
- **`capReached: true`** — show the buttons **disabled** ("This month's AI allowance is used up — it
renews on 1 December"). Reached means there isn't room left for even a small call.
- Amounts are cents (rand) as **charged** to the church, with fractions (a call costs a fraction of a
cent). The month is South African time; `renewsOn` is the 1st of the next month.
### A helper call
```
POST /api/installs/ai/complete
X-Hub-Install / X-Hub-Timestamp / X-Hub-Signature (as in §3)
{
"protocolVersion": 1,
"helper": "draft_event", // lower-case name, for usage reports
"system": "…", // the helper's fixed instructions (cached by Claude)
"input": "…", // this request's text
"schema": { … }, // optional JSON schema: the reply is JSON in that shape
"maxTokens": 2000, // 1–8000
"effort": "low" // optional: low (default) | medium | high
}
→ 200 { "output": "…" | { … }, // text, or the parsed JSON when a schema was given
"usage": { "inputTokens": 1840, "outputTokens": 420 },
"chargedCents": 0.31,
"status": { …as above… } }
```
- **Errors** are `{ code, message, status }` — `status` is the new AI status, so buttons can disable
straight after the call that used up the allowance:
- `402 AI_CAP_REACHED` — this call could pass the cap (checked before calling Claude).
- `403 AI_OFF` (cap R0) · `403 LICENCE_INACTIVE` · `503 AI_NOT_CONFIGURED` (Hub not set up).
- `422 AI_REFUSED` — Claude declined. `502 AI_INCOMPLETE` — the answer hit `maxTokens`.
`502 AI_FAILED` — not usable (e.g. JSON in the wrong shape). These still cost what was used.
- `503 AI_BUSY` / `503 AI_UNAVAILABLE` — Claude unreachable or rate-limited; nothing is charged.
- `400 BAD_REQUEST`, `413 AI_INPUT_TOO_LARGE` (about 90 000 tokens), and the §3 errors.
- **Metering:** real cost = tokens × the model's price × the exchange rate set in the Hub; charged =
real × (1 + markup). The cap counts charged rand. Before calling Claude the Hub holds the worst
case (an over-estimate of the prompt, plus `maxTokens`) against the cap in one transaction per
install, so calls at the same moment can't pass it; afterwards the hold becomes the real amount.
- Rate-limited to 60 a minute per IP (against runaway loops; money is limited by the cap).
- A Hub older than 1.6.0 answers `404 NOT_FOUND`: the install treats that as "AI off".
## 4. Licence token
`hel1.<payload>.<signature>` — `payload` is base64url JSON, `signature` is the base64url
@@ -195,7 +254,7 @@ Ed25519 signature of the ASCII string `hel1.<payload>`.
"graceDays": 14,
"issuedAt": "2026-10-24T08:15:00.000Z",
"validUntil": "2026-11-23T08:15:00.000Z", // issuedAt + 30 days
"limits": { "aiMonthlyCapCents": 0 }
"limits": { "aiMonthlyCapCents": 0 } // the AI cap (§3b); 0 = AI off
}
```
@@ -221,8 +280,3 @@ grace starts). Blocking the Hub can't keep a suspended licence active for more t
fields to a heartbeat or a token doesn't need a new version — both sides ignore fields they
don't know.
- The Hub accepts protocol `N` and `N-1`; anything else is `400 UNSUPPORTED_PROTOCOL`.
## 6. Later (not in v1)
- **AI proxy** (Cross Events 2.0): `POST /api/ai/complete`, signed like the heartbeat; the Hub holds
the Claude API key, meters each call in rand and enforces `limits.aiMonthlyCapCents`.