aetherius 0.3.0__tar.gz → 0.4.0__tar.gz

{aetherius-0.3.0 → aetherius-0.4.0}/.github/workflows/ci.yml

@@ -30,7 +30,7 @@ jobs:
           cache: pip
           cache-dependency-path: pyproject.toml
       # Base install stays light; heavy Act extras are not needed, tests marked
-      # browser/vision/agent skip themselves when their dependency is absent.
+      # browser/cognition/vision skip themselves when their dependency is absent.
       - run: python -m pip install -e ".[dev]"
       - run: make lint
       - run: make typecheck

{aetherius-0.3.0 → aetherius-0.4.0}/CHANGELOG.md

@@ -7,6 +7,127 @@ Toutes les évolutions notables du projet sont consignées ici. Le format s'insp
 
 ## [Non publié]
 
+## [0.4.0] - 2026-07-20
+
+Phase 2 — les Acts autonomes : **Oracle** (vision) et **Phantom** (agent) deviennent runnables, la
+**composition multi-Act** et le **self-healing** lèvent la contrainte « un Act par Blueprint », et
+l'**humain dans la boucle** (`confirm`) garde les actions sensibles. Phase 2 complète (A–E).
+
+### Ajouté
+- **Jalon 2-E — Human-in-the-loop (`confirm`)** ([docs/human-in-the-loop.md](docs/human-in-the-loop.md)) :
+  une action **orthogonale aux Acts** (héritée par tous les drivers comme `notify`) qui **gare le
+  run** jusqu'à une décision humaine puis reprend. **Attente bloquante, pas suspend/resume** : le
+  worker parqué bloque sur un rendez-vous mémoire (`core/runtime/approvals.py`,
+  `ApprovalRegistry`/`Rendezvous`), le run — navigateur compris — reste vivant ; la boucle asyncio,
+  l'UI, ne gèlent jamais. Le **statut reste `running`** (deux nouveaux events
+  `input_requested`/`input_provided` au contrat `events.schema.json`, aucun nouveau statut). **Timeout
+  obligatoire** (`timeout_ms`, défaut 5 min) + `on_timeout` `approve`/`reject`/`fail:CODE` (défaut
+  **reject**, deny-by-default : le step sensible gardé par `when` se saute) ; un run non surveillé
+  (bibliothèque, sans surface) applique le timeout **immédiatement**. **Quatre surfaces, un seul
+  rendez-vous** : Console (`ConfirmModal` via `ConsoleApprovalSink` sur `input_requested`),
+  CLI/in-process (invite stdin `questionary`, sur un thread pour respecter le timeout, no-op sans
+  TTY), **API daemon** (`POST /v1/runs/{id}/decisions`, token opaque lié au `run_id`, 404 run inconnu
+  / 409 rien en attente ou token invalide), et **réponse de notification** (boutons ntfy
+  Approve/Reject POSTant la route, via `Notification.data["confirm"]` + `AETHERIUS_DAEMON_PUBLIC_URL`).
+  Piste d'audit `approvals` (migration store forward-only **v1→v2**) écrite par le daemon depuis le
+  flux d'événements (source unique, sans course). Nouveaux : `core/actions/human.py` (spec `confirm`),
+  `Capability.CONFIRM`, `RunContext.approvals` + `RunEngine.run(approvals=)`, `server/approvals.py`,
+  `console/approvals.py`, `cli/approvals.py`, `store/approvals.py`. Contrats : event enum + route
+  OpenAPI. Exemple zéro config : `examples/vector/confirm-before-post.blueprint.json`. **Phase 2
+  terminée (A–E).**
+- **Jalon 2-D — Composition multi-Act & self-healing** ([docs/composition.md](docs/composition.md)) :
+  la contrainte « un Act par Blueprint » tombe. **`act` par step** — chaque step peut surcharger
+  l'act du run (hérité dans les branches `if`/`repeat`/`for_each`, validé contre l'act **effectif**) ;
+  les Acts navigateur (II/III/IV) partagent **un seul navigateur** : le moteur pré-scanne l'arbre
+  (surcharges + chaînes de fallback) et instancie une seule instance du plus haut Act atteignable,
+  par subsomption de la chaîne d'héritage des drivers (`core/runtime/drivers.py`, `DriverManager` à
+  démarrage paresseux, teardown groupé). **Self-healing** opt-in : sur échec d'un step navigateur,
+  la chaîne `options.fallback` (ou `fallback` par step, `[]` désactive) rejoue l'**intention** du
+  step (`describe`, jamais devinée) sur l'Act supérieur — escalade `oracle` = rejeu du même step en
+  ciblage vision (`fill` → `type`), escalade `phantom` = **micro-objectif** d'agent borné (6
+  actions, capable d'écarter un obstacle ; limité aux intentions exprimables par le planner).
+  L'escalade est ponctuelle (le step suivant repart sur son act) ; un step guéri est un succès
+  (`StepResult.healed_by`, durée cumulée), le récit passe par des événements `progress` de niveau
+  `warning` (aucun nouveau type d'événement) ; chaîne épuisée = l'erreur d'origine propagée
+  inchangée. Schéma : champs `step.act`/`step.describe`/`step.fallback` + `options.fallback`
+  (additifs). L'exécuteur est réorganisé (`core/runtime/steps.py` + `flow.py` extrait +
+  `healing.py`), zéro régression mono-Act. Exemples zéro config : `examples/composition/`
+  (run mixte Continuum→Oracle et sélecteur cassé rattrapé par vision, vérifiés en réel).
+- **Jalon 2-C — Act IV Phantom** ([docs/acts/phantom.md](docs/acts/phantom.md)) : `act: "phantom"`
+  est **runnable**. Un Blueprint **sans `steps`** déclare un `goal` et des `constraints` ; le moteur
+  route vers `driver.run_goal` (seam goal-only dans `RunEngine.run`) qui lance la boucle
+  **percevoir → raisonner → agir**. Le **planner** (Claude par défaut, rôle `Planner` du substrat de
+  cognition, `acts/_cognition/planning.py`) choisit chaque action par **tool use forcé**
+  (`tool_choice: any`) sur un vocabulaire restreint — ciblage **vision uniquement**, plus les outils
+  terminaux `finish` (objectif atteint → sortie) et `abort` (impossible / contrainte violée → échec
+  propre). L'action est jouée par le ciblage vision d'Oracle à travers la discrétion.
+  `PhantomDriver` **étend** `OracleDriver` (un seul navigateur, une seule discrétion, provider et
+  dispatch hérités) — un Blueprint `phantom` avec `steps` tourne déjà en mode scripté (socle 2-D).
+  Garde-fou : budget `options.agent.max_steps` (défaut 40, nouveau modèle `AgentOptions` + schéma) ;
+  un échec d'action est une **observation** mémorisée (résilience), jamais fatal — seuls `abort`, une
+  réponse de planner inutilisable ou le budget épuisé arrêtent le run. Observabilité par réutilisation
+  de `progress`/`step_started`/`step_finished` (`step_id` `agent[N]`, un `StepResult` par action),
+  **aucun nouvel `EventType`**. Sorties : `finish` exposé sous `{{ steps.agent.* }}`, ou l'issue de
+  l'agent (`{result, steps_taken}`) renvoyée telle quelle sans `outputs` déclarés. Garde validator
+  « goal-only ⇒ act phantom ». Exemple zéro config :
+  `examples/phantom/quotes-find-author.blueprint.json`.
+- **Jalon 2-B — Act III Oracle** ([docs/acts/oracle.md](docs/acts/oracle.md)) : `act: "oracle"` est
+  **runnable**. `OracleDriver` **étend** le driver Continuum (un seul navigateur, une seule
+  discrétion, steps à sélecteur inchangés) et route les cibles vision : `click`/`type`/`upload`/
+  `hover`/`wait_for` acceptent `target: {vision: "description"}` — capture en pixels CSS →
+  grounding (un appel par cible, seuil de confiance 0.5 ajustable par `min_confidence`) → action
+  par coordonnées off-center (bande 30–70 %) via la façade stealth (`HumanInput` gagne
+  `hover_at`). `wait_for` par vision sonde l'écran (un grounding par sonde, `on_timeout:
+  "fail:CODE"` honoré) ; `upload` alimente le file chooser ouvert par le clic. Nouvelle action
+  **`read`** (extraction sémantique, capability + spec `core/actions/vision.py`) : avec `schema`
+  les champs deviennent les sorties du step, sans schéma la valeur arrive sous `data`. Contrat
+  documenté sans changement structurel (`target`, `vision.provider`) ; le Studio accepte les steps
+  ciblés par vision. Exemple zéro config : `examples/oracle/quotes-vision-demo.blueprint.json`.
+- **Action `wait` : plage aléatoire** — sans `ms`, `min_ms`/`max_ms` tirent une durée uniforme
+  dans l'intervalle (act-agnostique) ; le gabarit fondateur `tiktok-upload` devient exact.
+- **Oracle : recherche par défilement (scan)** — une cible vision hors du viewport est trouvée en
+  défilant la page viewport par viewport (scroll humanisé sous discrétion, remontée en haut pour
+  un départ en milieu de page), à coût borné : 8 coups d'œil maximum, un appel de grounding
+  chacun ; `scan: false` épingle le step au viewport courant. Exemple zéro config :
+  `examples/oracle/books-scan-below-fold.blueprint.json`.
+- **Contribution : sondes réalistes** — la « Définition de terminé » exige désormais, en plus du
+  flux nominal vérifié à la main, une ou deux sondes réalistes « dures » (dont un cas conçu pour
+  échouer), consignées dans la doc de la capacité ([docs/testing.md](docs/testing.md)).
+- **Jalon 2-A — Substrat de perception & cognition** ([docs/cognition.md](docs/cognition.md)) : la
+  fondation partagée des Acts cognitifs. `ClaudeProvider` implémente le **grounding** (`locate` :
+  description → `Box` + confiance) et l'**extraction sémantique** (`read`, schéma optionnel) par
+  tool use forcé — réponse structurée, un appel par cible, modèle par défaut `claude-opus-4-8`
+  écrasé par `vision.model`, clé via `ANTHROPIC_API_KEY` (`.env` supporté) ; `resolve_provider`
+  résout `vision.provider` (`claude` défaut / `local`) ; `LocalGrounder` reste l'option locale
+  derrière la même interface (rôles non portés en `CognitionError` typée). Perception de page en
+  **pixels CSS** (`capture` : screenshot `scale="css"` + DOM optionnel, réduction 2576 px avec
+  remise à l'échelle des boîtes), cible unifiée `Target.from_step` (sélecteur ou
+  `target: {vision}`, ambiguïté rejetée), et **clic par coordonnées à travers le stealth**
+  (`HumanInput.click_at`/`type_at`, gestes rejoués + timing humain, intégration Chromium réelle).
+  Nouvelle erreur `CognitionError`. `import aetherius` reste léger (SDK importés paresseusement).
+- **Phase 2 — Autonomie & Contrôle : cadrage + squelette.** Directives et **spécifications par jalon**
+  ([docs/phase-2/](docs/phase-2/README.md), jalons 2-A à 2-E), plus les **stubs d'interface** du
+  substrat de cognition ([`acts/_cognition/`](src/aetherius/acts/_cognition/),
+  [`acts/_perception.py`](src/aetherius/acts/_perception.py),
+  [`core/runtime/selector.py`](src/aetherius/core/runtime/selector.py),
+  [`models/registry.py`](src/aetherius/models/registry.py)) et des Acts cognitifs (Oracle/Phantom).
+  Les Acts II/III/IV deviennent trois stratégies au-dessus d'un même substrat navigateur + stealth +
+  perception + cognition. La phase couvre aussi la composition multi-Act par step, le self-healing
+  (fallback d'Act) et le human-in-the-loop (action `confirm`). Aucun comportement runtime modifié
+  (`make check` vert, `import aetherius` reste léger).
+
+### Modifié
+- **Extras refondus (Jalon 2-A)** : nouvel extra `[cognition]` (`anthropic`, `pillow`) — le défaut
+  partagé Oracle+Phantom, qui **absorbe l'ancien `[agent]`** (supprimé) ; `[vision]` repositionné
+  en **grounder local optionnel** ; `[all]` et les markers pytest alignés (`cognition` remplace
+  `agent`).
+- **Oracle (Act III) redéfini** : le ciblage se fait par **grounding VLM** (Claude par défaut, un
+  détecteur local restant une option branchable derrière la même interface) plutôt que par un modèle
+  ONNX entraîné par tâche ; l'entraînement local devient une piste **optionnelle/avancée**. Fiches
+  [docs/acts/oracle.md](docs/acts/oracle.md) et [docs/acts/phantom.md](docs/acts/phantom.md)
+  réécrites (définition cible), [training/README.md](training/README.md) requalifié, section
+  « Phase 2 » et descriptions Oracle du README harmonisées.
+
 ## [0.3.0] - 2026-07-17
 
 Phase 1.5 : le socle devient **opérationnel** (planification, alertes, réactivité, furtivité réseau
@@ -184,6 +305,7 @@ Première release publique. Elle clôt la **Phase 1** : le socle d'Aetherius, ut
 - SemVer `0.x` : l'API peut évoluer pendant le durcissement de la Phase 1.
 - La **Phase 2** ajoutera Act III (Oracle, vision) et Act IV (Phantom, agent autonome).
 
-[Non publié]: https://github.com/kln-mltre/Aetherius/compare/v0.3.0...HEAD
+[Non publié]: https://github.com/kln-mltre/Aetherius/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/kln-mltre/Aetherius/releases/tag/v0.4.0
 [0.3.0]: https://github.com/kln-mltre/Aetherius/releases/tag/v0.3.0
 [0.2.0]: https://github.com/kln-mltre/Aetherius/releases/tag/v0.2.0

{aetherius-0.3.0 → aetherius-0.4.0}/CONTRIBUTING.md

@@ -43,7 +43,11 @@ est vrai. On ne saute pas une étape en attendant qu'on la réclame :
 3. **Doc à jour** dans le même changement — voir [Documentation](#documentation).
 4. **`make check` vert.**
 5. **Flux vérifié à la main** au moins une fois : le vrai `run`, pas seulement les tests (chaque
-   doc d'Act a une section « Tester … » pour ça).
+   doc d'Act a une section « Tester … » pour ça). En plus du chemin nominal, jouer **une ou deux
+   sondes réalistes « dures »** — un scénario réel plus exigeant que l'exemple zéro config, dont si
+   possible un cas conçu pour faire échouer la capacité. Un échec **propre et explicable** est un
+   résultat valide ; un comportement surprenant est un correctif ou une limite à documenter avant
+   de clore. Voir [docs/testing.md](docs/testing.md#sondes-réalistes).
 6. **Prise en main UI** pour une capacité **liée à l'UI et non triviale** (nouvel écran ou
    interaction non évidente de la Console) : un walkthrough orienté UI dans la doc **et** des captures
    SVG générées (`make screenshots`) — voir [Documentation](#documentation). Exception : une

{aetherius-0.3.0 → aetherius-0.4.0}/Makefile

@@ -31,7 +31,7 @@ test: ## Run the full Python test suite with coverage
 	pytest --cov=aetherius --cov-report=term-missing
 
 test-fast: ## Run only the fast tests (skip heavy extras and slow tests)
-	pytest -m "not browser and not vision and not agent and not slow"
+	pytest -m "not browser and not vision and not cognition and not slow"
 
 test-browser: ## Run the browser tests (Act II) against a real Chromium; needs the [browser] extra
 	pytest -m browser

{aetherius-0.3.0 → aetherius-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aetherius
-Version: 0.3.0
+Version: 0.4.0
 Summary: A fixed, robust web-bot engine driven by declarative instruction files (Blueprints).
 Project-URL: Repository, https://github.com/kln-mltre/Aetherius
 Author: Kylian Malartre
@@ -37,10 +37,8 @@ Requires-Dist: typer>=0.12
 Requires-Dist: tzlocal>=5.0
 Requires-Dist: uvicorn[standard]>=0.29
 Requires-Dist: websockets>=12.0
-Provides-Extra: agent
-Requires-Dist: anthropic>=0.25; extra == 'agent'
 Provides-Extra: all
-Requires-Dist: anthropic>=0.25; extra == 'all'
+Requires-Dist: anthropic>=0.40; extra == 'all'
 Requires-Dist: curl-cffi>=0.6; extra == 'all'
 Requires-Dist: numpy>=1.26; extra == 'all'
 Requires-Dist: onnxruntime>=1.17; extra == 'all'
@@ -50,6 +48,9 @@ Requires-Dist: playwright>=1.44; extra == 'all'
 Requires-Dist: socksio>=1.0; extra == 'all'
 Provides-Extra: browser
 Requires-Dist: playwright>=1.44; extra == 'browser'
+Provides-Extra: cognition
+Requires-Dist: anthropic>=0.40; extra == 'cognition'
+Requires-Dist: pillow>=10.3; extra == 'cognition'
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == 'dev'
 Requires-Dist: mypy>=1.9; extra == 'dev'
@@ -120,7 +121,7 @@ Blueprint choisit l'Act adapté à la tâche.
 |-----|-----|--------|------------------|
 | **I** | **Vector** | Requêtes HTTP/API | Les données sont derrière une API ou des endpoints stables. Le cas « axios ». Le plus rapide. |
 | **II** | **Continuum** | Navigateur scripté (Playwright) | Il faut un vrai navigateur : login, JS, session, DOM. Sélecteurs connus et stables. |
-| **III** | **Oracle** | Navigateur guidé par vision + discrétion | L'UI est fragile/obfusquée : Aetherius « voit » l'écran via un petit modèle entraîné et agit avec discrétion. |
+| **III** | **Oracle** | Navigateur guidé par vision + discrétion | L'UI est fragile/obfusquée : Aetherius « voit » l'écran via un modèle vision-langage (grounding VLM) et agit avec discrétion. |
 | **IV** | **Phantom** | Agent autonome | Objectif non scripté. Perçoit, raisonne, agit en boucle. Résilience maximale. Le plus lourd. |
 
 Plus l'Act est élevé, plus le Blueprint est **haut-niveau** (on décrit *quoi*, plus *comment*) et
@@ -139,10 +140,11 @@ exigent un navigateur : login, cookies de session, contenu rendu par JS. C'est l
 et réutilisable d'une « WebView cachée qui scrape ». Discrétion optionnelle.
 
 ### Act III — Oracle
-Quand les sélecteurs sont trop fragiles ou absents, Oracle **regarde l'écran**. Un petit modèle de
-vision entraîné spécifiquement pour la tâche (exporté en ONNX) localise les éléments cibles sur des
-captures d'écran ; Aetherius clique par coordonnées à travers la couche de discrétion. Idéal pour
-les interfaces qui changent souvent ou piègent les bots.
+Quand les sélecteurs sont trop fragiles ou absents, Oracle **regarde l'écran**. Un modèle
+vision-langage (VLM — Claude par défaut, un détecteur local reste une option) localise en langage
+naturel les éléments cibles sur des captures d'écran ; Aetherius clique par coordonnées à travers la
+couche de discrétion. Le flux reste scripté et déterministe (un appel de grounding par cible). Idéal
+pour les interfaces qui changent souvent ou piègent les bots.
 
 ### Act IV — Phantom
 Un agent décisionnel autonome. Boucle **percevoir → raisonner → agir** : il perçoit la page (vision
@@ -325,8 +327,9 @@ aetherius            # ouvre la Console
 > **État actuel** : la Console est navigable de bout en bout. Library, Runs, **Schedules** (runs
 > récurrents : liste, tir manuel, historique, création guidée), Catalog, le **Recorder**, le
 > **Blueprint Studio** et **Settings** (démarrer/arrêter le daemon) sont pleinement fonctionnels
-> pour Act I (Vector) et Act II (Continuum, avec l'extra `[browser]`) ; seul **Sessions** affiche
-> honnêtement son jalon en attente (stealth/session). Détails : [docs/console.md](docs/console.md).
+> pour Act I (Vector), Act II (Continuum, extra `[browser]`), Act III (Oracle) et Act IV (Phantom)
+> (extras `[cognition]`+`[browser]`) ; seul **Sessions** affiche honnêtement son jalon en attente
+> (stealth/session). Détails : [docs/console.md](docs/console.md).
 
 Depuis la Console, sans écrire de JSON à la main :
 - **Créer et éditer des Blueprints** via le **Blueprint Studio** (voir plus bas).
@@ -464,7 +467,8 @@ console.log(result.outputs.events);
 ```
 src/aetherius/
   core/        blueprint (models/loader/validator/template), actions (le dictionnaire),
-               runtime (engine/context/steps/selector/result), extraction, events, errors, driver
+               runtime (engine/drivers/steps/flow/healing/context/selector/result), extraction,
+               events, errors, driver
   acts/        vector (I), continuum (II), oracle (III), phantom (IV)
   stealth/     policy, humanizer (mouse/keyboard/scroll/timing), gestures, fingerprint,
                session (store/warmup), ml (optionnel)
@@ -493,10 +497,10 @@ typées (jamais avalées) ; les Acts sont des drivers interchangeables derrière
 ## Installation (cible)
 
 ```bash
-pip install aetherius            # cœur + Act I (Vector) + daemon + Console
-pip install aetherius[browser]   # + Act II (Continuum)
-pip install aetherius[vision]    # + Act III (Oracle)
-pip install aetherius[agent]     # + Act IV (Phantom)
+pip install aetherius             # cœur + Act I (Vector) + daemon + Console
+pip install aetherius[browser]    # + Act II (Continuum)
+pip install aetherius[cognition]  # + Acts III/IV (Oracle, Phantom) : cognition Claude par défaut
+pip install aetherius[vision]     # optionnel : grounder local (ONNX/VLM) derrière la même interface
 pip install aetherius[all]
 ```
 
@@ -678,10 +682,83 @@ couche stealth, le rendre invisible **au niveau réseau** (proxy, rotation d'IP)
   `examples/vector/http-headers-identity.blueprint.json`. [docs/stealth.md](docs/stealth.md),
   [docs/phase-1.5/h-fingerprint.md](docs/phase-1.5/h-fingerprint.md).
 
-### Phase 2 — les Acts autonomes (à venir)
-
-- [ ] Act III — Oracle (vision + entraînement).
-- [ ] Act IV — Phantom (agent).
+### Phase 2 — Autonomie & Contrôle (terminée)
+
+Cadrage complet et **spécifications par jalon** : [docs/phase-2/](docs/phase-2/README.md). La phase
+livre les **Acts cognitifs** et rend le bot à la fois plus **autonome** (il gère les parties non
+scriptées, voit l'écran, s'auto-répare) et plus **pilotable** (il demande une confirmation humaine à
+distance). Oracle est **redéfini** : ciblage par **grounding VLM** (Claude par défaut, modèle local
+optionnel), sans entraînement obligatoire.
+
+- [x] **2-A** — Substrat de perception & cognition : la fondation partagée d'Oracle et Phantom.
+  Interface `CognitionProvider` ségrégée en trois rôles (`Grounder`/`Extractor`/`Planner`),
+  `ClaudeProvider` par défaut — grounding et extraction sémantique par **tool use forcé** (réponse
+  structurée, un appel par cible, `claude-opus-4-8` écrasé par `vision.model`) —, `LocalGrounder`
+  optionnel derrière la même interface, résolution `vision.provider` (`claude`/`local`).
+  Perception de page en **pixels CSS** (`capture` : screenshot `scale="css"`, DOM optionnel),
+  cible unifiée `Target` (sélecteur **ou** `{vision: "description"}`), et **clic par coordonnées à
+  travers le stealth** (`HumanInput.click_at`/`type_at`, gestes rejoués + timing humain, vérifié
+  sur Chromium réel). Extras refondus : `[cognition]` (anthropic + pillow, absorbe `[agent]`),
+  `[vision]` repositionné en grounder local. `import aetherius` reste léger.
+  [docs/cognition.md](docs/cognition.md),
+  [docs/phase-2/2-a-cognition.md](docs/phase-2/2-a-cognition.md).
+- [x] **2-B** — Act III Oracle : `oracle` est **runnable**. Ciblage par description en langage
+  naturel (`target: {vision}`) sur `click`/`type`/`upload`/`hover`/`wait_for` : capture en pixels
+  CSS → grounding (un appel par cible, seuil de confiance 0.5, `min_confidence` par step) → action
+  par coordonnées **off-center (bande 30–70 %) à travers le stealth** (`hover_at` rejoint la façade
+  `HumanInput`) ; une cible hors viewport est trouvée par **recherche par défilement** (scan borné
+  à 8 coups d'œil, scroll humanisé, opt-out `scan: false`) ; `wait_for` par vision sonde l'écran
+  (un grounding par sonde), `upload` alimente le file chooser ouvert par le clic. Action **`read`** (extraction sémantique) : `vision` + `schema`
+  objet → les champs deviennent les sorties du step, sans schéma → valeur sous `data`.
+  `OracleDriver` **étend** le driver Continuum — un seul navigateur, une seule discrétion, steps à
+  sélecteur inchangés. Capability `read` (specs `core/actions/vision.py`, hint « requires
+  act='oracle' »), et l'action `wait` gagne `min_ms`/`max_ms` (durée aléatoire uniforme,
+  act-agnostique). Exemples zéro config : `examples/oracle/quotes-vision-demo.blueprint.json` et
+  `books-scan-below-fold.blueprint.json` (vérifiés en réel, Claude + Chromium).
+  [docs/acts/oracle.md](docs/acts/oracle.md), [docs/phase-2/2-b-oracle.md](docs/phase-2/2-b-oracle.md).
+- [x] **2-C** — Act IV Phantom : `act: "phantom"` est **runnable**. Un Blueprint sans `steps`
+  déclare un `goal` et des `constraints` ; le moteur invoque la boucle **percevoir → raisonner →
+  agir** (`RunEngine` route vers `driver.run_goal` quand `steps` est vide). Le **planner** (Claude
+  par défaut, rôle `Planner` du substrat) choisit chaque action via un vocabulaire d'outils
+  restreint (tool use forcé, ciblage **vision uniquement**, plus `finish`/`abort`) ; l'action est
+  jouée par le ciblage vision d'Oracle à travers la discrétion. `PhantomDriver` **étend**
+  `OracleDriver` (un seul navigateur, une seule discrétion). Garde-fou : budget
+  `options.agent.max_steps` (défaut 40) ; un échec d'action est une **observation** (résilience),
+  pas la mort du run. Observabilité par `progress`/`step_started`/`step_finished` (`step_id`
+  `agent[N]`), sans nouvel événement. Sorties : `finish` sous `{{ steps.agent.* }}`, ou l'issue de
+  l'agent renvoyée telle quelle sans `outputs`. Exemple zéro config :
+  `examples/phantom/quotes-find-author.blueprint.json`. [docs/acts/phantom.md](docs/acts/phantom.md),
+  [docs/phase-2/2-c-phantom.md](docs/phase-2/2-c-phantom.md).
+- [x] **2-D** — Composition multi-Act par step + self-healing : un Blueprint mélange les Acts —
+  `act` **par step** (hérité dans les branches de flux, validé contre l'act effectif), les Acts
+  navigateur partageant **un seul navigateur** (une instance du plus haut Act atteignable, par
+  subsomption de la chaîne d'héritage des drivers ; drivers démarrés à la demande,
+  `core/runtime/drivers.py`). **Self-healing** opt-in : un step navigateur qui échoue est rejoué
+  sur l'Act supérieur via sa chaîne `options.fallback`/`fallback` (ordonnée, `oracle`/`phantom`)
+  et son **`describe`** (intention en langage naturel, jamais devinée) — escalade Oracle = rejeu
+  vision du même step (`fill`→`type`), escalade Phantom = **micro-objectif** d'agent borné
+  (6 actions) capable d'écarter un obstacle ; ponctuelle (le step suivant repart sur son act),
+  step guéri = succès tracé (`healed_by` + événements `progress` warning, aucun nouveau type
+  d'événement), chaîne épuisée = l'erreur d'origine inchangée. Exemples zéro config :
+  `examples/composition/` (run mixte + self-healing, vérifiés en réel).
+  [docs/composition.md](docs/composition.md),
+  [docs/phase-2/2-d-composition.md](docs/phase-2/2-d-composition.md).
+- [x] **2-E** — Human-in-the-loop : l'action **`confirm`** (orthogonale aux Acts, héritée par tous les
+  drivers) **gare le run** jusqu'à une décision humaine puis reprend — attente bloquante sur un
+  rendez-vous mémoire (`core/runtime/approvals.py`), le worker parqué, jamais la boucle ; le statut
+  reste `running` (nouveaux events `input_requested`/`input_provided`, aucun nouveau statut). Timeout
+  **obligatoire** (`on_timeout` `approve`/`reject`/`fail:CODE`, défaut **reject** deny-by-default) ;
+  run non surveillé (bibliothèque) = timeout immédiat. **Quatre surfaces, un seul rendez-vous** :
+  Console (`ConfirmModal` sur `input_requested`), CLI/in-process (invite stdin `questionary`), API
+  daemon (`POST /v1/runs/{id}/decisions`, token opaque lié au run, 404/409), et **réponse de
+  notification** (boutons ntfy Approve/Reject POSTant la route via `Notification.data`, URL publique
+  `AETHERIUS_DAEMON_PUBLIC_URL`). Piste d'audit `approvals` (migration store v1→v2) écrite depuis le
+  flux d'événements. Exemple zéro config : `examples/vector/confirm-before-post.blueprint.json`.
+  [docs/human-in-the-loop.md](docs/human-in-the-loop.md),
+  [docs/phase-2/2-e-human-in-loop.md](docs/phase-2/2-e-human-in-loop.md).
+
+**Phase 2 terminée (A–E).** Aetherius est désormais autonome (Oracle/Phantom, composition,
+self-healing) **et** pilotable (human-in-the-loop).
 
 ## Sources de référence
 

{aetherius-0.3.0 → aetherius-0.4.0}/README.md

@@ -48,7 +48,7 @@ Blueprint choisit l'Act adapté à la tâche.
 |-----|-----|--------|------------------|
 | **I** | **Vector** | Requêtes HTTP/API | Les données sont derrière une API ou des endpoints stables. Le cas « axios ». Le plus rapide. |
 | **II** | **Continuum** | Navigateur scripté (Playwright) | Il faut un vrai navigateur : login, JS, session, DOM. Sélecteurs connus et stables. |
-| **III** | **Oracle** | Navigateur guidé par vision + discrétion | L'UI est fragile/obfusquée : Aetherius « voit » l'écran via un petit modèle entraîné et agit avec discrétion. |
+| **III** | **Oracle** | Navigateur guidé par vision + discrétion | L'UI est fragile/obfusquée : Aetherius « voit » l'écran via un modèle vision-langage (grounding VLM) et agit avec discrétion. |
 | **IV** | **Phantom** | Agent autonome | Objectif non scripté. Perçoit, raisonne, agit en boucle. Résilience maximale. Le plus lourd. |
 
 Plus l'Act est élevé, plus le Blueprint est **haut-niveau** (on décrit *quoi*, plus *comment*) et
@@ -67,10 +67,11 @@ exigent un navigateur : login, cookies de session, contenu rendu par JS. C'est l
 et réutilisable d'une « WebView cachée qui scrape ». Discrétion optionnelle.
 
 ### Act III — Oracle
-Quand les sélecteurs sont trop fragiles ou absents, Oracle **regarde l'écran**. Un petit modèle de
-vision entraîné spécifiquement pour la tâche (exporté en ONNX) localise les éléments cibles sur des
-captures d'écran ; Aetherius clique par coordonnées à travers la couche de discrétion. Idéal pour
-les interfaces qui changent souvent ou piègent les bots.
+Quand les sélecteurs sont trop fragiles ou absents, Oracle **regarde l'écran**. Un modèle
+vision-langage (VLM — Claude par défaut, un détecteur local reste une option) localise en langage
+naturel les éléments cibles sur des captures d'écran ; Aetherius clique par coordonnées à travers la
+couche de discrétion. Le flux reste scripté et déterministe (un appel de grounding par cible). Idéal
+pour les interfaces qui changent souvent ou piègent les bots.
 
 ### Act IV — Phantom
 Un agent décisionnel autonome. Boucle **percevoir → raisonner → agir** : il perçoit la page (vision
@@ -253,8 +254,9 @@ aetherius            # ouvre la Console
 > **État actuel** : la Console est navigable de bout en bout. Library, Runs, **Schedules** (runs
 > récurrents : liste, tir manuel, historique, création guidée), Catalog, le **Recorder**, le
 > **Blueprint Studio** et **Settings** (démarrer/arrêter le daemon) sont pleinement fonctionnels
-> pour Act I (Vector) et Act II (Continuum, avec l'extra `[browser]`) ; seul **Sessions** affiche
-> honnêtement son jalon en attente (stealth/session). Détails : [docs/console.md](docs/console.md).
+> pour Act I (Vector), Act II (Continuum, extra `[browser]`), Act III (Oracle) et Act IV (Phantom)
+> (extras `[cognition]`+`[browser]`) ; seul **Sessions** affiche honnêtement son jalon en attente
+> (stealth/session). Détails : [docs/console.md](docs/console.md).
 
 Depuis la Console, sans écrire de JSON à la main :
 - **Créer et éditer des Blueprints** via le **Blueprint Studio** (voir plus bas).
@@ -392,7 +394,8 @@ console.log(result.outputs.events);
 ```
 src/aetherius/
   core/        blueprint (models/loader/validator/template), actions (le dictionnaire),
-               runtime (engine/context/steps/selector/result), extraction, events, errors, driver
+               runtime (engine/drivers/steps/flow/healing/context/selector/result), extraction,
+               events, errors, driver
   acts/        vector (I), continuum (II), oracle (III), phantom (IV)
   stealth/     policy, humanizer (mouse/keyboard/scroll/timing), gestures, fingerprint,
                session (store/warmup), ml (optionnel)
@@ -421,10 +424,10 @@ typées (jamais avalées) ; les Acts sont des drivers interchangeables derrière
 ## Installation (cible)
 
 ```bash
-pip install aetherius            # cœur + Act I (Vector) + daemon + Console
-pip install aetherius[browser]   # + Act II (Continuum)
-pip install aetherius[vision]    # + Act III (Oracle)
-pip install aetherius[agent]     # + Act IV (Phantom)
+pip install aetherius             # cœur + Act I (Vector) + daemon + Console
+pip install aetherius[browser]    # + Act II (Continuum)
+pip install aetherius[cognition]  # + Acts III/IV (Oracle, Phantom) : cognition Claude par défaut
+pip install aetherius[vision]     # optionnel : grounder local (ONNX/VLM) derrière la même interface
 pip install aetherius[all]
 ```
 
@@ -606,10 +609,83 @@ couche stealth, le rendre invisible **au niveau réseau** (proxy, rotation d'IP)
   `examples/vector/http-headers-identity.blueprint.json`. [docs/stealth.md](docs/stealth.md),
   [docs/phase-1.5/h-fingerprint.md](docs/phase-1.5/h-fingerprint.md).
 
-### Phase 2 — les Acts autonomes (à venir)
-
-- [ ] Act III — Oracle (vision + entraînement).
-- [ ] Act IV — Phantom (agent).
+### Phase 2 — Autonomie & Contrôle (terminée)
+
+Cadrage complet et **spécifications par jalon** : [docs/phase-2/](docs/phase-2/README.md). La phase
+livre les **Acts cognitifs** et rend le bot à la fois plus **autonome** (il gère les parties non
+scriptées, voit l'écran, s'auto-répare) et plus **pilotable** (il demande une confirmation humaine à
+distance). Oracle est **redéfini** : ciblage par **grounding VLM** (Claude par défaut, modèle local
+optionnel), sans entraînement obligatoire.
+
+- [x] **2-A** — Substrat de perception & cognition : la fondation partagée d'Oracle et Phantom.
+  Interface `CognitionProvider` ségrégée en trois rôles (`Grounder`/`Extractor`/`Planner`),
+  `ClaudeProvider` par défaut — grounding et extraction sémantique par **tool use forcé** (réponse
+  structurée, un appel par cible, `claude-opus-4-8` écrasé par `vision.model`) —, `LocalGrounder`
+  optionnel derrière la même interface, résolution `vision.provider` (`claude`/`local`).
+  Perception de page en **pixels CSS** (`capture` : screenshot `scale="css"`, DOM optionnel),
+  cible unifiée `Target` (sélecteur **ou** `{vision: "description"}`), et **clic par coordonnées à
+  travers le stealth** (`HumanInput.click_at`/`type_at`, gestes rejoués + timing humain, vérifié
+  sur Chromium réel). Extras refondus : `[cognition]` (anthropic + pillow, absorbe `[agent]`),
+  `[vision]` repositionné en grounder local. `import aetherius` reste léger.
+  [docs/cognition.md](docs/cognition.md),
+  [docs/phase-2/2-a-cognition.md](docs/phase-2/2-a-cognition.md).
+- [x] **2-B** — Act III Oracle : `oracle` est **runnable**. Ciblage par description en langage
+  naturel (`target: {vision}`) sur `click`/`type`/`upload`/`hover`/`wait_for` : capture en pixels
+  CSS → grounding (un appel par cible, seuil de confiance 0.5, `min_confidence` par step) → action
+  par coordonnées **off-center (bande 30–70 %) à travers le stealth** (`hover_at` rejoint la façade
+  `HumanInput`) ; une cible hors viewport est trouvée par **recherche par défilement** (scan borné
+  à 8 coups d'œil, scroll humanisé, opt-out `scan: false`) ; `wait_for` par vision sonde l'écran
+  (un grounding par sonde), `upload` alimente le file chooser ouvert par le clic. Action **`read`** (extraction sémantique) : `vision` + `schema`
+  objet → les champs deviennent les sorties du step, sans schéma → valeur sous `data`.
+  `OracleDriver` **étend** le driver Continuum — un seul navigateur, une seule discrétion, steps à
+  sélecteur inchangés. Capability `read` (specs `core/actions/vision.py`, hint « requires
+  act='oracle' »), et l'action `wait` gagne `min_ms`/`max_ms` (durée aléatoire uniforme,
+  act-agnostique). Exemples zéro config : `examples/oracle/quotes-vision-demo.blueprint.json` et
+  `books-scan-below-fold.blueprint.json` (vérifiés en réel, Claude + Chromium).
+  [docs/acts/oracle.md](docs/acts/oracle.md), [docs/phase-2/2-b-oracle.md](docs/phase-2/2-b-oracle.md).
+- [x] **2-C** — Act IV Phantom : `act: "phantom"` est **runnable**. Un Blueprint sans `steps`
+  déclare un `goal` et des `constraints` ; le moteur invoque la boucle **percevoir → raisonner →
+  agir** (`RunEngine` route vers `driver.run_goal` quand `steps` est vide). Le **planner** (Claude
+  par défaut, rôle `Planner` du substrat) choisit chaque action via un vocabulaire d'outils
+  restreint (tool use forcé, ciblage **vision uniquement**, plus `finish`/`abort`) ; l'action est
+  jouée par le ciblage vision d'Oracle à travers la discrétion. `PhantomDriver` **étend**
+  `OracleDriver` (un seul navigateur, une seule discrétion). Garde-fou : budget
+  `options.agent.max_steps` (défaut 40) ; un échec d'action est une **observation** (résilience),
+  pas la mort du run. Observabilité par `progress`/`step_started`/`step_finished` (`step_id`
+  `agent[N]`), sans nouvel événement. Sorties : `finish` sous `{{ steps.agent.* }}`, ou l'issue de
+  l'agent renvoyée telle quelle sans `outputs`. Exemple zéro config :
+  `examples/phantom/quotes-find-author.blueprint.json`. [docs/acts/phantom.md](docs/acts/phantom.md),
+  [docs/phase-2/2-c-phantom.md](docs/phase-2/2-c-phantom.md).
+- [x] **2-D** — Composition multi-Act par step + self-healing : un Blueprint mélange les Acts —
+  `act` **par step** (hérité dans les branches de flux, validé contre l'act effectif), les Acts
+  navigateur partageant **un seul navigateur** (une instance du plus haut Act atteignable, par
+  subsomption de la chaîne d'héritage des drivers ; drivers démarrés à la demande,
+  `core/runtime/drivers.py`). **Self-healing** opt-in : un step navigateur qui échoue est rejoué
+  sur l'Act supérieur via sa chaîne `options.fallback`/`fallback` (ordonnée, `oracle`/`phantom`)
+  et son **`describe`** (intention en langage naturel, jamais devinée) — escalade Oracle = rejeu
+  vision du même step (`fill`→`type`), escalade Phantom = **micro-objectif** d'agent borné
+  (6 actions) capable d'écarter un obstacle ; ponctuelle (le step suivant repart sur son act),
+  step guéri = succès tracé (`healed_by` + événements `progress` warning, aucun nouveau type
+  d'événement), chaîne épuisée = l'erreur d'origine inchangée. Exemples zéro config :
+  `examples/composition/` (run mixte + self-healing, vérifiés en réel).
+  [docs/composition.md](docs/composition.md),
+  [docs/phase-2/2-d-composition.md](docs/phase-2/2-d-composition.md).
+- [x] **2-E** — Human-in-the-loop : l'action **`confirm`** (orthogonale aux Acts, héritée par tous les
+  drivers) **gare le run** jusqu'à une décision humaine puis reprend — attente bloquante sur un
+  rendez-vous mémoire (`core/runtime/approvals.py`), le worker parqué, jamais la boucle ; le statut
+  reste `running` (nouveaux events `input_requested`/`input_provided`, aucun nouveau statut). Timeout
+  **obligatoire** (`on_timeout` `approve`/`reject`/`fail:CODE`, défaut **reject** deny-by-default) ;
+  run non surveillé (bibliothèque) = timeout immédiat. **Quatre surfaces, un seul rendez-vous** :
+  Console (`ConfirmModal` sur `input_requested`), CLI/in-process (invite stdin `questionary`), API
+  daemon (`POST /v1/runs/{id}/decisions`, token opaque lié au run, 404/409), et **réponse de
+  notification** (boutons ntfy Approve/Reject POSTant la route via `Notification.data`, URL publique
+  `AETHERIUS_DAEMON_PUBLIC_URL`). Piste d'audit `approvals` (migration store v1→v2) écrite depuis le
+  flux d'événements. Exemple zéro config : `examples/vector/confirm-before-post.blueprint.json`.
+  [docs/human-in-the-loop.md](docs/human-in-the-loop.md),
+  [docs/phase-2/2-e-human-in-loop.md](docs/phase-2/2-e-human-in-loop.md).
+
+**Phase 2 terminée (A–E).** Aetherius est désormais autonome (Oracle/Phantom, composition,
+self-healing) **et** pilotable (human-in-the-loop).
 
 ## Sources de référence
 

{aetherius-0.3.0/src/aetherius/_contracts → aetherius-0.4.0/contracts}/blueprint.schema.json

@@ -40,8 +40,17 @@
     "options": { "$ref": "#/$defs/options" },
     "vision": {
       "type": "object",
-      "description": "Vision configuration for Oracle/Phantom.",
-      "properties": { "model": { "type": "string" } },
+      "description": "Cognition configuration for Oracle/Phantom (see docs/cognition.md).",
+      "properties": {
+        "provider": {
+          "enum": ["claude", "local"],
+          "description": "Cognition backend: claude (default, [cognition] extra) or local ([vision] extra, on-device grounder)."
+        },
+        "model": {
+          "type": "string",
+          "description": "Model name, not backend: an Anthropic model id for claude, a local asset name@version for local."
+        }
+      },
       "additionalProperties": true
     },
     "goal": {
@@ -107,7 +116,25 @@
             "backoff": { "enum": ["none", "linear", "exponential"] }
           }
         },
-        "proxy": { "$ref": "#/$defs/proxy" }
+        "proxy": { "$ref": "#/$defs/proxy" },
+        "agent": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Phantom (Act IV) guardrails; ignored by the other Acts.",
+          "properties": {
+            "max_steps": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 40,
+              "description": "Upper bound on the perceive->reason->act loop: the agent fails cleanly if the goal is not reached within this many steps."
+            }
+          }
+        },
+        "fallback": {
+          "type": "array",
+          "description": "Self-healing (Jalon 2-D): default escalation chain tried, in order, when a browser step fails and carries a 'describe' (or a vision target). A step's own 'fallback' overrides it.",
+          "items": { "enum": ["oracle", "phantom"] }
+        }
       }
     },
     "proxy": {
@@ -161,7 +188,7 @@
     },
     "step": {
       "type": "object",
-      "description": "A single action. Parameters depend on the action; extra properties are allowed and validated per-action by the engine.",
+      "description": "A single action. Parameters depend on the action; extra properties are allowed and validated per-action by the engine. Act III+ adds 'read' (semantic extraction: 'vision' description plus optional 'schema' object shaping the reply).",
       "properties": {
         "id": { "type": "string" },
         "action": { "type": "string" },
@@ -169,6 +196,34 @@
           "type": "string",
           "description": "Guard expression rendered before dispatch; the step is skipped unless it yields true/1/yes."
         },
+        "act": {
+          "enum": ["vector", "continuum", "oracle", "phantom"],
+          "description": "Multi-Act composition (Jalon 2-D): overrides the Blueprint act for this step (nested flow steps inherit it). Browser Acts share a single browser within the run."
+        },
+        "describe": {
+          "type": "string",
+          "description": "Self-healing: natural-language intent of the step, replayed on a higher Act (vision grounding or agent micro-goal) when its selector fails. Without it a failing selector step is not escalated."
+        },
+        "fallback": {
+          "type": "array",
+          "description": "Self-healing: per-step escalation chain; overrides options.fallback ([] disables it for this step).",
+          "items": { "enum": ["oracle", "phantom"] }
+        },
+        "target": {
+          "description": "Unified target of an interactive action. Either the drop selector of drag (string), or an object aiming at a DOM selector ({selector, selector_type}) or, on Act III+, at a natural-language description resolved by vision grounding ({vision}). Top-level 'selector' and 'target' are mutually exclusive on a step.",
+          "oneOf": [
+            { "type": "string", "description": "drag only: selector to drop onto." },
+            {
+              "type": "object",
+              "properties": {
+                "vision": { "type": "string", "description": "Natural-language description of the on-screen element (Act III+)." },
+                "selector": { "type": "string", "description": "DOM selector (nested form of the top-level 'selector')." },
+                "selector_type": { "enum": ["css", "xpath", "text"] }
+              },
+              "additionalProperties": true
+            }
+          ]
+        },
         "then": {
           "type": "array",
           "description": "Steps run when an if condition holds.",

{aetherius-0.3.0 → aetherius-0.4.0}/contracts/events.schema.json

@@ -10,7 +10,7 @@
     "run_id": { "type": "string" },
     "ts": { "type": "string", "format": "date-time" },
     "type": {
-      "enum": ["progress", "step_started", "step_finished", "step_skipped", "debug", "artifact", "error", "done"]
+      "enum": ["progress", "step_started", "step_finished", "step_skipped", "debug", "artifact", "error", "done", "input_requested", "input_provided"]
     },
     "step_id": { "type": "string" },
     "level": { "enum": ["debug", "info", "warning", "error"] },