feat: v6.6.0 — Agent phase 5 : API publique agent (/api/v2/agents, run synchrone JSON) + marketplace skills (export/import portable + galerie de 6 presets, palette / du panneau) + webhooks agent.run.started/failed · 764 tests verts

docs/API_GUIDE_V6.md

@@ -2,9 +2,13 @@
 
 > **Statut** : ✅ **IMPLÉMENTÉ (v6.3.0, 2026-09-21)** — l'API publique `/api/v2` est livrée :
 > routeur `app/routers/api_v2.py`, helpers `app/services/api_v2_helpers.py`, migration 20,
-> OpenAPI généré (`/docs`, `/redoc`, `docs/openapi-v2.json` — 402 chemins), 24 tests dédiés.
+> OpenAPI généré (`/docs`, `/redoc`, `docs/openapi-v2.json`), 24 tests dédiés.
+> **v6.6.0 (2026-09-24)** — **Agent phase 5** : wrappers agent (`/api/v2/agents/*`) +
+> marketplace de skills (`/api/v2/skills/*`) dans `app/routers/api_v2_agent.py`, logique
+> partagée `app/services/skill_gallery.py`, OpenAPI régénéré (**427 chemins**), 15 tests dédiés
+> (`tests/test_v66_agent_api.py`). Voir §2.4.
 > Les sections ci-dessous décrivent les conventions cibles et restent la référence de conception.
-> **Dernière mise à jour** : 2026-09-21
+> **Dernière mise à jour** : 2026-09-24
 > **Portée** : inventaire de l'API existante, conventions cibles, design CRUD par ressource, webhooks, sécurité, checklist d'implémentation.
 >
 > **Reste reporté (v6.4)** : webhooks HMAC `X-FlowDeck-Signature` + retry 2s/10s/60s + événements étendus ;
@@ -208,6 +212,53 @@ POST /api/move, /col-mapping (GET/DELETE/POST), /board-config/{owner}/{repo} (GE
 - Pas de pagination, filtres, tri.
 - Pas de documentation OpenAPI en production (`docs_url` n'est actif qu'en DEBUG).
 
+### 2.4 API publique v2 — Agent & Skill marketplace (`app/routers/api_v2_agent.py`, v6.6.0)
+
+> **Agent phase 5 « Plateforme »** : permettre à une intégration tierce de piloter
+> FlowDeck Agent et d'installer/partager des skills, sans session navigateur.
+
+**Agents, conversations & runs**
+| Méthode | Route | Scope | Description |
+|---------|-------|-------|-------------|
+| GET | `/api/v2/agents` | read | Liste les agents (pagination `limit`/`offset`) |
+| POST | `/api/v2/agents` | write | Crée un agent (`name`, `system_instructions`, `model`, `scope`, `trigger`) |
+| GET/PUT/DELETE | `/api/v2/agents/{id}` | read / write | Détail, mise à jour, suppression |
+| GET | `/api/v2/agents/conversations` | read | Conversations **de l'utilisateur du token** |
+| POST | `/api/v2/agents/conversations` | write | Crée une conversation (`agent_id` optionnel) |
+| GET/DELETE | `/api/v2/agents/conversations/{id}` | read / write | Conversation + messages / suppression |
+| POST | `/api/v2/agents/conversations/{id}/run` | write | **Run synchrone JSON** (le flux SSE reste interne) |
+| GET | `/api/v2/agents/conversations/{id}/actions` | read | Journal d'audit (`agent_actions`, snapshots) |
+| POST | `/api/v2/agents/actions/{id}/undo` | write | Rollback d'une action |
+| POST | `/api/v2/agents/{id}/trigger` | write | Déclenche un agent custom (JSON, synchrone) |
+
+Réponse de `run` : `{conversation_id, status: completed|failed, final, error, reasoning[], actions[], events[], duration_ms}` —
+HTTP 500 quand `status = failed`. Les événements `events[]` sont ceux du flux SSE
+(`reasoning`, `action`, `final`, `notice`, `error`), à plat : `{"type": "final", "content": ...}`.
+
+**Skill marketplace**
+| Méthode | Route | Scope | Description |
+|---------|-------|-------|-------------|
+| GET/POST | `/api/v2/skills` | read / write | Liste / création (`409` si nom déjà présent) |
+| GET/DELETE | `/api/v2/skills/{id}` | read / write | Détail / suppression |
+| GET | `/api/v2/skills/{id}/export` | read | **Document portable** `{format, version, skill{...}}` |
+| POST | `/api/v2/skills/import` | write | Import (identique → `409`, `overwrite: true` → maj) |
+| GET | `/api/v2/skills/gallery` | read | Presets embarqués (6) |
+| POST | `/api/v2/skills/gallery/{slug}/install` | write | Installe un preset dans le workspace |
+| POST | `/api/v2/skills/{id}/apply` | write | Ouvre une conversation préchargée du skill |
+
+Mêmes endpoints (session cookie) côté interne : `/api/agent/skills/gallery`,
+`/api/agent/skills/{id}/export`, `/api/agent/skills/import`, `DELETE /api/agent/skills/{id}` —
+**même implémentation** via `app/services/skill_gallery.py`.
+
+**Règles spécifiques agent**
+1. La **propriété** des conversations est vérifiée (`user_id` du token) : un token ne voit
+   jamais les conversations d'un autre utilisateur (`404`, pas `403`, pour ne pas fuiter).
+2. Le run est **synchrone** : le moteur (`AgentEngine`), l'ACL (`PermissionManager`), le journal
+   `agent_actions` et les webhooks sont exactement ceux de l'UI — aucun second chemin.
+3. Cycle de vie webhook : `agent.run.started` → `agent.run.finished` | `agent.run.failed`
+   (catalogue `app/services/webhook_outbound.py`, abonnement `agent.*` possible).
+4. Chaque mutation écrit `api_audit_log` (`agent.create`, `agent.run`, `skill.import`, …).
+
 ---
 
 ## 3. Conventions cibles pour l'API v2
@@ -606,7 +657,7 @@ EVENTS = [
 "mention.created", "notification.created",
 "sprint.created", "sprint.updated", "sprint.completed",
 "share.created", "share.revoked", "page.published", "page.unpublished",
-"agent.run.completed",
+"agent.run.started", "agent.run.finished", "agent.run.failed",
 ```
 
 **Payload type** :