diet-guard/docs/DOCS-claude-relay.md
Krzysztof kuhy Rudnicki e6322f7f3e Serialise the relay's log writers
The narrow pull, the log write and the publish each read, merge and write
the food log. Run at once (a publish in flight while a second request
logs) they lose the append: the phone is told "logged" and the only copy
is gone. The new race test lost an entry before this change (1 of 2) and
keeps both after it; the shared temp-file name of the log writer also
collided between threads.

One asyncio lock now covers the pull, "resolve slot + log" and the
publish. A request arriving during a publish waits for it (up to one full
tick); the model call stays outside the lock.

Also: a test that the relay unlocks the header diet_guard's devices store
wrote (same key, a blob sealed by one opens on the other), the skill
returns grams 0 for nothing to estimate (parse fails closed, nothing is
logged), and the doc's session note is corrected: the pull and publish
refresh the gate's session file as the CLI's publish does.

Failure paths: a lost append is now impossible in-process (fail closed by
waiting); the pull failure, locked key, estimator and cleanup paths are
unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWZHWP4KZ6x5TcXDBFC
2026-11-17 21:21:05 +01:00

243 lines
12 KiB
Markdown

# The "send to Claude" relay (contract)
The phone sends a food description and/or a photo. A worker on the PC runs
Claude on kuhy's Max subscription, **logs the meal at once (no review)** and
answers the phone. Transport is Firebase RTDB through the shared
`rtdb_relay` package (`kuhyx/utils`, tag `rtdb-relay-v0.1.1`), the same wire
format as the tutor app. No VPN, no open port, only kuhy's Google account.
This file is the contract both halves build against. The fixture
`tests/fixtures/claude_relay_contract.json` is read by the Python tests and
by the phone's Dart tests, so the two cannot drift. Regenerate it with
`scripts/build_claude_relay_fixture.py` (random nonces: bytes change, the
plaintext does not). The worker lives in `diet_guard/_claude_*.py` (`_claude_worker.py` serves,
`_claude_log.py` picks the slot and writes, `_claude_estimate.py` calls the
model); the estimator and its skill are described at the end.
## 1. Where it lives in RTDB
Root `R = diet-guard-sync/claude-e2e`. It is `E2eLayout.of("diet-guard-sync/claude")`,
chosen so its header path is **the existing header `diet-guard-sync/e2e`**,
the one `E2eLayout.of("diet-guard-sync/devices")` already uses. Same
passphrase, same Argon2id salt, same key: the phone unlocks nothing new. A
test asserts the two header paths are equal; a second header would be a
second salt and the phone could not open a request.
| Path under `R` | Writer | Value |
|---|---|---|
| `requests/{rid}/req` | phone | sealed unit, clear sibling `created` |
| `requests/{rid}/claim` | worker | clear `{by, lease_until, attempt, phase, at}` |
| `requests/{rid}/result` | worker | sealed unit, clear sibling `at` |
Every other path is refused by the sealer (fail closed). A sealed unit is
`{"_e2e": <blob>, <clear siblings>}`; the blob is crdt_sync's `E2eCipher`
over compact JSON with the unit's full path (`R/requests/{rid}/req`) as AAD,
so a blob copied to another path does not open. Byte format:
`~/src/utils/rtdb_relay/rtdb_relay/tests/data/e2e_vectors.json`. Both
`req` and `result` are sealed, **the photo included**: no food text or image
is ever in clear.
`rid` is a **ULID** (`[0-9A-HJKMNP-TV-Z]{26}`), not a uuid. `rtdb_relay`
never serves any other key, so a uuid-keyed request would sit unanswered
forever. This is a deliberate deviation from the first sketch ("id (uuid)");
the rid is the request's `id`.
## 2. Request (`requests/{rid}/req`)
Plaintext before sealing:
```json
{"kind": "meal", "dev": "<phone device id>", "sent_at": 1767225600000,
"body": {"text": "2 jajka sadzone i kromka chleba",
"photo_jpeg_b64": "<base64>", "client_slot_min": 720, "mode": "due"}}
```
plus the **clear** sibling `created` = `{".sv": "timestamp"}` (RTDB server
time, ms). `created`, not `sent_at`, drives the 24 h rule: a phone clock can
be wrong.
| Field | Rule |
|---|---|
| `kind` | exactly `"meal"`; anything else -> `unknown_kind` |
| `body.text` | optional string, 1..2000 chars after trim |
| `body.photo_jpeg_b64` | optional standard base64 of a JPEG (starts `FFD8`), longest side <= ~1024 px, <= 600 000 base64 chars |
| `body.client_slot_min` | required int 0..1439: the slot the phone would use now (its own `slotForLog`) |
| `body.mode` | required: `"due"` or `"normal"` |
At least one of `text` / `photo_jpeg_b64` is required. An invalid body gets
`bad_request` (below) and nothing is logged. The phone downsizes and
re-encodes the photo before sealing (the raw camera file is several MB).
## 3. Result (`requests/{rid}/result`)
`ok` is authoritative. Every result the meal handler writes also carries
`status` (`"logged"` | `"error"`); the two guard failures `unsealed` and
`unknown_kind` come from `rtdb_relay` before the handler and carry only
`ok: false`, so a client reads `status = ok ? "logged" : "error"`.
Logged (clear sibling `at` = server ms):
```json
{"ok": true, "kind": "meal", "status": "logged", "id": "<rid>",
"entry_id": "<uuid5 of rid>", "desc": "2 jajka sadzone i kromka chleba",
"grams": 190, "kcal": 410, "protein_g": 17.5, "carbs_g": 22, "fat_g": 26,
"slot_min": 720, "time": "2026-11-17T12:03:41+01:00"}
```
Error:
```json
{"ok": false, "kind": "meal", "status": "error", "id": "<rid>",
"error_code": "estimate_failed", "code": "estimate_failed",
"error": "model returned no valid JSON", "retry": true}
```
`code` and `error_code` are the same string (`code` is `rtdb_relay`'s name,
`error_code` the phone-facing one). `error` is for the log, never the UI.
| `code` | Meaning | `retry` |
|---|---|---|
| `bad_request` | body fails section 2 | false |
| `expired` | `created` older than 24 h (or missing) when the PC got to it | false |
| `estimate_timeout` | Claude exceeded 45 s | true |
| `estimate_failed` | Claude errored or the CLI/login is unusable | true |
| `estimate_invalid` | output not JSON / fails the schema / nonsense values | true |
| `unsealed`, `unknown_kind` | `rtdb_relay` guards | false |
| `internal` | a bug in the handler (visible, never a silent drop) | true |
**No answer is not an error.** If the PC cannot sync or the e2e key is
locked (`SyncError`, `E2eLockedError`, wrong or missing passphrase) the
worker writes nothing, leaves the request pending, logs why, and tries
again (section 6). The phone keeps its hourglass.
## 4. The slot
The PC decides; `client_slot_min` is never trusted in due mode. All maths
reuse `_slots.py` and `_gate.due_slots`; this feature changes none of it.
- **`"due"`**: after a narrow `pull_peer_logs()`, the entry's slot is
`due_slots(now)[0]`, the **oldest** elapsed-but-unlogged slot of today
(so a phone meal already logged elsewhere is seen). `client_slot_min` is
ignored.
- **`"due"` with nothing due** (already logged elsewhere, free day, sick
day, hold, or outside the enforcement window): not an error. Fall back to
`slot_for_log(now, schedule)`, the rule `ate` uses.
- **`"normal"`**: `nearest_slot(client_slot_min, schedule)`, the existing
nearest-slot rule, so a request that waited hours for a switched-off PC
still lands in the slot the phone saw when it was sent.
The entry's `time` is the processing time (`log_meal` forbids the past), and
`source` is `"claude"`. The logged slot is echoed as `slot_min`.
## 5. Order of work and why
```
phone: PUT req ──────────────────────────────────────────────────────────┐
PC: claim (ETag lease) -> validate -> age check -> already logged? -> │
narrow pull_peer_logs -> Claude estimate -> slot -> log_meal -> │
PUT result -> DELETE req -> publish_after_log (background) <────────┘
```
1. **Idempotent by request id, twice over.** The entry id is
`uuid5(NAMESPACE, rid)`, written with `log_meal_as`. Before spending a
Claude call the worker looks for that id with `find_entry` in the raw log
(tombstones included). Found: it rebuilds the
result from the entry and logs nothing. So a duplicate SSE event, a lease
that expired, or a crash between `log_meal` and the result PUT (the
worker takes over its own dead claim on restart) all end in one entry.
2. **Pull before Claude.** `pull_peer_logs()` (the narrow one, ~84 ms) fails
closed. A failure means "do nothing" (section 3) before any model cost.
3. **Answer first, publish last.** `publish_after_log` is a full sync tick
(15 to 27 s). Run before the answer it would break the 30 s target, so
the order is log, result, delete `req`, then publish. The result already
carries everything the phone shows; the entry itself reaches the phone's
log through the normal sync a moment later. A failed publish is only
logged: the entry is durable locally and the next tick or lock carries it.
4. **Delete only `req`.** The photo is the heavy part and is useless after
the answer. `claim` and `result` stay so a phone that was offline when
the result landed still reads it. The phone should delete
`requests/{rid}` once it has shown the answer; the worker deletes any
answered node whose `result.at` is older than 24 h.
5. **Expiry.** A request whose `created` is older than 24 h when the worker
reaches it gets `expired` and nothing is logged; its `req` is deleted
like any other.
6. **Blocking work** (log file, sync, Claude) never runs on the event loop.
**One lock** covers everything that reads, merges and writes the food log:
the narrow pull, "resolve slot + `log_meal_as`", and the publish. Two of
them at once lose an append (a publish writing back a log read before a
second request's entry) and the phone would already have been told
"logged". The price: a request that arrives during a publish waits for it,
up to one full tick (15 to 27 s) before its own pull. The model call
itself runs outside the lock.
## 6. The worker
`python -m diet_guard claude-worker`, run by `diet-guard-claude.service`
(systemd `--user`, `Restart=on-failure`, `WantedBy=default.target`; the
unit lives at the repo root with the other two, `install.sh` installs it).
- Event-driven: one SSE stream on `R/requests`. Reconnects forever with
1/2/5/10/30 s backoff; `auth_revoked` reconnects at once; `cancel` (the
rules now refuse the path) is fatal. Each reconnect begins with the whole
node, so requests that arrived while the PC was off are served in order.
- Waits are only for faults: the e2e unlock and a failed pre-pull retry
every 60 s / 30 s while something is pending. No idle timer.
- Session: the RTDB stream uses its own Firebase app name `diet_guard_claude`
(`~/.config/diet_guard_claude/firebase_auth.json`), so the stream never
shares a refresh token file with another process. Seed once, see "Deploy".
The pull and publish go through the ordinary sync client, so the worker
also refreshes the gate's `~/.config/diet_guard/firebase_auth.json`,
exactly as the CLI's own publish does. The database URL and API key come
from `~/.config/crdt-sync/firebase.json`; the passphrase from
`~/.config/crdt-sync/password`.
- One worker per PC. Claim leases last 300 s and renew every 60 s.
- Dependencies (`rtdb_relay`, `httpx`, `claude_agent_sdk`) are imported only
inside the worker's own modules, never by the gate or the CLI at load
time. System Python needs them before the unit starts (see "Deploy").
## 7. Security rules
`~/src/utils/firebase/database.rules.json` pins the **whole database** to
kuhy's uid (`.read` and `.write` on the root: `auth != null && auth.uid ===
<uid>`). `R` is a path inside that database, so **the existing rules already
cover it and no rules change is needed**. The tutor already runs under the
same rule at `tutor/v1-e2e`. The local rendered copy
(`~/.config/crdt-sync/database.rules.json`) matches that shape; the live
console copy could not be read without a signed-in uid (check with an
unauthenticated `curl "$DATABASE_URL/.json"`: must answer
`Permission denied`). A stranger who signs up with the public API key reads
and writes nothing. The worker's session must be kuhy's own account.
## 8. The estimator and its skill
`diet_guard/_claude_estimate.py` exposes the pure function
`estimate_meal(text: str | None, photo: bytes | None) -> Estimate` (also for
the Tk gate later). It runs Claude through `claude_agent_sdk` with an
**isolated `CLAUDE_CONFIG_DIR`** holding only a copy of the OAuth access
token (no refresh token) and `skills/diet-food/SKILL.md`. kuhy's own
`~/.claude` is never read except to copy the token: its hooks would make the
model answer with a grilling round.
- Input: the text, the photo as an image content block, and the closest
rows of the curated and derived food banks (`search_foods(text)`; for a
photo-only request the top rows by count).
- Output: strict JSON, enforced by `output_format` json_schema and
re-validated: `desc`, `grams` (>0), `kcal`, `protein_g`, `carbs_g`,
`fat_g` (all finite, >= 0, kcal <= 5000), optional `components`. Anything
else is `estimate_invalid`.
- Failure, timeout, invalid JSON or a missing login: an error result and
**nothing is logged** (fail closed).
## 9. Deploy (not done by the implementation)
1. `/usr/bin/python3 -m pip install --user --break-system-packages -e .`
from `~/src/diet-guard` (new deps: `claude-agent-sdk`, `rtdb-relay`,
`httpx`); verify `/usr/bin/python3 -c "import claude_agent_sdk, rtdb_relay, httpx"`.
2. Seed the worker's session once (one Google consent):
`python3 -m tool.seed_session --client-id ... --client-secret ... --app diet_guard_claude`
in `~/src/utils/crdt-sync`.
3. `bash install.sh` (copies and enables `diet-guard-claude.service` once
the session file exists).
4. Phone side: the sender, hourglass state and result screen. They follow
sections 1 to 3 and the fixture.