diet-guard/docs/DOCS-claude-relay.md
Krzysztof kuhy Rudnicki 642467dc1d Add the Claude relay worker
python -m diet_guard claude-worker serves the phone's meal requests from
RTDB (rtdb_relay RequestServer, one SSE stream, reconnects with backoff):
validate, estimate with Claude, log through the signed log with
source=claude under the oldest due slot (normal mode: nearest slot of the
phone's hint), write the sealed result, delete only the request payload,
then publish in the background. diet-guard-claude.service (Restart=on-failure,
WantedBy=default.target) is installed by install.sh and started once the
worker's own Firebase session exists. Nothing is deployed by this commit.

Failure paths:
- narrow peer pull fails (sync locked/unreachable): fail closed, no claim, no
  answer, no model call; the request stays pending, retried every 30 s
- e2e key locked, no passphrase, no session: fail closed, nothing read or
  written; the worker waits and retries every 60 s
- bad body, request older than 24 h (or no created): fail closed, an error
  result, nothing logged
- Claude failure/timeout/invalid JSON: fail closed, an error result with
  retry, nothing logged
- crash between log and result, or a duplicate event: idempotent, the entry
  id is uuid5 of the rid and is looked up (tombstones included) before the
  model call
- request payload delete, old-answer cleanup and the post-answer publish
  failing: fail open on purpose (logged only); the answer and the local
  entry are already durable
- due mode with nothing due: falls back to slot_for_log, not an error

New log helpers log_meal_as / find_entry; log_meal's body is split into
_entry_fields / _store_entry with the same output. The gate and CLI import
none of the worker's dependencies at load time.

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

12 KiB

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:

{"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):

{"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:

{"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 serialises "resolve slot + log_meal" so two requests do not take the same due slot.

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: its own Firebase app name diet_guard_claude (~/.config/diet_guard_claude/firebase_auth.json), never the gate's diet_guard file (two processes refreshing one token file corrupt it). Seed once, see "Deploy". 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.