767 lines
60 KiB
Markdown
767 lines
60 KiB
Markdown
# SPEC TRANSPORT — Contrat dispatch / ack / retry / orphan / resume
|
||
|
||
**Date :** 2026-05-24
|
||
**Auteur :** Claude (recherche dispatchée, lecture seule sur code)
|
||
**Statut :** spécification contractuelle. Aucune modif code. Toutes les sections sont en tables ou state machines, prose minimale.
|
||
**Pré-requis :**
|
||
- `docs/recherche/AXE_B1_REPLAY_TRANSPORT.md` (transport SSE/WebSocket — choix techno)
|
||
- `docs/recherche/AXE_B1_DEEP_WATCHDOG.md` (implémentation watchdog)
|
||
- `docs/REPLAY_BLOCAGE_NOTES_MEDICALES_2026-05-08.md` (bug 9 actions perdues)
|
||
- `docs/SYNTHESE_TECHNOS_REPLAY_2026-05-23.md` §4
|
||
|
||
Ce doc fige **le contrat** entre `api_stream.py` (FastAPI Linux) et `agent_v1/core/executor.py` + `agent_v1/network/streamer.py` (Léa Windows). Il est **isomorphe poll ↔ SSE** (cf. §9).
|
||
|
||
---
|
||
|
||
## 1. TL;DR + diagramme d'ensemble
|
||
|
||
Une action visuelle est un **message borné par 2 IDs** : `action_id` (unique par step de replay, déterministe) + `attempt_id` (UUID, incrémenté à chaque re-dispatch transport). Le serveur tient une **mini-visibility-timeout in-memory** (`_retry_pending`). Le client tient un **LRU `dedup_set`** des `attempt_id` récemment exécutés. La pause supervisée (`paused_need_help`) est l'état absorbant en cas d'épuisement des essais ou de signal explicite (`system_dialog`, `wrong_window`, `target_not_found`). Le contrat est identique en polling (transport actuel) et en SSE (cible AXE_B1).
|
||
|
||
```
|
||
┌───────────── server (Linux, FastAPI :5005) ─────────────┐
|
||
│ │
|
||
_replay_queues │ ┌──────────┐ DISPATCH ┌─────────────┐ │
|
||
[session_id] │ │ PENDING │ ──────────────►│ DISPATCHED │ │
|
||
│ └──────────┘ │ (_retry_ │ │
|
||
│ ▲ │ pending) │ │
|
||
│ │ repush head └─────┬───────┘ │
|
||
│ │ (watchdog) │ REPORT(success) │
|
||
│ ┌────┴─────┐ age>30s, resent │ verify OK │
|
||
│ │ ORPHAN │ ◄─── timeout ◄────────┤ │
|
||
│ │ (resent_ │ │ │
|
||
│ │ count++)│ ▼ │
|
||
│ └──────────┘ ┌──────────┐ │
|
||
│ │ resent ≥ MAX │ ACKED │ │
|
||
│ ▼ └──────────┘ │
|
||
│ ┌──────────┐ REPORT(fail+system_dialog/wrong_window) │
|
||
│ │ ABANDONED│◄──┬────────────────┐ │
|
||
│ └──────────┘ │ │ │
|
||
│ │ ▼ ▼ │
|
||
│ │ ┌──────────────┐ ┌──────────┐ │
|
||
│ └──►│ PAUSE_NEED_ │ │ FAILED │ │
|
||
│ │ HELP │ │ (retry │ │
|
||
│ └─────┬────────┘ │ budget │ │
|
||
│ │ /resume │ out) │ │
|
||
│ ▼ └──────────┘ │
|
||
│ (resume_action en tête queue) │
|
||
└──────────────────────────────────────────────────────────┘
|
||
▲ │
|
||
│ POST /replay/result │ GET /replay/next (poll)
|
||
│ │ ou SSE event
|
||
│ ▼
|
||
┌───────────┴──────────── client Léa (Windows) ────────────┐
|
||
│ ┌──────────┐ parse ┌──────────┐ execute_replay_ │
|
||
│ │ RECEIVED │──────────►│ DEDUP │ action() │
|
||
│ └──────────┘ │ CHECK │ │
|
||
│ └────┬─────┘ │
|
||
│ hit LRU │ miss │
|
||
│ │ ▼ │
|
||
│ │ ┌──────────┐ │
|
||
│ │ │EXECUTING │ │
|
||
│ │ └────┬─────┘ │
|
||
│ ▼ ▼ │
|
||
│ ┌──────────────┐ │
|
||
│ │ REPORTING │ → POST /replay/result │
|
||
│ └──────────────┘ │
|
||
└──────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 2. State machine serveur — une action dans `_retry_pending`
|
||
|
||
```
|
||
start
|
||
│
|
||
▼
|
||
┌───────────────────────────────────────────────────────────────┐
|
||
│ PENDING │
|
||
│ présent dans _replay_queues[session_id], pas encore │
|
||
│ extrait par get_next_action │
|
||
└───────────────────────┬───────────────────────────────────────┘
|
||
│ get_next_action → pop queue + write
|
||
│ _retry_pending[action_id]={dispatched_at=now}
|
||
│ + log [REPLAY] DISPATCH
|
||
▼
|
||
┌───────────────────────────────────────────────────────────────┐
|
||
│ DISPATCHED │
|
||
│ dans _retry_pending, attente du REPORT │
|
||
│ invariant : action absente de _replay_queues │
|
||
└───┬───────────────────────┬───────────────────────────────────┘
|
||
│ REPORT(success=True) │ REPORT(success=False, error=*)
|
||
│ verify OK ou skip │ watchdog scan age>ORPHAN_TIMEOUT
|
||
│ │
|
||
│ pop _retry_pending │ resent_count < MAX_RESENDS
|
||
│ completed_actions++ │ → repush head + resent++
|
||
│ current_idx++ │ → dispatched_at=0
|
||
▼ │ → log [BUS] lea:dispatch_
|
||
┌────────┐ │ orphan_resent
|
||
│ ACKED │ │
|
||
│ (term) │ │ resent_count ≥ MAX_RESENDS
|
||
└────────┘ │ → pop _retry_pending
|
||
│ → log [BUS] lea:dispatch_
|
||
│ orphan_giveup
|
||
│ → ABANDONED
|
||
▼
|
||
┌─────────────────┐ watchdog repush
|
||
│ ORPHAN_RESENT │ ───────────► PENDING
|
||
│ (transitoire) │ (avec resent++)
|
||
└─────────────────┘
|
||
|
||
REPORT(verify failed AND retry_count<MAX_RETRIES_PER_ACTION):
|
||
_schedule_retry crée action_id_retry{N+1}, repush head
|
||
le nouveau action_id entre en PENDING (nouvelle entrée)
|
||
l'ancien action_id sort de DISPATCHED via pop
|
||
|
||
REPORT(system_dialog | wrong_window | target_not_found):
|
||
──► PAUSE_NEED_HELP (replay_state.status)
|
||
_retry_pending non purgé sur-le-champ (peut être réutilisé par /resume)
|
||
|
||
ABANDONED:
|
||
entrée _retry_pending supprimée
|
||
──► si politique = pause sur Nème giveup → PAUSE_NEED_HELP
|
||
sinon : action perdue, replay continue sur l'action suivante
|
||
|
||
CANCELLED (POST /replay/<id>/cancel):
|
||
purge _retry_pending par replay_id (api_stream.py:4489)
|
||
_replay_queues[session_id] = []
|
||
state.status = "cancelled"
|
||
```
|
||
|
||
**Invariants serveurs :**
|
||
|
||
| # | Invariant | Garanti par |
|
||
|---|---|---|
|
||
| I1 | Une action en `DISPATCHED` est absente de `_replay_queues` | pop atomique sous `_replay_lock` (api_stream.py:3346-3348) |
|
||
| I2 | `action_id` unique dans `_retry_pending` à un instant t | clé dict + check `if action_id_sent not in _retry_pending` (api_stream.py:3354) |
|
||
| I3 | `report_action_result.pop(action_id)` est idempotent | `pop(key, None)` retourne None si déjà acquitté (api_stream.py:3491) |
|
||
| I4 | Cancel purge bien `_retry_pending` pour ce replay | iter `_retry_pending.items() if v["replay_id"]==replay_id` (api_stream.py:4489-4491) |
|
||
| I5 | Watchdog re-check sous lock avant repush | pattern `if aid not in self._retry_pending: skip` (AXE_B1_DEEP §3) |
|
||
| I6 | Pause `paused_need_help` ne distribue aucune action | `get_next_action` retourne `replay_paused=True` (api_stream.py:2951) |
|
||
|
||
---
|
||
|
||
## 3. State machine client Léa — une action côté `executor.py`
|
||
|
||
```
|
||
┌──────────────┐
|
||
│ POLLING │ thread `_poll_loop`, every 1s (+backoff)
|
||
│ (idle) │ GET /replay/next?session_id&machine_id
|
||
└──────┬───────┘
|
||
│ HTTP 200 + action ≠ null
|
||
▼
|
||
┌──────────────┐
|
||
│ RECEIVED │ data["action"] parsé
|
||
└──────┬───────┘
|
||
│
|
||
┌───────────────┴────────────────┐
|
||
│ attempt_id ∈ dedup_set ? │
|
||
▼ ▼
|
||
OUI : SKIP NON
|
||
(log warning, ack synthetique) │
|
||
▼
|
||
┌──────────────┐
|
||
│ EXECUTING │ execute_replay_action()
|
||
│ │ ├─ pre-check window
|
||
│ │ ├─ resolve target visuel
|
||
│ │ ├─ click / type / key
|
||
│ │ └─ screenshot_after
|
||
└──────┬───────┘
|
||
│
|
||
┌─────────────────┼──────────────────┐
|
||
│ │ │
|
||
success=True success=False system_dialog
|
||
warning=None error=* détecté
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌─────────────────────────────────┐
|
||
│ REPORTING │
|
||
│ POST /replay/result + retry │
|
||
│ (timeout=10s, allow_redirects=False)
|
||
└─────────────────┬────────────────┘
|
||
│
|
||
┌──────────┴──────────┐
|
||
HTTP 200 fail/timeout
|
||
│ │
|
||
▼ ▼
|
||
┌──────────┐ ┌──────────────┐
|
||
│ ACKED │ │ REPORT_RETRY │ (PAS implémenté
|
||
│ + LRU │ │ (in-memory) │ v1 ; à v2)
|
||
│ store │ └──────┬───────┘
|
||
│ attempt │ │
|
||
│ _id │ ▼
|
||
└──────────┘ (perte report : serveur watchdog
|
||
rattrapera via orphan)
|
||
|
||
Pendant POLLING : si data.replay_paused → afficher PauseDialog
|
||
Pendant EXECUTING : timeout par étape gérée par execute_replay_action
|
||
(resolve serveur 30s, _wait_for_screen_change 1000ms+, capture 0.5s)
|
||
```
|
||
|
||
**Invariants clients :**
|
||
|
||
| # | Invariant | Garanti par |
|
||
|---|---|---|
|
||
| C1 | Une action reçue est TOUJOURS reportée (succès ou échec) | try/except global executor.py:2429-2503, fallback `result={success:False, error=…}` |
|
||
| C2 | Un seul `poll_and_execute` à la fois | `self._replay_lock.acquire(blocking=False)` executor.py:2291 |
|
||
| C3 | Pas de blocage event tray UI pendant exécution | thread dédié `_poll_loop` |
|
||
| C4 | Idempotence côté action (v2) | dedup_set LRU bornée 256 entrées sur `attempt_id` (§6.2) — **À AJOUTER** |
|
||
| C5 | Pause UI déclenchée uniquement sur signal serveur explicite | `data.get("replay_paused")` executor.py:2346 |
|
||
|
||
---
|
||
|
||
## 4. Contrats JSON
|
||
|
||
### 4.1. Payload DISPATCH serveur → client (GET /replay/next OU SSE event)
|
||
|
||
**Cas nominal : action visuelle**
|
||
|
||
| Champ | Type | Obligatoire | Description | Source code |
|
||
|---|---|---|---|---|
|
||
| `action` | object \| null | oui | l'action ou `null` si rien | api_stream.py:3436 |
|
||
| `session_id` | str | oui | session active | api_stream.py:3438 |
|
||
| `machine_id` | str | oui | machine cible | api_stream.py:3439 |
|
||
| `action.action_id` | str | oui | identifiant unique step, ex. `step_4c0663941f22` | DB workflow + suffixes `_retry1/_resume` |
|
||
| `action.attempt_id` | str | **À AJOUTER** | UUID hex 16, nouveau à chaque dispatch (initial OU resend) | n/a, v2 |
|
||
| `action.type` | enum | oui | `click`/`type`/`key_combo`/`wait`/`scroll`/`pause_for_human`/`extract_text`/... | core/executor.py:2422 |
|
||
| `action.target_spec` | object | si visuelle | `{by_text,vlm_description,anchor_image_base64,resolve_order,window_title,uia_target}` | api_stream.py:3364 |
|
||
| `action.parameters` | object | dep. type | `{text,keys,duration_ms,condition,…}` | dépend du type |
|
||
| `action.expected_window_before` | str | non | titre fenêtre attendue avant clic | api_stream.py:3366 |
|
||
| `action.expected_window_title` | str | non | titre fenêtre attendue après clic | api_stream.py:3369 |
|
||
| `action.success_strict` | bool | non | mode strict (skip OCR fuzzy) | api_stream.py:3387 |
|
||
| `action.intention` | str | non | description humaine | api_stream.py:3379 |
|
||
| `action.monitor_resolution` | object | oui (QW1) | `{idx,offset_x,offset_y,w,h,source}` | api_stream.py:3403 |
|
||
| `action.from_node` | str | non | id node WorkflowGraph (active pre-check) | api_stream.py:3229 |
|
||
| `action.dispatch_meta` | object | **À AJOUTER** | `{first_dispatched_at,resent_count,last_resent_at}` pour visibilité client | v2 |
|
||
| `precheck` | object | non | résultat pre-check serveur `{match,similarity,popup_detected}` | api_stream.py:3441 |
|
||
| `server_busy` | bool | non | lock occupé, retry plus tard | api_stream.py:2944 |
|
||
| `replay_paused` | bool | non | replay en pause supervisée | api_stream.py:2960 |
|
||
| `pause_message` | str | si paused | message à afficher dans bulle | api_stream.py:2961 |
|
||
| `replay_id` | str | si paused | pour ack ciblé via /resume | api_stream.py:2962 |
|
||
| `auth_detected` | bool | non | injection automatique d'actions d'auth | api_stream.py:3304 |
|
||
|
||
**Exemple complet (v2 cible) :**
|
||
```json
|
||
{
|
||
"action": {
|
||
"action_id": "step_4c0663941f22",
|
||
"attempt_id": "a8f3c2d1e9b4f720",
|
||
"type": "click",
|
||
"target_spec": {
|
||
"by_text": "Imagerie",
|
||
"resolve_order": ["ocr","template","vlm"],
|
||
"anchor_image_base64": "iVBORw0KGgo…",
|
||
"window_title": "MOREL Catherine — Easily Assure",
|
||
"uia_target": null
|
||
},
|
||
"parameters": {},
|
||
"expected_window_before": "MOREL Catherine — Easily Assure",
|
||
"expected_window_title": "MOREL Catherine — Easily Assure",
|
||
"success_strict": true,
|
||
"intention": "Cliquer onglet Imagerie",
|
||
"monitor_resolution": {"idx":1,"offset_x":0,"offset_y":0,"w":2560,"h":1600,"source":"action_hint"},
|
||
"from_node": "node_tab_imagerie",
|
||
"dispatch_meta": {
|
||
"first_dispatched_at": 1779015600.123,
|
||
"resent_count": 0,
|
||
"last_resent_at": 0.0
|
||
}
|
||
},
|
||
"session_id": "sess_demo_42",
|
||
"machine_id": "DESKTOP-58D5CAC"
|
||
}
|
||
```
|
||
|
||
**Cas pause supervisée :**
|
||
```json
|
||
{
|
||
"action": null,
|
||
"session_id": "sess_demo_42",
|
||
"machine_id": "DESKTOP-58D5CAC",
|
||
"replay_paused": true,
|
||
"pause_message": "Je n'y arrive pas (« Coller ou saisir... »)",
|
||
"replay_id": "replay_free_68ca51ab"
|
||
}
|
||
```
|
||
|
||
**Cas idle / server_busy :**
|
||
```json
|
||
{"action": null, "session_id":"sess_demo_42", "machine_id":"…", "server_busy": true}
|
||
```
|
||
|
||
### 4.2. Payload REPORT client → serveur (POST /replay/result)
|
||
|
||
| Champ | Type | Obligatoire | Description | Source code |
|
||
|---|---|---|---|---|
|
||
| `session_id` | str | oui | | api_stream.py:628 |
|
||
| `action_id` | str | oui | identifiant de l'action acquittée | api_stream.py:629 |
|
||
| `attempt_id` | str | **À AJOUTER** | echo du `attempt_id` reçu (corrélation watchdog ↔ client) | v2 |
|
||
| `success` | bool | oui | résultat global | api_stream.py:630 |
|
||
| `error` | str \| null | dep. success | message court (`target_not_found`, `system_dialog:uac_consent`, …) | api_stream.py:631 |
|
||
| `warning` | str \| null | non | `no_screen_change`/`popup_handled`/`visual_resolve_failed`/`wrong_window` | api_stream.py:632 |
|
||
| `screenshot_after` | str \| null | recommandé | base64 PNG ou path | api_stream.py:634 |
|
||
| `screenshot_before` | str \| null | recommandé (clic) | base64 PNG du frame pre-action (Critic) | api_stream.py:635 |
|
||
| `actual_position` | object | si visuel | `{x_pct: float, y_pct: float}` coords cliquées | api_stream.py:636 |
|
||
| `resolution_method` | str | si visuel | `server_resolve_hybrid`/`template_match`/... | api_stream.py:638 |
|
||
| `resolution_score` | float | si visuel | 0.0–1.0 | api_stream.py:639 |
|
||
| `resolution_elapsed_ms` | float | si visuel | latence cascade | api_stream.py:640 |
|
||
| `target_description` | str | si fail | description humaine pour bulle pause | api_stream.py:642 |
|
||
| `target_spec` | object | si fail | echo target_spec pour reconstruction | api_stream.py:643 |
|
||
| `correction` | object | si pédagogique | `{x_pct,y_pct,uia_snapshot,crop_b64}` mode supervisé | api_stream.py:645 |
|
||
| `system_dialog` | object | si dialog | `{category,matched_signal,matched_value,reason,context}` | api_stream.py:650 |
|
||
| `needs_human` | bool | non | force pause supervisée | api_stream.py:651 |
|
||
|
||
**Exemple succès :**
|
||
```json
|
||
{
|
||
"session_id": "sess_demo_42",
|
||
"action_id": "step_4c0663941f22",
|
||
"attempt_id": "a8f3c2d1e9b4f720",
|
||
"success": true,
|
||
"actual_position": {"x_pct":0.2305,"y_pct":0.2805},
|
||
"resolution_method": "server_resolve_hybrid_text_direct",
|
||
"resolution_score": 0.80,
|
||
"resolution_elapsed_ms": 412.7,
|
||
"screenshot_before": "iVBO…",
|
||
"screenshot_after": "iVBO…"
|
||
}
|
||
```
|
||
|
||
**Exemple échec target_not_found :**
|
||
```json
|
||
{
|
||
"session_id": "sess_demo_42",
|
||
"action_id": "step_36346c1c40b9",
|
||
"attempt_id": "b9e4d3c2f0a5e831",
|
||
"success": false,
|
||
"error": "target_not_found",
|
||
"warning": "visual_resolve_failed",
|
||
"target_description": "Coller ou saisir le dossier patient",
|
||
"target_spec": {"by_text":"Coller ou saisir le dossier patient", "…":"…"},
|
||
"screenshot_after": "iVBO…"
|
||
}
|
||
```
|
||
|
||
**Exemple system_dialog (UAC) :**
|
||
```json
|
||
{
|
||
"session_id":"sess_demo_42",
|
||
"action_id":"step_xxx",
|
||
"attempt_id":"…",
|
||
"success": false,
|
||
"error": "system_dialog:uac_consent",
|
||
"system_dialog": {
|
||
"category": "uac_consent",
|
||
"matched_signal": "window_title",
|
||
"matched_value": "Contrôle de compte d'utilisateur",
|
||
"reason": "UAC consent prompt blocking click",
|
||
"context": "handle_popup_vlm"
|
||
},
|
||
"needs_human": true,
|
||
"screenshot_after": "iVBO…"
|
||
}
|
||
```
|
||
|
||
### 4.3. Payload re-dispatch (orphan resent)
|
||
|
||
Identique au DISPATCH normal **sauf** `dispatch_meta` enrichi :
|
||
|
||
```json
|
||
{
|
||
"action": {
|
||
"action_id": "step_4c0663941f22", // INCHANGÉ
|
||
"attempt_id": "c2d5e8f1a3b7c049", // NOUVEAU (UUID frais)
|
||
"type": "click",
|
||
"...": "…",
|
||
"dispatch_meta": {
|
||
"first_dispatched_at": 1779015600.123,
|
||
"resent_count": 1,
|
||
"last_resent_at": 1779015630.987,
|
||
"resend_reason": "orphan_timeout"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Règle :** `action_id` reste stable (preserve idempotence côté serveur via `_retry_pending`). **Seul `attempt_id` change** (permet au client de distinguer un vrai re-dispatch d'un doublon réseau).
|
||
|
||
### 4.4. Payload escalation pause supervisée
|
||
|
||
Envoyé par le serveur dans la réponse au prochain poll après bascule `paused_need_help` (cf. §4.1 cas pause). Le client doit afficher la bulle et arrêter d'exécuter jusqu'à reception d'un nouveau dispatch (qui sera l'action de resume).
|
||
|
||
**Payload /replay/{replay_id}/resume (POST) :** corps optionnel `{"acknowledged_check_ids": ["chk_1","chk_2"]}` (QW4). Réponse :
|
||
```json
|
||
{
|
||
"status": "resumed",
|
||
"replay_id": "replay_free_68ca51ab",
|
||
"session_id": "sess_demo_42",
|
||
"remaining_actions": 12
|
||
}
|
||
```
|
||
|
||
**Payload /replay/{replay_id}/cancel (POST) :** corps vide. Réponse :
|
||
```json
|
||
{"status": "cancelled", "replay_id": "…", "session_id": "…"}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Matrice des cas limites — la table principale du document
|
||
|
||
Notation : **S** = état serveur (PENDING/DISPATCHED/ORPHAN/ACKED/ABANDONED/PAUSE), **C** = état client (POLLING/RECEIVED/EXECUTING/REPORTING/IDLE/DEAD).
|
||
|
||
| # | Scénario | État serveur (avant→après) | État client (avant→après) | Comportement attendu (v2 contrat) | Risque idempotence | Status code / contournement |
|
||
|---|---|---|---|---|---|---|
|
||
| **a** | Client coupe AVANT réception réponse `/replay/next` (bug 8 mai) | DISPATCHED→ORPHAN→PENDING→DISPATCHED | POLLING→POLLING (timeout) | Watchdog détecte age>30s, re-dispatch (`attempt_id` neuf, `resent_count=1`). Bulle "action retentée" facultative. | **Faible** : action_id stable, client n'a JAMAIS exécuté → pas de double-effet. | OK via AXE_B1_DEEP §3 |
|
||
| **b** | Client coupe APRÈS réception, AVANT exécution | DISPATCHED→ORPHAN→PENDING→DISPATCHED | RECEIVED→DEAD | Watchdog re-dispatch. Si client revit, reçoit nouvelle attempt → exécute. Si client mort, watchdog finit en ABANDONED. | **Faible** : action perdue avant tout effet. | OK |
|
||
| **c** | Client exécute, coupe AVANT envoi report | DISPATCHED→ORPHAN→PENDING→DISPATCHED | EXECUTING→REPORTING→DEAD (avant POST) | Watchdog re-dispatch. **2e exécution probable** côté client. Idempotence action requise (§6.3). | **ÉLEVÉ** : double clic, double saisie possibles. Cible critique : `type` → préfixer `Ctrl+A`. | dedup_set côté client (§6.2) BLOQUE la 2e si même `action_id` reçu < 256 messages |
|
||
| **d** | Client report success, serveur ne reçoit pas (HTTP 502, timeout serveur côté POST) | DISPATCHED→ORPHAN→PENDING | EXECUTING→REPORTING(echec POST)→IDLE | Client doit **retenter** le POST (boucle interne avec backoff). v1 : un seul essai (executor.py:2476 timeout=10s, pas de retry). **À AJOUTER v2** : retry 3× backoff [1,3,7]s. Sinon watchdog re-dispatch + dedup_set côté client→ack synthétique. | Moyen | À ajouter retry POST côté client |
|
||
| **e** | Client report success=false, retry budget restant | DISPATCHED→FAILED(verify)→PENDING(retry_N+1) | EXECUTING→REPORTING→POLLING | `_schedule_retry` crée nouvelle entrée `{action_id}_retry{N+1}` (replay_engine.py:2604), repush head. `verify_failed` ne consomme PAS le budget orphan. | Géré | OK |
|
||
| **f** | Watchdog re-dispatch ALORS QUE client envoie report tardif | DISPATCHED→ORPHAN→repush en cours | EXECUTING→REPORTING(en vol) | Race window. Re-check sous lock dans watchdog `if aid not in _retry_pending: skip` (AXE_B1_DEEP §3 _scan_once). Si pop arrive 1er : repush skip. Si repush arrive 1er : pop ignoré (`no_active_replay`). | Faible | Géré par I3 + I5 |
|
||
| **g** | Watchdog re-dispatch, mais client a déjà ré-exécuté (cas c+f combinés) | DISPATCHED→ORPHAN→repush | EXECUTING(1)→REPORTING(1)→RECEIVED(2)→EXECUTING(2) | dedup_set client détecte 2e `action_id` identique → log warning + ack synthétique `{success:true, warning:"already_executed"}`. **Sans dedup** : double exécution = bug applicatif. | **CRITIQUE sans dedup** | dedup_set v2 obligatoire |
|
||
| **h** | Client mort silencieux (Léa crash, NoMachine freeze) | DISPATCHED→ORPHAN→PENDING→…→ABANDONED→PAUSE | DEAD | Watchdog MAX_RESENDS=2 puis ABANDONED. **Hook v1.1** : si ≥2 give-ups en 60s sur même session → bascule replay_state.status=paused_need_help + message "Léa ne répond plus" (AXE_B1_DEEP §6 R4). | OK avec hook | À ajouter hook dead_client_signal |
|
||
| **i** | Serveur restart pendant actions en `_retry_pending` | TOUT en mémoire → PERTE | POLLING → reçoit 404 / 503 / ConnectionError | `_retry_pending` est in-memory. Au restart : queue vide, replay_state perdu (sauf si persisté en DB — vérifier). Client backoff exponentiel ; quand serveur revient, replay_state restaurable depuis SQLite mais `_retry_pending` non. **Décision v1** : rebuild best-effort — `_replay_states` sauvegardés en SQLite ont les `completed_actions`, on relance depuis `current_action_index+1`. Pas de rejeu des actions en vol. **Lacune connue** : si action mid-flight ; à valider avec Dom. | n/a (état perdu) | **À TRANCHER avec Dom** : persistance _retry_pending ? |
|
||
| **j** | Polls clients simultanés en course (2 process Léa, ou retry rapide) | DISPATCHED (1 seul vainqueur du lock) | 2× POLLING | `_replay_lock.acquire(timeout=4.5)` : 1er gagne, 2e reçoit `{server_busy:true}` (api_stream.py:2944). Client backoff. Ordre des steps préservé (lock global). | Faible | OK |
|
||
| **k** | Action arrivée 2× côté client (double-clic même bouton) | DISPATCHED (attempt_1) puis DISPATCHED (attempt_2) | RECEIVED→DEDUP_CHECK→SKIP (2e) | dedup_set client = LRU 256 sur `action_id`. 2e réception → ack synthétique success=true warning="already_executed", PAS de ré-exécution. | Bloqué côté client | dedup_set v2 |
|
||
| **l** | Pause supervisée serveur déclenchée pendant action en vol | DISPATCHED→PAUSE | EXECUTING→REPORTING (résultat ignoré côté serveur ?) | Le serveur applique la pause sur le step SUIVANT (boucle `while queue` voit `paused`). L'action en vol s'achève normalement, report traité (pop+verify), puis prochain poll → `replay_paused=true`. **PAS de cancel de l'action en vol** (pas de protocole serveur→client pour interrompre une action en cours). | Faible | OK |
|
||
| **m** | Cancel replay côté VWB UI pendant action en vol | DISPATCHED→cancelled (purge _retry_pending) | EXECUTING→REPORTING | Cancel purge `_retry_pending` par replay_id (api_stream.py:4489) ET vide `_replay_queues[session_id]`. Le report tardif arrive : `pop(action_id)→None` → réponse `no_active_replay` (api_stream.py:3488). Client log info. Pas d'erreur. | Faible | OK |
|
||
| **n** | Cap MAX_RESENDS atteint | ORPHAN→ABANDONED | DEAD ou EXECUTING (cas g) | Log `[BUS] lea:dispatch_orphan_giveup`. v1 = action perdue silencieusement, replay continue (peut bloquer step suivant si dépendance). **Politique v2 :** si action critique (type ∈ {click,type,t2a_decision}) → bascule `paused_need_help` immédiatement avec message "Léa n'a pas répondu, vérifie". Si non critique (wait,scroll) → log seul, continue. | n/a | **À TRANCHER** : seuil par type ? |
|
||
| **o** | Action non-visuelle (`extract_text`, `t2a_decision`) vs visuelle (`click`) | Non-visuelle : pas de DISPATCHED, exécutée *server-side* dans la même boucle `get_next_action` (api_stream.py:3132-3197) | Jamais reçue par le client | **Contrats distincts** : non-visuelles n'entrent JAMAIS dans `_retry_pending`. Le watchdog n'a rien à scanner pour elles. Si extract_text plante (Ollama 503), `queue.pop(0)` + log warning + continue (api_stream.py:3195) → action serveur perdue silencieusement. **Risque pas couvert par watchdog.** | n/a | **À TRANCHER** : retry serveur sur actions serveur ? séparé du watchdog actions visuelles |
|
||
| **p** | Workflow se termine alors qu'action est encore en `_retry_pending` | DISPATCHED en cours → workflow.completed | n/a | `_replay_states[replay_id].status = "completed"`. Si une action est encore en `_retry_pending`, le watchdog la verra orphan ; au resend, `get_next_action` ne trouvera pas de `owning_replay` (status `running` requis ligne 2974) → queue vide retournée. **Fuite mémoire** : entrée `_retry_pending` jamais purgée tant que pas de cancel ou age > MAX_RESENDS. **Mitigation** : ajouter purge `_retry_pending` sur transition vers completed/error/failed (analogue à cancel ligne 4489). | Faible (mais leak) | **À AJOUTER v2** : purge à la complétion |
|
||
| **q** | Précheck "wait" injecté (popup détectée) — n'est PAS une action workflow | Pas dans `_retry_pending` (action synthétique) | RECEIVED→EXECUTING(wait 2000ms)→REPORTING(success=true) | wait_action a un `action_id=precheck_wait_<6hex>` non stockée côté serveur. Le report arrive : `pop(action_id)→None`, action ignorée gracieusement. | Faible | OK |
|
||
| **r** | Replay paused, client continue à poller | PAUSE | POLLING reçoit `replay_paused:true` à chaque tick | Client affiche bulle 1 fois (dedup sur `_last_pause_msg_shown` executor.py:2351), continue à poller. CPU loss négligeable. | Faible | OK |
|
||
| **s** | Reverse-proxy NPM bufferise SSE | DISPATCHED, event jamais reçu | POLLING/SSE silencieux | `X-Accel-Buffering: no` côté server response. Ping 15s force flush. AXE_B1 §4 §8 risques. | Faible avec headers | OK avec headers |
|
||
| **t** | NoMachine timeout idle (>60s) | DISPATCHED dormant | SSE→reconnect via Last-Event-ID | sseclient-py auto-reconnect, `Last-Event-ID` header repris au reconnect → serveur peut sauter les events déjà acquittés. v1 polling : pas de Last-Event-ID, juste réacheminement via watchdog. | Faible | OK |
|
||
| **u** | Bearer token expire/révoqué pendant un replay actif | DISPATCHED en attente | POLLING reçoit 401 | Client doit re-auth (hors scope v1 : tokens longue durée). v1 : crash + tray notification. Watchdog côté serveur continue à scanner — actions partent en ABANDONED après MAX. | Faible | hors scope v1 |
|
||
|
||
---
|
||
|
||
## 6. Sémantique d'idempotence
|
||
|
||
### 6.1. Couches d'idempotence
|
||
|
||
| Couche | Mécanisme | Effet | Implémenté ? |
|
||
|---|---|---|---|
|
||
| **Serveur — pop sur report** | `_retry_pending.pop(action_id, None)` retourne None silencieux si déjà acquitté | report en double n'augmente pas `completed_actions` 2× | ✅ api_stream.py:3491 |
|
||
| **Serveur — re-check watchdog** | `if aid not in _retry_pending: skip` sous lock | re-dispatch annulé si report arrivé entre snapshot et repush | ✅ AXE_B1_DEEP §3 |
|
||
| **Serveur — cancel purge** | itération `_retry_pending` par replay_id | aucun ghost-resend après cancel | ✅ api_stream.py:4489 |
|
||
| **Action — `action_id` stable** | identifiant unique step (`step_<hex>` puis suffixes `_retry{N}` ou `_resume`) | clé du `pop` côté serveur, clé du dedup côté client | ✅ DB workflow + replay_engine.py:2609 |
|
||
| **Action — `attempt_id` rotatif** | UUID nouveau à chaque DISPATCH (initial + chaque resend) | distingue un re-dispatch légitime d'un doublon réseau, permet stats orphan | ❌ **À AJOUTER v2** |
|
||
| **Client — dedup_set LRU 256** | `set` bornée de `(action_id)` ou `(action_id, attempt_id)` récemment exécutés | bloque ré-exécution en cas g/k | ❌ **À AJOUTER v2 obligatoire** |
|
||
| **Action — idempotence intrinsèque** | clear field avant `type`, idempotence native du `click` sur tab actif | minimise dégât en cas de double exécution résiduelle | ⚠ **À documenter dans VWB**, pas dans code |
|
||
|
||
### 6.2. Spec dedup_set client (v2)
|
||
|
||
```python
|
||
# agent_v1/core/executor.py — à ajouter
|
||
from collections import OrderedDict
|
||
|
||
class ActionDedupSet:
|
||
"""LRU bornée d'action_id récemment exécutées.
|
||
Bloque ré-exécution si action arrive 2 fois (orphan resent + double réseau).
|
||
"""
|
||
def __init__(self, max_size: int = 256):
|
||
self._store: OrderedDict[str, float] = OrderedDict() # action_id → ts
|
||
self._max = max_size
|
||
|
||
def seen(self, action_id: str) -> bool:
|
||
if action_id in self._store:
|
||
# Touch (LRU)
|
||
self._store.move_to_end(action_id)
|
||
return True
|
||
return False
|
||
|
||
def mark(self, action_id: str) -> None:
|
||
self._store[action_id] = time.time()
|
||
self._store.move_to_end(action_id)
|
||
if len(self._store) > self._max:
|
||
self._store.popitem(last=False)
|
||
```
|
||
|
||
**Usage dans `poll_and_execute_inner` AVANT `execute_replay_action` :**
|
||
```python
|
||
if self._dedup.seen(action.get("action_id","")):
|
||
logger.warning(f"[DEDUP] action {action.get('action_id')} déjà exécutée — ack synthétique")
|
||
self._post_synthetic_ack(action, server_url, replay_result_url,
|
||
success=True, warning="already_executed")
|
||
return True
|
||
self._dedup.mark(action.get("action_id",""))
|
||
# … execute_replay_action(action) …
|
||
```
|
||
|
||
### 6.3. Idempotence intrinsèque par type d'action
|
||
|
||
| Type | Idempotent nativement ? | Mitigation si exécuté 2× |
|
||
|---|---|---|
|
||
| `click` sur tab/bouton actif | OUI (le tab reste actif) | aucune |
|
||
| `click` sur bouton "Submit"/"Valider" | NON (double formulaire) | **dedup_set CRITIQUE** + dialog confirm côté app |
|
||
| `type` texte | NON (double saisie) | préfixer `Ctrl+A` (clear) + dedup_set |
|
||
| `keyboard_shortcut` Ctrl+S | dep. (1 sauvegarde = 1 dialog) | dedup_set |
|
||
| `keyboard_shortcut` Ctrl+V | NON (double collage) | dedup_set + clear avant |
|
||
| `scroll` | OUI mais déplace 2× | tolérable, dedup_set conseillé |
|
||
| `wait` | OUI | aucun risque |
|
||
| `extract_text` (server-side) | OUI (lecture pure) | n/a |
|
||
| `t2a_decision` (server-side, LLM) | OUI mais re-coût LLM ($/temps) | retry serveur, pas client |
|
||
|
||
---
|
||
|
||
## 7. Timeouts et seuils
|
||
|
||
| Nom | Défaut | Env var | Effet | Source |
|
||
|---|---:|---|---|---|
|
||
| `client_poll_timeout` | 30 s | non, en dur | `requests.get(/replay/next, timeout=30)` côté Léa | executor.py:2320 |
|
||
| `client_report_timeout` | 10 s | non, en dur | `requests.post(/replay/result, timeout=10)` | executor.py:2480 |
|
||
| `client_resolve_timeout` | 30 s | non, en dur | appel serveur `/resolve_target` | executor.py:1898 |
|
||
| `server_replay_lock_timeout` | 4.5 s | non, en dur | `_async_replay_lock(timeout=4.5)` → 503 ou server_busy | api_stream.py:539, 2938 |
|
||
| `server_action_server_side_timeout` | 180 s | non, en dur | `asyncio.wait_for(extract_text/t2a, 180)` | api_stream.py:3141 |
|
||
| `server_paste_and_execute_timeout` | 30 s | non, en dur | paste+execute ydotool | api_stream.py:3192 |
|
||
| `server_precheck_timeout` | 0.5 s | non, en dur | CLIP embed pre-check | api_stream.py:3250 |
|
||
| `heartbeat_max_age` | varie | `RPA_HEARTBEAT_MAX_AGE_SECONDS` | utilité pre-check | api_stream.py:3235 |
|
||
| `WATCHDOG_SCAN_INTERVAL_S` | 10 s | `RPA_WATCHDOG_SCAN_INTERVAL_S` | période scan orphan | AXE_B1_DEEP §11 |
|
||
| `WATCHDOG_ORPHAN_TIMEOUT_S` | 30 s | `RPA_WATCHDOG_ORPHAN_TIMEOUT_S` | age sans report → orphan | AXE_B1_DEEP §11 |
|
||
| `WATCHDOG_MAX_RESENDS` | 2 | `RPA_WATCHDOG_MAX_RESENDS` | give-up après N resends | AXE_B1_DEEP §11 |
|
||
| `WATCHDOG_REPUSH_POSITION` | `head` | `RPA_WATCHDOG_REPUSH_POSITION` | head/tail | AXE_B1_DEEP §11 |
|
||
| `WATCHDOG_ENABLED` | `1` | `RPA_WATCHDOG_ENABLED` | kill-switch | AXE_B1_DEEP §11 |
|
||
| `REPLAY_STATE_TTL_SECONDS` | varie | `RPA_REPLAY_STATE_TTL` | purge states finis | api_stream.py:726 |
|
||
| `MAX_REPLAY_STATES` | n | en dur | borne `_replay_states` | api_stream.py:735 |
|
||
| `MAX_RETRIES_PER_ACTION` | 3 | en dur | budget retry métier `_schedule_retry` | replay_engine.py:2591 |
|
||
| `_poll_backoff_min` | varie | n/a | reset après HTTP 200 | executor.py:2334 |
|
||
| `_poll_backoff_max` | varie | n/a | plafond backoff exponentiel | executor.py:2326 |
|
||
| `_poll_backoff_factor` | 2.0 | n/a | facteur multiplicatif | executor.py:2326 |
|
||
| `SSE_PING_INTERVAL_S` (cible) | 15 | env futur | heartbeat SSE | AXE_B1 §4 |
|
||
|
||
**Cohérence des seuils :**
|
||
- `client_poll_timeout (30s) > server_replay_lock_timeout (4.5s)` → OK, le client attend bien la réponse server_busy.
|
||
- `server_action_server_side_timeout (180s) > client_poll_timeout (30s)` → SI extract_text dure 35s sans dispatcher d'action visuelle entre temps, le client coupe MAIS le serveur continue ; au prochain poll le serveur a fini, dispatche l'action visuelle suivante. **Pas de perte tant que l'action visuelle dispatch est rapide après extract_text.** Bug 8 mai = extract_text + dispatch click dans la MÊME réponse → 5s timeout dépassé → fix `timeout=30` adopté.
|
||
- `WATCHDOG_ORPHAN_TIMEOUT_S (30s) > client_poll_timeout (30s)` → frontière dangereuse. **Recommandation : remonter à 45s** pour laisser le temps au client de retenter au moins 1 poll naturellement avant que le watchdog résende.
|
||
|
||
---
|
||
|
||
## 8. Transitions vers pause supervisée et resume
|
||
|
||
### 8.1. Déclencheurs `status = "paused_need_help"`
|
||
|
||
| Déclencheur | Source | État avant | État après | Champ enrichi |
|
||
|---|---|---|---|---|
|
||
| `pause_for_human` en mode supervised ou safety_checks présents | api_stream.py:3066-3111 | running | paused_need_help | `safety_checks`, `pause_payload`, `failed_action.reason="user_request"` |
|
||
| Report `system_dialog:*` (UAC/CredUI/SmartScreen) | api_stream.py:3785-3870 | running | paused_need_help | `failed_action.reason="system_dialog"`, message contextualisé |
|
||
| Report `warning="wrong_window"` | api_stream.py:3872-3920 | running | paused_need_help | `failed_action.reason="wrong_window"` |
|
||
| Report `success=false` + `error="target_not_found"` après MAX_RETRIES_PER_ACTION (3) | api_stream.py:3949-4030 | running | paused_need_help | `failed_action.target_description` |
|
||
| Hook v1.1 dead client signal (2+ giveups en 60s) | À AJOUTER (AXE_B1_DEEP §6 R4) | running | paused_need_help | `failed_action.reason="dead_client"` |
|
||
| Hook v2 (cas n) : N orphan giveup sur action type critique | À DÉCIDER avec Dom | running | paused_need_help | `failed_action.reason="orphan_max_resends"` |
|
||
|
||
### 8.2. État de `_retry_pending` au moment de la pause
|
||
|
||
- **Pause via `pause_for_human`** : aucune action en vol (pause arrive *avant* dispatch).
|
||
- **Pause via report failed** : l'action qui a déclenché la pause vient d'être `pop`pée. `_retry_pending` est **vide pour cet action_id** (déjà acquittée). Aucune purge supplémentaire nécessaire.
|
||
- **Pause via watchdog hook (v1.1)** : `_retry_pending` peut contenir des entrées orphelines avec age > MAX. **Politique :** purger en transition (à ajouter dans le hook).
|
||
|
||
### 8.3. /resume — reconstruction de l'action
|
||
|
||
`resume_replay` (api_stream.py:4361-4474) :
|
||
1. Vérifie state.status == `paused_need_help` (sinon 409).
|
||
2. Vérifie acquittement safety_checks required (sinon 400).
|
||
3. Reset state : `status="running"`, `failed_action=None`, `pause_message=None`, `safety_checks=[]`.
|
||
4. Reconstruit l'action :
|
||
- Priorité 1 : `failed_action.original_action` si présent.
|
||
- Priorité 2 : `_retry_pending.pop(failed_action.action_id, {}).get("action")`.
|
||
- Priorité 3 : minimum `{action_id, type, target_spec, visual_mode}`.
|
||
5. Nouveau `action_id = "{original}_resume"`.
|
||
6. Enregistre dans `_retry_pending[resume_id] = {action,retry_count:0,replay_id,reason:"resume_after_pause"}`.
|
||
7. Insère en tête `_replay_queues[session_id]`.
|
||
|
||
**Lacune v1 :** le nouveau `action_id` (`_resume`) **n'a pas de `attempt_id`** explicite. Au prochain dispatch, le watchdog démarre le compteur à 0. Cohérent.
|
||
|
||
### 8.4. Event bus `[BUS]`
|
||
|
||
| Event | Quand | Payload (log structuré) | Source |
|
||
|---|---|---|---|
|
||
| `[BUS] lea:safety_checks_generated` | Pause `pause_for_human` avec checks | `replay=<id> count=N sources=[…]` | api_stream.py:3081 |
|
||
| `[BUS] lea:monitor_routed` | Dispatch action visuelle (résolution monitor) | `replay=<id> action=<id> idx=N source=<…>` | api_stream.py:3419 |
|
||
| `[BUS] lea:dispatch_orphan_resent` (v1.1) | Watchdog repush | `action_id=X resent=N/MAX age=Ts session machine replay` | AXE_B1_DEEP §3 |
|
||
| `[BUS] lea:dispatch_orphan_giveup` (v1.1) | Watchdog abandon | `action_id=X resent=N age_total=Ts session machine replay` | AXE_B1_DEEP §3 |
|
||
| `[BUS] lea:dead_client_signal` (v2) | Hook ≥2 giveups/60s | `session=<S> dead_count=N period=60s` | À AJOUTER |
|
||
|
||
Tous les events sont consommables via `journalctl --user -u rpa-streaming -f | grep '\[BUS\]'`. Pas de bus pub/sub réel (pattern QW1/QW4 = log structuré).
|
||
|
||
---
|
||
|
||
## 9. Compatibilité polling actuel ↔ futur SSE
|
||
|
||
Le contrat des §4 / §5 / §6 / §8 est **invariant** par rapport au transport. Voici ce qui change vs ce qui ne change pas :
|
||
|
||
| Aspect | Polling (v1 actuel) | SSE (cible AXE_B1) | Change ? |
|
||
|---|---|---|---|
|
||
| Endpoint dispatch | `GET /api/v1/traces/stream/replay/next` (1 réponse JSON) | `GET /api/v1/traces/stream/replay/events` (stream `text/event-stream`) | OUI |
|
||
| Format payload action | JSON dans body | JSON dans `data:` field d'un `ServerSentEvent` (event=`action`) | NON (même schéma) |
|
||
| Endpoint report | `POST /api/v1/traces/stream/replay/result` | identique | NON |
|
||
| ID corrélation | `action_id` + (v2) `attempt_id` | identique + `id:` SSE = `action_id` | NON |
|
||
| Détection déco client | Indirecte (pas de poll suivant) | `await request.is_disconnected()` immédiat | OUI (gain) |
|
||
| Détection déco serveur | Timeout client 30s | `EventSource.onerror` + reconnect natif | OUI (gain) |
|
||
| Reprise après reconnect | Pas de Last-Event-ID, watchdog seul | `Last-Event-ID` header automatique côté sseclient-py | OUI (gain) |
|
||
| Watchdog `_retry_pending` | **ACTIF** | **ACTIF** (ceinture+bretelles, cf. AXE_B1_DEEP §12) | NON |
|
||
| dedup_set client | **ACTIF v2** | **ACTIF v2** | NON |
|
||
| `_replay_lock` serveur | Tient pendant exécution serveur (extract_text…) | Idem (les actions server-side restent dans la même boucle) | NON |
|
||
| Bulle pause client | Reçue via `replay_paused:true` au prochain poll | Reçue via event `event=paused` ou via `replay_paused:true` dans event `action` | NON (même UX) |
|
||
|
||
**Flag de bascule :** `RPA_REPLAY_TRANSPORT=poll|sse` côté client (executor.py choisit poll vs `replay_subscriber.py`) et serveur (les 2 endpoints coexistent — pas de mutual exclusion). Permet rollback 1-ligne.
|
||
|
||
**Garantie de migration :** un client v2 polling et un client v2 SSE consomment **strictement le même contrat de message**. Le watchdog serveur scanne `_retry_pending` indépendamment du transport. Tous les invariants I1–I6 et C1–C5 tiennent identiquement.
|
||
|
||
**Seul écart pratique :** en SSE, `WATCHDOG_ORPHAN_TIMEOUT_S` peut descendre à 15s (déconnexion détectée plus tôt). En polling, garder 30s (laisser une chance au polling naturel).
|
||
|
||
---
|
||
|
||
## 10. Précédents externes — fiches courtes
|
||
|
||
### 10.1. AWS SQS — visibility timeout
|
||
- **Contrat :** message reçu devient *invisible* pour `VisibilityTimeout` secondes (défaut 30s). Si pas `DeleteMessage` avant expiration → redevient visible, redélivrable.
|
||
- **Modèle :** at-least-once delivery (standard queues), exactly-once (FIFO via `MessageDeduplicationId`).
|
||
- **Idempotence :** **côté consommateur obligatoire** (chez AWS « your processing logic must be idempotent »). DLQ pour les empoisonnés.
|
||
- **Cap :** `ChangeMessageVisibility` pour étendre dynamiquement. Limite dure 12h.
|
||
- **Notre mapping :** `_retry_pending[action_id] = {dispatched_at}` = visibility timeout in-memory. `WATCHDOG_ORPHAN_TIMEOUT_S = 30s` = `VisibilityTimeout`. `WATCHDOG_MAX_RESENDS = 2` = `maxReceiveCount` avant DLQ. ABANDONED = DLQ équivalent (mais sans queue physique, juste log).
|
||
- **Source :** [SQS visibility timeout doc](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html) (consulté 2026-05-24)
|
||
|
||
### 10.2. NATS JetStream — pull consumer ack
|
||
- **Contrat :** `AckExplicit` par défaut. `AckWait` (défaut 30s) = délai avant redélivrance. `MaxDeliver` = N attempts max. `MaxAckPending` = window flow control (défaut 1000).
|
||
- **NAK :** redélivrance immédiate (ou `nakWithDelay`).
|
||
- **Backoff :** liste `[5s, 30s, 300s, …]` qui *override* `AckWait`. Si liste plus courte que `MaxDeliver`, dernier délai répété.
|
||
- **Notre mapping :** `AckWait` = `WATCHDOG_ORPHAN_TIMEOUT_S`. `MaxDeliver` = `WATCHDOG_MAX_RESENDS+1`. **Pas de NAK explicite chez nous** : un report success=false suit la voie retry métier (`_schedule_retry`), pas la voie transport. **Pas de backoff** dans la v1 du watchdog (justification AXE_B1_DEEP §5 : démo médicale, réactivité prime). Adoptable si besoin.
|
||
- **Source :** [NATS JetStream Consumers doc](https://docs.nats.io/nats-concepts/jetstream/consumers) (consulté 2026-05-24)
|
||
|
||
### 10.3. Skyvern — `execute_step` + `handle_failed_step`
|
||
- **Contrat :** boucle récursive `execute_step` (forge/agent.py lignes 1094–1577). À chaque step :
|
||
- `step.status == failed` → `handle_failed_step()` retourne *next step* (retry) ou *None* (terminal).
|
||
- `step.status == completed` → `handle_completed_step()` décide advance vs verify vs finalize.
|
||
- **Cap :** `max_steps_per_run` global, hiérarchie task → org → settings (ligne 1169-1176).
|
||
- **Idempotence :** PR récente a *retiré* le retry interne du `fail_task` (transition status uniquement). Skyvern délègue le retry au LLM via re-emit du prochain action_use.
|
||
- **Différence avec nous :** Skyvern = monolithe local (browser CDP), pas de transport HTTP entre dispatcher et exécuteur. Notre cas nécessite un layer transport en plus, d'où `_retry_pending` qui n'a pas d'équivalent direct.
|
||
- **Source :** [Skyvern agent.py main](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/agent.py), [PR #434 better catch exceptions](https://github.com/Skyvern-AI/skyvern/pull/434)
|
||
|
||
### 10.4. browser-use — action_id + idempotency guard
|
||
- **Contrat :** `max_failures` config (défaut 3). Action cache court-terme keyed sur `(command, selector, value)` pour éviter side-effects dupliqués si retry rapide.
|
||
- **Pattern d'idempotency key :** « *deterministic key before execution, generated from workflow run ID, step index, and action type* » (cf. mightybot blog).
|
||
- **Notre mapping :** `action_id` déterministe = `step_<hex_workflow>` + suffixes. dedup_set client = équivalent action cache court-terme.
|
||
- **Différence :** browser-use est intra-process (loop Python contrôle Chromium via CDP local). Notre cas inter-process inter-machine.
|
||
- **Source :** [browser-use AGENTS.md](https://github.com/browser-use/browser-use/blob/main/AGENTS.md), [Idempotent AI agents — buildmvpfast 2026](https://www.buildmvpfast.com/blog/idempotent-ai-agent-retry-safe-patterns-production-workflow-2026)
|
||
|
||
### 10.5. Anthropic Computer Use SDK — tool_use_id binding
|
||
- **Contrat :** chaque `tool_use` retourné par Claude a un `id` ; le code applicatif doit retourner un `tool_result` avec `tool_use_id` identique (loop.py lignes 234-254).
|
||
- **Retry :** uniquement au niveau API (`max_retries=4` côté client Anthropic, ligne 182). **Pas de retry au niveau tool execution** — c'est le modèle qui re-décide au prochain tour.
|
||
- **Idempotence :** non garantie par le SDK. Délégué à l'application (« deduplication or idempotency key handling visible in this loop : none »).
|
||
- **Notre mapping :** `tool_use_id` ↔ `action_id`. Mais notre boucle est *server-driven* (queue d'actions pré-compilée par VWB), pas LLM-driven. Plus déterministe, donc plus simple à idempotenter.
|
||
- **Source :** [computer-use-demo/loop.py main](https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-demo/computer_use_demo/loop.py), [Tool use Claude API docs](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview)
|
||
|
||
### 10.6. Playwright MCP — SSE remote transport
|
||
- **Contrat :** transport stdio (local) OU HTTP/SSE (remote). Tools/list au handshake, tool/call par event SSE descendant, tool/result POST remontant.
|
||
- **Issue connue 2026 :** « SSE stream disconnected » après idle (cline/cline #8367). Mitigation = ping applicatif.
|
||
- **Timeout :** 30s par défaut sur CDP endpoint connect.
|
||
- **Notre mapping :** très proche du pattern cible AXE_B1 §4 (SSE descendant + POST ack). Confirme robustesse du choix techno. Précaution : prévoir reconnect natif (sseclient-py).
|
||
- **Source :** [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp), [cline issue #8367 SSE disconnect](https://github.com/cline/cline/issues/8367)
|
||
|
||
### 10.7. Synthèse comparative
|
||
|
||
| Système | ID corrélation | Visibility/Ack timeout | Max retry transport | Dedup client | Modèle delivery |
|
||
|---|---|---|---|---|---|
|
||
| **AWS SQS std** | MessageId + ReceiptHandle | VisibilityTimeout 30s | maxReceiveCount (DLQ) | obligatoire app | at-least-once |
|
||
| **NATS JetStream** | StreamSeq + ConsumerSeq | AckWait 30s | MaxDeliver | obligatoire app | at-least-once |
|
||
| **Skyvern** | step.step_id | n/a (monolithe) | max_steps_per_run | n/a | exactly-once local |
|
||
| **browser-use** | (cmd, selector, value) | n/a | max_failures=3 | action cache | exactly-once local |
|
||
| **Anthropic CU** | tool_use_id | n/a | max_retries client (API) | non garanti | exactly-once par tour |
|
||
| **Playwright MCP** | request_id | 30s CDP | n/a (LLM décide) | non garanti | best-effort |
|
||
| **Nous (v2 cible)** | `action_id` + `attempt_id` | ORPHAN_TIMEOUT 30s | MAX_RESENDS=2 | dedup_set 256 LRU | at-least-once + dedup → effectif exactly-once |
|
||
|
||
---
|
||
|
||
## 11. Sources
|
||
|
||
### Code interne (lecture seule, lignes vérifiées 2026-05-24)
|
||
- `agent_v0/server_v1/api_stream.py:520-559` — `_replay_lock`, `_async_replay_lock`, `_replay_queues`, `_replay_states`, `_machine_replay_target`
|
||
- `agent_v0/server_v1/api_stream.py:626-651` — `ReplayResultReport` Pydantic schema
|
||
- `agent_v0/server_v1/api_stream.py:2906-3443` — `get_next_action` (DISPATCH path)
|
||
- `agent_v0/server_v1/api_stream.py:3132-3197` — actions server-side `extract_text/t2a_decision/...`
|
||
- `agent_v0/server_v1/api_stream.py:3354-3359` — création `_retry_pending` (à enrichir AXE_B1_DEEP §4.1)
|
||
- `agent_v0/server_v1/api_stream.py:3446-3491` — `report_action_result`, pop idempotent
|
||
- `agent_v0/server_v1/api_stream.py:3785-3870` — bascule `paused_need_help` sur system_dialog
|
||
- `agent_v0/server_v1/api_stream.py:4361-4474` — `resume_replay` + safety_checks
|
||
- `agent_v0/server_v1/api_stream.py:4477-4494` — `cancel_replay` + purge
|
||
- `agent_v0/server_v1/replay_engine.py:2583-2642` — `_schedule_retry` (retry métier, distinct du retry transport)
|
||
- `agent_v0/agent_v1/core/executor.py:2275-2503` — `poll_and_execute` + `_poll_and_execute_inner`
|
||
- `agent_v0/agent_v1/core/executor.py:2308-2321` — `requests.get(/replay/next, timeout=30)` (fix 8 mai)
|
||
- `agent_v0/agent_v1/core/executor.py:2476-2501` — `requests.post(/replay/result, timeout=10)`
|
||
- `agent_v0/agent_v1/network/streamer.py:1-120` — streaming events/screenshots (canal séparé du replay)
|
||
|
||
### Docs internes
|
||
- `docs/recherche/AXE_B1_REPLAY_TRANSPORT.md` (2026-05-23) — choix SSE vs WebSocket, pseudo-code endpoint
|
||
- `docs/recherche/AXE_B1_DEEP_WATCHDOG.md` (2026-05-24) — implémentation watchdog complète
|
||
- `docs/REPLAY_BLOCAGE_NOTES_MEDICALES_2026-05-08.md` — diagnostic 9 actions perdues, racine du contrat
|
||
- `docs/SYNTHESE_TECHNOS_REPLAY_2026-05-23.md` §4 — synthèse replay
|
||
- `docs/LESSONS_LEARNED_GHT_2026-05.md` — bugs P0 post-démo
|
||
- `docs/SMOKE_TEST_FINALIZE_REPLAY_2026-05-20.md` — contrat finalize → replay
|
||
|
||
### Sources externes (consultées 2026-05-24)
|
||
|
||
**Patterns queue / visibility timeout / idempotence**
|
||
- [Amazon SQS visibility timeout](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html)
|
||
- [Amazon SQS exactly-once processing FIFO](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues-exactly-once-processing.html)
|
||
- [Amazon SQS message deduplication ID](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/using-messagededuplicationid-property.html)
|
||
- [NATS JetStream Consumers](https://docs.nats.io/nats-concepts/jetstream/consumers)
|
||
- [NATS JetStream Model Deep Dive](https://docs.nats.io/using-nats/developer/develop_jetstream/model_deep_dive)
|
||
- [How to Handle SQS Visibility Timeout (oneuptime 2026-01-27)](https://oneuptime.com/blog/post/2026-01-27-sqs-message-visibility-timeout/view)
|
||
- [Achieving idempotency in AWS serverless (Albaqali)](https://qasimalbaqali.medium.com/achieving-idempotency-in-the-aws-serverless-space-d0671a521479)
|
||
|
||
**Frameworks RPA / Computer Use**
|
||
- [Skyvern forge/agent.py main](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/forge/agent.py) — `execute_step` 1094-1577
|
||
- [Skyvern webeye/actions/handler.py](https://github.com/Skyvern-AI/skyvern/blob/main/skyvern/webeye/actions/handler.py)
|
||
- [Skyvern PR #434 better catch exceptions](https://github.com/Skyvern-AI/skyvern/pull/434)
|
||
- [Skyvern retry run webhook docs](https://www.skyvern.com/docs/api-reference/api-reference/agent/retry-run-webhook)
|
||
- [Anthropic computer-use-demo loop.py](https://github.com/anthropics/claude-quickstarts/blob/main/computer-use-demo/computer_use_demo/loop.py) — dispatch 234-254
|
||
- [Anthropic Tool use overview docs](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview)
|
||
- [Microsoft Playwright MCP](https://github.com/microsoft/playwright-mcp)
|
||
- [Cline SSE disconnect issue #8367](https://github.com/cline/cline/issues/8367)
|
||
- [browser-use AGENTS.md main](https://github.com/browser-use/browser-use/blob/main/AGENTS.md)
|
||
- [browser-use issue #3615 agent not stopping](https://github.com/browser-use/browser-use/issues/3615)
|
||
|
||
**Patterns idempotence agents AI**
|
||
- [Idempotent AI Agents — buildmvpfast 2026](https://www.buildmvpfast.com/blog/idempotent-ai-agent-retry-safe-patterns-production-workflow-2026)
|
||
- [Fault-Tolerant AI Agent Pipelines — MightyBot](https://mightybot.ai/blog/fault-tolerant-ai-agent-pipelines/)
|
||
- [Action Verification and Retries in LLM Agent Loops — ingramhaus](https://ingramhaus.com/action-verification-and-retries-in-llm-agent-execution-loops)
|
||
- [Idempotency in Distributed Systems — aloknecessary](https://aloknecessary.github.io/blogs/idempotency-distributed-systems/)
|
||
- [Stripe API idempotent requests](https://docs.stripe.com/api/idempotent_requests)
|
||
|
||
**Transport SSE / FastAPI**
|
||
- [sse-starlette GitHub](https://github.com/sysid/sse-starlette)
|
||
- [FastAPI lifespan events](https://fastapi.tiangolo.com/advanced/events/)
|
||
- [Stop streaming response when client disconnects (FastAPI #7572)](https://github.com/fastapi/fastapi/discussions/7572)
|
||
|
||
---
|
||
|
||
## 12. Décisions non tranchables sans Dom (sortir explicitement du contrat v2)
|
||
|
||
Ces points sont identifiés mais demandent un arbitrage produit :
|
||
|
||
| # | Cas limite | Question | Recommandation Claude |
|
||
|---|---|---|---|
|
||
| D1 | Cas (i) — restart serveur pendant actions en `_retry_pending` | Faut-il persister `_retry_pending` (SQLite) pour rebuild ? Ou accepter perte transport au restart ? | **Accepter perte v2** : le restart serveur est volontaire (`systemctl restart`), Pauline relance le replay depuis VWB. Surcoût persistance > bénéfice. |
|
||
| D2 | Cas (n) — politique abandon | Bascule en `paused_need_help` après MAX_RESENDS atteint ? Pour quels types d'action ? | **OUI pour `click`/`type`/`t2a_decision`** (critiques). **Log seul pour `wait`/`scroll`** (continuer). À ajouter dans hook watchdog v1.1. |
|
||
| D3 | Cas (o) — actions server-side perdues | Retry serveur sur `extract_text` qui timeout ? Watchdog dédié actions server-side ? | **Différer** : v1 = un seul try + log warning, comportement actuel acceptable. v2 envisageable si bench Ollama montre instabilités fréquentes. |
|
||
| D4 | Cas (p) — purge `_retry_pending` à la complétion workflow | Ajouter purge automatique en transition vers `completed/error/failed` ? | **OUI**, simple à ajouter analogue à cancel (api_stream.py:4489). |
|
||
| D5 | dedup_set côté client | Implémenter v2 obligatoire ? Quelle taille LRU ? Inclure `attempt_id` ou juste `action_id` ? | **OUI obligatoire v2.** Taille 256 (couvre largement les workflows GHT 50 steps). Key = `action_id` seul (le `attempt_id` n'apporte rien côté dedup — l'objectif est de bloquer la double exécution même action). |
|
||
| D6 | `attempt_id` côté serveur | Générer UUID à chaque dispatch (initial + resend) ? Stocker l'historique ? | **OUI v2.** Génération à chaque DISPATCH dans `get_next_action`. Pas d'historique nécessaire (logs structurés `[BUS] lea:dispatch_orphan_resent` suffisent). |
|
||
| D7 | Migration backward-compat | Si client v1 (sans dedup_set, sans `attempt_id` echo) parle à serveur v2, casse-t-il ? | **NON** : `attempt_id` est optionnel côté serveur (toléré absent). dedup_set est purement défensif côté client. Migration progressive sans rupture. |
|
||
| D8 | Cas (l) — protocole d'interruption serveur→client d'une action en vol | Ajouter mécanisme `cancel_in_flight` ? | **NON v1, v2** : pas nécessaire pour la démo. Pause supervisée sur step suivant suffit. |
|
||
|
||
---
|
||
|
||
## 13. Liens vers autres specs en cours
|
||
|
||
- **`spec_validator`** (à venir) — un Validator strict (sémantique post-action) ne peut être fiable que si toutes les actions arrivent. **SPEC_TRANSPORT est prérequis logique de spec_validator.** Le contrat REPORT.warning peut s'enrichir de codes de Validator (`semantic_fail`, `expected_text_not_found`) sans casser ce contrat.
|
||
- **`spec_popups`** (à venir) — la détection popup côté serveur (pre-check) ET côté client (DialogHandler) émet des actions synthétiques `wait` ou des reports `warning="popup_handled"`. **Cas (q) du §5 documente la non-interférence.** Le contrat dialog/popup s'imbrique sur les mêmes endpoints sans extension.
|
||
- **AXE_B2 (Validator)** : couvre le côté `verify_action` + Critic sémantique (déjà partiellement codé dans `replay_verifier.py`). À spécifier en parallèle.
|
||
- **AXE_B4 (ORA Observe-Reason-Act)** : pousse aussi dans `_replay_queues` → bénéficie gratuitement du watchdog et du contrat.
|
||
- **AXE_D2 (Dialog/Popup)** : `system_dialog` + `wrong_window` + DialogHandler — branches bascule pause supervisée déjà tracées §8.1.
|
||
|
||
---
|
||
|
||
*Document de spécification contractuelle. Lecture seule sur code, aucune modification. À valider par Dom avant implémentation v2 (dedup_set, attempt_id, hooks watchdog).*
|