mirror of
https://github.com/kuhyx/diet-guard.git
synced 2026-11-19 05:54:33 +01:00
check_patch_targets reads PEP 562 _LAZY_ATTRS tables when a module cannot import under the hook python. Bumps gatelock 0.15.0, rtdb-relay 0.2.0 (Python side unchanged), gradle 9.9.1. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
240 lines
12 KiB
Markdown
240 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.2.0`), 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 worker shares the sync's own Firebase session,
|
|
`~/.config/diet_guard/firebase_auth.json` (app name `diet_guard`); there is
|
|
no separate seed. Sharing is safe: the worker's pull and publish already go
|
|
through the ordinary sync client and refresh that file, Firebase keeps an
|
|
older refresh token valid after a refresh, and crdt-sync's
|
|
`FileCredentialStore` saves atomically under a unique temp name for exactly
|
|
this several-process case. 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. `bash install.sh` (copies and enables `diet-guard-claude.service` once
|
|
the sync session file exists; no Google consent needed).
|
|
3. Phone side: [DOCS-claude-relay-phone.md](DOCS-claude-relay-phone.md).
|