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:
@@ -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`.
|
||||
|
||||
Reference in New Issue
Block a user