docs: stato del progetto e guida alla ripresa (harness+backend su main)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -0,0 +1,46 @@
|
||||
# ThothII — Stato e come riprendere
|
||||
|
||||
**Aggiornato:** 2026-06-27 (fine sessione)
|
||||
**Branch corrente:** `main` (HEAD `b909f3e`)
|
||||
|
||||
## Cosa è fatto (tutto su `main`)
|
||||
|
||||
1. **Harness** (`harness/`) — completo e RPC-ready. Piano: [docs/superpowers/plans/2026-06-27-harness-rpc-readiness.md](plans/2026-06-27-harness-rpc-readiness.md).
|
||||
2. **Backend** (`backend/`) — completo. Spec: [docs/superpowers/specs/2026-06-27-backend-design.md](specs/2026-06-27-backend-design.md). Piano: [docs/superpowers/plans/2026-06-27-backend-implementation.md](plans/2026-06-27-backend-implementation.md).
|
||||
|
||||
Entrambi sviluppati con subagent-driven development (un implementer + review per task, più review finale del branch). I branch `feat/harness-rpc-readiness` e `feat/backend-implementation` sono già merged in `main` (si possono cancellare: `git branch -d feat/harness-rpc-readiness feat/backend-implementation`).
|
||||
|
||||
## Verifica che sia tutto verde (primo comando di domani)
|
||||
|
||||
```bash
|
||||
cd ~/projects/ThothII/backend && npm test && npm run build
|
||||
cd ../harness && source .venv/bin/activate && pytest -q --ignore=tests/l2 && npm test
|
||||
```
|
||||
Atteso: backend 32 test + tsc OK; harness 233 pytest + 24 node:test.
|
||||
|
||||
## Il contratto chiave (per non perderlo)
|
||||
|
||||
Lo spike ha scoperto che il gate non poteva usare `ctx.sendRaw` (inesistente in Pi). Il **wire contract reale**: il gate emette via `ctx.ui.input(JSON.stringify(descriptor))` → Pi manda `{type:"extension_ui_request", id, method:"input", title:"<descriptor JSON>"}` → il client risponde `{type:"extension_ui_response", id, value:"<ui_response JSON>"}`. Il backend (`SessionBridge`) decodifica `title`→descriptor e ri-codifica la risposta in `value`. Il contratto verso il frontend (`ui_request`/`ui_response`) NON cambia.
|
||||
|
||||
## Due strade per riprendere (scelta rimandata)
|
||||
|
||||
### A) Validazione end-to-end con Pi reale (rischio residuo più importante)
|
||||
I test sono tutti deterministici contro `fake-pi-rpc`; il loop con **Pi reale** non è mai stato eseguito. Richiede VPN attiva + `pi` (GLM 5.2) configurato + `harness/.env` popolato + il symlink `harness/config/tht.yaml`.
|
||||
Due assunzioni da provare dal vivo: (1) il comando RPC `prompt` attiva l'`input` hook del gate; (2) Pi serializza verbatim il descriptor nel `title` di `ctx.ui.input`.
|
||||
Come: avviare il backend (`cd backend && npm run dev`), fare `POST /sessions` con una domanda reale, aprire l'SSE `GET /sessions/:id/events`, verificare che arrivi il widget F1 e che la risposta avanzi. Se fallisce, il fix è localizzato a `emitAndWait` (gate) + il `fake-pi-rpc`.
|
||||
|
||||
### B) Frontend (terzo progetto)
|
||||
Brainstorming → spec → piano del **frontend** (React/Next/ShadCn/AGGrid), come da architettura [docs/superpowers/specs/2026-06-25-thothii-architecture-design.md](specs/2026-06-25-thothii-architecture-design.md) §6. Consuma SOLO la REST+SSE del backend (contratto già stabile). Avviare con la skill `superpowers:brainstorming`.
|
||||
|
||||
## Backlog non bloccante (da chiudere quando si tocca l'area)
|
||||
|
||||
- **`GET /models`** torna `[]` di default (seam `listModels` pronto): cablare `pi --list-models` o uno spawn Pi effimero perché la tendina FE si popoli.
|
||||
- **`resume()`** manda il kickoff `/nuova-domanda` invece di `/riprendi-sessione`: per il Pi reale `spawnFor` deve poter scegliere il kickoff di ripresa (altrimenti la sessione ripresa riparte da F1).
|
||||
- **Multi-workspace lato Pi/gate**: il backend è workspace-aware, ma il gate usa il symlink `config/tht.yaml` (mono-workspace MVP). Per il multi-workspace reale il gate dovrebbe accettare un env `THT_CONFIG`/workspace.
|
||||
- **`SseHub`**: i `Set` per-sessione vuoti non vengono rimossi (leak minore su processi long-running).
|
||||
- **Copertura test** da estendere: route `steer`/`close`/404, handler SSE, percorsi `notify`/`oidc`; test gate per `/riprendi-sessione` RPC e i path di re-present di `emitAndWait` (cancel/id-mismatch/JSON-invalido).
|
||||
- `GET /sessions/:id/events` su id inattivo apre uno stream 200 vuoto invece di 404.
|
||||
|
||||
## Nota operativa
|
||||
|
||||
Il ledger di esecuzione subagent-driven è in `.git/sdd/progress.md` (non versionato): contiene la cronologia task→commit→review. Utile se serve ricostruire perché una scelta è stata fatta.
|
||||
Reference in New Issue
Block a user