@imenam/mcp-organizer 1.0.1 → 1.0.3

package/README.md

@@ -11,7 +11,7 @@ Un seul paquet, deux modes :
 | `mcp-organizer --server` | **Site** : processus web permanent, derrière un reverse proxy (nginx). Il détient la base, sert l'interface, son API et l'API des agents (`/api/agent/*`). |
 | `mcp-organizer` | **MCP** (stdio) : serveur MCP de l'agent, sans base ni logique métier. Configuré par `ORGANIZER_URL` et `ORGANIZER_TOKEN`, il relaie chaque appel d'outil à l'API des agents du site. Il peut tourner sur n'importe quelle machine, notamment dans une gateway de mcp-gateway-manager. |
 
-Autres commandes : `--setup` (installation du site : `.env`, unité systemd, bloc nginx, premier compte), `--set-user` (compte), `--backup` (sauvegarde de la base et des pièces jointes), `--claude-setup-mcp` (entrée `.mcp.json` du mode MCP), `--version`, `--help`. Chaque mode et chaque commande chargent leur code à la demande.
+Autres commandes : `--setup` (installation du site : `.env`, unité systemd, bloc nginx, premier compte), `--set-user` (compte), `--backup` (sauvegarde de la base et des pièces jointes), `--claude-setup-mcp` (entrée `.mcp.json` du mode MCP), `--watch` (veilleur de notifications de l'agent, lancé par son outil `Monitor`), `--version`, `--help`. Chaque mode et chaque commande chargent leur code à la demande.
 
 Prérequis : Node.js 20 ou plus récent.
 
@@ -201,12 +201,14 @@ Les outils MCP sont destinés à l'agent ; leurs schémas JSON sont écrits à l
 | `promote_idea` | `POST ideas/:id/promote` | Crée une tâche à partir d'une idée et marque l'idée promue |
 | `complete_request` | `POST requests/:id/complete` | Termine la demande avec la réponse à l'auteur |
 | `fail_request` | `POST requests/:id/fail` | Termine la demande en échec avec la raison |
+| `enable_notifications` | `GET notifications` | Exécuté par le mode MCP lui-même : dépose le relais du veilleur et rend l'appel `Monitor` à faire, ou, derrière mcp-http-gateway, la spécification de veille du relais (voir « Notifications de l'agent ») |
+| `wait_for_requests` | `GET requests/wait` | Outil d'attente du veilleur de la gateway : attend qu'une demande passe en attente (`cursor`, `timeout_seconds` de 1 à 50, `watcher`) et rend ses lignes et le curseur suivant dans `_meta["gateway/events"]` |
 
 Chaque écriture enregistre une action dans le lot de la demande (avec le jeton), crée une version de l'entité (avec le jeton), alimente le journal des changements et les notifications. Une erreur dit à l'agent quoi faire ensuite (« call claim_request on it first », « Call search_tasks to find it »…).
 
 ### Boucle de travail de l'agent
 
-Rien n'arrive tout seul à l'agent : il n'y a pas d'outil d'attente. L'utilisateur lui demande de traiter la file ; les `instructions` du serveur présentent les concepts (espace, tâche, demande, lot, portée) et la boucle :
+L'agent traite la file quand l'utilisateur le lui demande, ou quand son veilleur lui annonce une demande (voir « Notifications de l'agent ») ; les `instructions` du serveur présentent les concepts (espace, tâche, demande, lot, portée), les notifications et la boucle :
 
 1. `list_requests` ;
 2. `claim_request` sur la plus ancienne (`get_context` montre l'espace à tout moment) ;
@@ -218,6 +220,30 @@ Règles de traitement rappelées à l'agent : une **idée** se rattache à une t
 
 **Portée** : une demande vise l'espace où elle est écrite (l'espace ouvert dans l'interface) ; une review de test vise donc l'espace de sa tâche, une promotion d'idée l'espace de l'idée. Un jeton couvre un espace : son agent voit et traite les demandes de tous les membres de cet espace, avec les droits du propriétaire du jeton, et seulement là. Une demande prise par un jeton n'est traitée que par lui ; si l'agent s'arrête en cours de route, un membre la « Libère » depuis l'interface. Le jeton est revérifié à chaque appel ; quand son propriétaire quitte l'espace ou en est retiré, ses jetons sur cet espace sont révoqués et refusés dès l'appel suivant.
 
+### Notifications de l'agent
+
+L'agent peut être prévenu en temps réel des demandes qui passent en attente, sur le modèle de mcp-messenger. Le site ne pousse rien : un veilleur, sur la machine de l'agent, l'interroge en attente longue, et chaque ligne qu'il écrit réveille l'agent.
+
+1. En début de session, l'agent appelle `enable_notifications`. Le mode MCP lit sur le site le jeton, son espace, le nombre de demandes en attente et l'état du veilleur (`GET notifications`), écrit le **relais** puis rend l'appel `Monitor` exact : commande `npx -y @imenam/mcp-organizer --watch <id du jeton>`, `timeout_ms` 1 800 000.
+2. L'agent lance cette commande avec `Monitor`. Le veilleur est un processus du shell de la session, pas un enfant du mode MCP : il ne reçoit pas le bloc `env` du `.mcp.json`. L'identifiant du jeton, passé en argument, est public (ce n'est pas sa valeur) : il sert seulement à retrouver le relais.
+3. Le **relais** est un fichier `~/.mcp-organizer/watch/<sha256(id du jeton)>.json` en 0600, qui porte l'URL du site et le jeton ; la valeur du jeton n'apparaît donc jamais dans la conversation. Il est écrit par `enable_notifications`, jamais au démarrage, et supprimé à l'arrêt du mode MCP qui l'a écrit en dernier ; un relais de plus de 7 jours est purgé. `ORGANIZER_STATE_DIR` déplace le répertoire (`<ORGANIZER_STATE_DIR>/watch`), pour les tests. Sans relais, le veilleur refuse de démarrer et dit d'appeler `enable_notifications`.
+4. Le veilleur appelle `GET requests/wait?watcher=true` en boucle : chaque appel reste ouvert jusqu'à 50 s et répond dès qu'une demande de l'espace passe en attente (création, ou libération par un membre). Le curseur rendu, repassé en `since`, rattrape les demandes arrivées entre deux appels. Une panne réseau ou du site est réessayée avec un délai de 1 s à 30 s.
+5. Pour chaque demande, une ligne sur stdout : `[organizer] idea · Bob Martin — "Un mode sombre" · ORG-4 (<id de la demande>)` (type, auteur, extrait, tâche de contexte, identifiant). L'agent se réveille et la traite par la boucle de travail, en commençant par `claim_request`. Les demandes déjà en attente quand le veilleur démarre ne sont pas annoncées : `enable_notifications` en donne le nombre, `list_requests` les liste.
+6. Un refus du site (jeton révoqué, expiré, propriétaire retiré…) arrête le veilleur après une dernière ligne `[organizer] notifications stopped: <raison>`.
+
+L'hôte arrête un `Monitor` au bout de 30 minutes au plus : l'agent relance alors le même appel `Monitor`, sans rappeler `enable_notifications`.
+
+**Dans une gateway du gateway manager** (mcp-http-gateway), le mode MCP tourne sur la machine de la gateway et le veilleur sur celle de l'agent : un relais écrit par le mode MCP serait hors de portée du veilleur. Organizer suit alors la convention de veille de mcp-http-gateway, sans rien changer à la gateway ; pour l'agent, la démarche reste la même (`enable_notifications`, puis la commande rendue, avec `Monitor`).
+
+1. `enable_notifications` déclare la propriété réservée `_gateway_watch`. Le relais `--mcp` de la gateway la cache à l'agent et la remplit à chaque appel (`{ "version": 1 }`).
+2. Quand elle est remplie, le mode MCP n'écrit aucun fichier : il lit le curseur de départ (`GET notifications`) et rend la spécification `_meta["gateway/watch"] = { "tool": "wait_for_requests", "arguments": { "watcher": true }, "cursor": "<curseur>", "description": "New requests for the AI in the organizer" }`.
+3. Le relais écrit son fichier de veille sur la machine de l'agent (adresse et jeton de la gateway, route, outil, curseur) et rend à l'agent l'appel `Monitor` de son propre veilleur (`node <gateway>/server.js --watch <fichier>`) ; il répond lui-même « déjà actives » quand ce veilleur tourne.
+4. Ce veilleur appelle `wait_for_requests` à travers la gateway, en boucle, avec `cursor` et `timeout_seconds: 50` ; le mode MCP le relaie en `GET requests/wait?since=<curseur>&watcher=true` et rend `_meta["gateway/events"] = { "cursor", "lines" }`. Les lignes sont celles du veilleur local.
+
+Le jeton organizer reste sur la machine de la gateway. Le veilleur de la gateway ne s'arrête pas sur un refus : il l'annonce une fois (`[gateway-watch] … la veille échoue`) et réessaie.
+
+**Présence** : le site tient en mémoire, par jeton, les attentes en cours de son veilleur, avec un délai de grâce de 2 minutes entre deux attentes. `enable_notifications` répond « already live » quand un veilleur est déjà armé (en armer un second doublerait chaque notification), et la page Agent de l'interface affiche « à l'écoute » à côté du jeton. Les attentes du veilleur de la gateway comptent aussi (`watcher: true`).
+
 ### API des agents
 
 `/api/agent/*` sert le mode MCP ; n'importe quel client HTTP peut l'appeler avec un jeton.
@@ -225,6 +251,7 @@ Règles de traitement rappelées à l'agent : une **idée** se rattache à une t
 - **Authentification** : `Authorization: Bearer org_…`, revérifiée à chaque requête (jeton non révoqué, non expiré, propriétaire actif et toujours membre de l'espace) ; le dernier usage du jeton est mis à jour. Les cookies sont ignorés et le contrôle d'origine des modifications ne s'applique pas : sans cookie, une page tierce ne peut rien faire au nom d'un utilisateur.
 - **Codes** : 401 pour un jeton absent, inconnu, révoqué (y compris au départ de son propriétaire) ou expiré (avec `WWW-Authenticate: Bearer`) ; 403 pour un propriétaire inactif ou qui n'est plus membre, une tâche ou une idée d'un autre espace, ou une demande prise par un autre jeton ; 404 pour une demande, une tâche ou une route inconnue ; 409 pour un état qui interdit l'action (demande en attente ou close) ; 400 pour des paramètres invalides ; 500 pour une erreur interne, avec un message générique et une référence (voir « Sécurité »). Le corps d'une erreur est `{ "error": "<message qui dit quoi faire>" }`.
 - **Réponses** : `{ "text": "…", "data": { … } }`. `text` est le résultat rédigé pour l'agent (celui que renvoie l'outil) ; `data` porte les mêmes informations structurées, validées par les schémas zod de `shared/schemas/agent-tools.schema.ts`, partagés par le site et le mode MCP.
+- **Attente longue** : `GET requests/wait?timeout_seconds=<1-50>&since=<curseur>&watcher=true` rend les demandes de l'espace passées en attente depuis `since`, sinon attend la prochaine, au plus `timeout_seconds` (30 par défaut) ; `data` porte les demandes, le curseur suivant et `timedOut`. `watcher=true` compte l'attente dans la présence du veilleur du jeton. `GET notifications` donne le jeton, son espace, le nombre de demandes en attente et l'état du veilleur.
 - **Paramètres** : les noms des arguments des outils (`request_id`, `after_task`…) ; dans le chemin pour la tâche (`:ref`), l'idée et la demande, dans la requête pour un `GET`, dans le corps JSON sinon.
 
 ## Configuration
@@ -371,11 +398,12 @@ Chaque mutation ajoute à la table `changes` une ligne par entité touchée (`se
 ```
 src/index.ts          ligne de commande : aide, version, .env, choix du mode ou de la commande
 src/server/           mode site : configuration, serveur Hono, protections, limitation des connexions
-src/mcp/              mode MCP (stdio) : instructions, définitions des outils, client HTTP du site
+src/mcp/              mode MCP (stdio) : instructions, définitions des outils, client HTTP du site,
+                      enable_notifications et wait_for_requests (notifications.ts), relais du veilleur (watch-handoff.ts)
 src/agent-api/        routes /api/agent/* : logique des outils de l'agent, authentifiée par jeton
 src/gui-api.ts        routes /api/* de l'interface
 src/cli/              --setup (setup.ts), --set-user (set-user.ts), --backup (backup.ts),
-                      --claude-setup-mcp (setup-mcp.ts), saisies au terminal (prompt.ts)
+                      --claude-setup-mcp (setup-mcp.ts), --watch (watch.ts), saisies au terminal (prompt.ts)
 src/deploy/           fichiers écrits par --setup : .env fusionné (env-render.ts), unité systemd et bloc nginx (templates.ts)
 src/core/             base SQLite, migrations, store, comptes, espaces, tâches, tests, pièces jointes,
                       notifications, e-mail, dictée, file de l'agent, jetons d'agent, historique, .env, journaux, entrée .mcp.json
@@ -390,7 +418,7 @@ e2e/                  parcours Playwright sur le site réel ; captures dans e2e/
 
 Les tests ne lisent jamais la configuration du développeur : `test/launch.ts`, partagé par les tests node et les parcours e2e, lance chaque processus avec `--dotenv=<fichier vide du répertoire temporaire>` et vide toutes les variables de configuration héritées du shell. Le site de test est lancé en `--server` sur un port libre de `127.0.0.1`, avec `ORGANIZER_PUBLIC_URL=http://127.0.0.1:<port>` ; les outils sont appelés par un client MCP réel sur le mode MCP, relié à ce site par un jeton créé par l'API de l'interface (`ORGANIZER_URL`, `ORGANIZER_TOKEN`). Un test vérifie, sur une copie du package dont le `.env` détourne le répertoire de données, que ce `.env` n'atteint pas un processus lancé par les tests (et qu'il l'atteindrait sans `--dotenv`).
 
-**Tests node** : migrations, invariants, versions, journal des changements, connexions concurrentes ; comptes (amorçage avec nom obligatoire, `--set-user` et `--name`, connexion, sessions, liens d'accès, invitations, droits, e-mail) ; profil ; jetons d'agent (affichage unique, configuration du mode MCP, hash seul en base, révocation, expiration, perte d'appartenance, espace hors de portée) ; `--claude-setup-mcp` (entrée du mode MCP, `--url` et `--token` obligatoires, fusion, `--force`, options inconnues ou invalides, fichier illisible laissé intact) ; `--setup` (`.env`, unité systemd et bloc nginx écrits, premier compte créé, `.env` existant fusionné, publication sous un chemin, valeurs incohérentes ou manquantes refusées sans rien écrire, valeurs dotenv citées, site démarré depuis le `.env` écrit) ; `--backup` (copie de la base d'un site en service et de ses pièces jointes, restaurable ; destination existante refusée sans `--force` ; pièce jointe manquante qui ne laisse aucun fichier ; répertoire sans base refusé) ; `.env` et `--dotenv` ; tâches, tâches de test, pièces jointes, notifications, boîte à idées, dictée avec un serveur Groq simulé, historique et annulation ; chaque outil appelé par un client MCP du SDK sur le mode MCP relié à un site de test, jeton inconnu, révoqué ou expiré, site injoignable, espace hors portée, demande prise par un autre jeton, deux jetons de deux membres sur le même espace commun (prise atomique), mode MCP sans `ORGANIZER_URL` / `ORGANIZER_TOKEN`, mode MCP qui ne charge aucun module natif (crochet de résolution qui les bloque), `ORGANIZER_URL` en http refusée hors de la machine locale, redirection du site refusée sans y envoyer le jeton, `.env` du paquet ignoré par le mode MCP (lu avec `--dotenv`) ; commandes du site arrêtées avec la marche à suivre quand better-sqlite3 n'a pas de module natif (crochet de résolution qui simule l'échec) ; `list_requests` sur plus de 100 demandes closes (les plus récentes d'abord) ; jetons révoqués au départ ou au retrait de leur propriétaire, et migration qui révoque ceux des anciens membres ; erreurs internes au message générique ; sauvegarde privée pendant son écriture (droits observés hors Windows, test ignoré sous Windows) ; `--setup` qui refuse `--trust-proxy=oui` avec une écoute hors de la boucle locale, bloc nginx en `listen 443 ssl http2` ; API des agents en HTTP direct (401 et 403 explicites, cookies ignorés, écriture sans `Origin`, réponses validées par les schémas partagés) ; site : `--help` (qui cite `--setup` et `--backup`) et `--version`, refus de connexion sans compte avec les commandes d'une installation par clonage et du paquet npm, démarrage refusé sans `ORGANIZER_PUBLIC_URL` ou `PORT` ou avec un chemin de base incohérent, SPA et `<base href>`, cookie (`Path`, `Secure` en https), formulaires multipart et 413 ; protections : modification refusée sans origine ou d'une origine étrangère, en-têtes de sécurité, limitation des connexions par couple (IP, e-mail) et par IP, rafale de tentatives parallèles limitée, compte non bloqué par un tiers, `X-Forwarded-For` ignoré sans `ORGANIZER_TRUST_PROXY` et pris en compte avec.
+**Tests node** : migrations, invariants, versions, journal des changements, connexions concurrentes ; comptes (amorçage avec nom obligatoire, `--set-user` et `--name`, connexion, sessions, liens d'accès, invitations, droits, e-mail) ; profil ; jetons d'agent (affichage unique, configuration du mode MCP, hash seul en base, révocation, expiration, perte d'appartenance, espace hors de portée) ; `--claude-setup-mcp` (entrée du mode MCP, `--url` et `--token` obligatoires, fusion, `--force`, options inconnues ou invalides, fichier illisible laissé intact) ; `--setup` (`.env`, unité systemd et bloc nginx écrits, premier compte créé, `.env` existant fusionné, publication sous un chemin, valeurs incohérentes ou manquantes refusées sans rien écrire, valeurs dotenv citées, site démarré depuis le `.env` écrit) ; `--backup` (copie de la base d'un site en service et de ses pièces jointes, restaurable ; destination existante refusée sans `--force` ; pièce jointe manquante qui ne laisse aucun fichier ; répertoire sans base refusé) ; `.env` et `--dotenv` ; tâches, tâches de test, pièces jointes, notifications, boîte à idées, dictée avec un serveur Groq simulé, historique et annulation ; chaque outil appelé par un client MCP du SDK sur le mode MCP relié à un site de test, jeton inconnu, révoqué ou expiré, site injoignable, espace hors portée, demande prise par un autre jeton, deux jetons de deux membres sur le même espace commun (prise atomique), mode MCP sans `ORGANIZER_URL` / `ORGANIZER_TOKEN`, mode MCP qui ne charge aucun module natif (crochet de résolution qui les bloque), `ORGANIZER_URL` en http refusée hors de la machine locale, redirection du site refusée sans y envoyer le jeton, `.env` du paquet ignoré par le mode MCP (lu avec `--dotenv`) ; commandes du site arrêtées avec la marche à suivre quand better-sqlite3 n'a pas de module natif (crochet de résolution qui simule l'échec) ; `list_requests` sur plus de 100 demandes closes (les plus récentes d'abord) ; jetons révoqués au départ ou au retrait de leur propriétaire, et migration qui révoque ceux des anciens membres ; erreurs internes au message générique ; sauvegarde privée pendant son écriture (droits observés hors Windows, test ignoré sous Windows) ; `--setup` qui refuse `--trust-proxy=oui` avec une écoute hors de la boucle locale, bloc nginx en `listen 443 ssl http2` ; notifications de l'agent (présence et délai de grâce du veilleur, ligne d'une demande, `GET notifications`, attente longue réveillée par une demande créée ou libérée, curseur qui rattrape une demande arrivée entre deux attentes, expiration, jeton inconnu, durée hors limites ; `enable_notifications` puis veilleur `--watch` réel qui écrit une ligne par nouvelle demande, sans le jeton dans la conversation, « already live » une fois armé, arrêt sur jeton révoqué, refus de démarrer sans relais ; convention de mcp-http-gateway : propriété `_gateway_watch`, spécification de veille sans relais local, curseur de départ qui rattrape une demande, lignes et curseur de `wait_for_requests`, présence, arguments invalides) ; API des agents en HTTP direct (401 et 403 explicites, cookies ignorés, écriture sans `Origin`, réponses validées par les schémas partagés) ; site : `--help` (qui cite `--setup` et `--backup`) et `--version`, refus de connexion sans compte avec les commandes d'une installation par clonage et du paquet npm, démarrage refusé sans `ORGANIZER_PUBLIC_URL` ou `PORT` ou avec un chemin de base incohérent, SPA et `<base href>`, cookie (`Path`, `Secure` en https), formulaires multipart et 413 ; protections : modification refusée sans origine ou d'une origine étrangère, en-têtes de sécurité, limitation des connexions par couple (IP, e-mail) et par IP, rafale de tentatives parallèles limitée, compte non bloqué par un tiers, `X-Forwarded-For` ignoré sans `ORGANIZER_TRUST_PROXY` et pris en compte avec.
 
 **Parcours e2e** (site compilé en `--server`, port libre, répertoire de données temporaire, premier compte créé par `ORGANIZER_ADMIN_*`). Chaque page est surveillée : une exception ou une erreur de console, dont toute violation de la CSP, fait échouer le parcours.
 
@@ -398,7 +426,7 @@ Les tests ne lisent jamais la configuration du développeur : `test/launch.ts`,
 - connexion refusée puis réussie, création d'un espace commun, invitation, activation du compte invité par le lien dans un second navigateur ; invitation d'un second espace rejointe depuis « Invitations reçues », ancien lien refusé ;
 - tâches, sous-tâches et sous-sous-tâches, glisser-déposer entre colonnes et dans une colonne (persisté), assignation notifiée chez l'assignée ;
 - tâche de test à deux testeurs, résultats, review soumise qui crée une demande traitée par l'agent ; testeuse désassignée puis retirée, résultats conservés en lecture seule ;
-- idée saisie dans l'interface → demande en attente → traitement par un client MCP réel sur le mode MCP, avec un jeton créé par l'API de l'interface (tâche créée, statut et priorité changés) → réponse, actions, jeton qui a traité la demande et dernier passage de l'agent visibles → annulation d'une action puis du lot, tâche retirée du tableau de bord ; demande restée en cours libérée depuis la page Agent puis reprise ;
+- idée saisie dans l'interface → demande en attente → traitement par un client MCP réel sur le mode MCP, avec un jeton créé par l'API de l'interface (tâche créée, statut et priorité changés) → réponse, actions, jeton qui a traité la demande et dernier passage de l'agent visibles → annulation d'une action puis du lot, tâche retirée du tableau de bord ; demande restée en cours libérée depuis la page Agent puis reprise ; jeton dont le veilleur attend affiché « à l'écoute », réveillé par une demande ;
 - portée : les agents de Julie (un jeton sur son espace personnel, un sur l'espace commun) ne voient que les demandes de leur espace et ne lisent ni ne modifient l'espace personnel de Matthieu, sur lequel elle ne peut pas créer de jeton ;
 - panneau assistant, « Modifiée par l'agent · Annuler » et restauration d'une version ;
 - boîte à idées : promotion manuelle et promotion confiée à l'agent ;
@@ -425,7 +453,7 @@ Thème sombre, épuré, une seule action principale par écran. L'interface se r
 | **Détail d'un test** | Même gabarit avec « Test », la ligne « Teste ORG-41 … », la barre de bilan et « 9/12 vérifiés · 2 KO », un onglet par testeur, puis un onglet en lecture seule par ancien testeur (désassigné ou parti de l'espace), un résultat par point (OK, KO, Bloqué, À vérifier, avec commentaire), « Ma review » avec dictée et « Soumettre la review », reviews des autres testeurs repliées avec l'état de leur demande. |
 | **Saisir une idée** | Modale : texte, micro, « Envoyer » ; « L'agent la classera à son prochain passage ». |
 | **Assistant** | Panneau latéral : contexte « À propos de ORG-41 » (tâche ouverte), fil des demandes de l'utilisateur et des réponses de l'agent, statut, « Modifier · Annuler » en attente, « Libérer » en cours, nom du jeton qui traite ou a traité la demande (son propriétaire en infobulle), « N actions · Annuler ». |
-| **Agent** (`#/agent`) | État des agents de l'espace : chaque jeton actif qui le couvre, son propriétaire et son dernier passage (point allumé s'il date de moins de 10 min), ou « Aucun agent sur cet espace · Ajouter un agent » (lien vers Paramètres) ; « Filtrer » ; demandes En attente (crayon et croix au survol), En cours (jeton qui l'a prise, « Libérer »), Traitées (jeton qui l'a traitée ; elles se déplient : réponse, actions avec « Annuler », « Tout annuler »), Annulées repliées. |
+| **Agent** (`#/agent`) | État des agents de l'espace, rechargé toutes les 30 s : chaque jeton actif qui le couvre, son propriétaire et son dernier passage (point allumé s'il date de moins de 10 min), ou « à l'écoute » quand son veilleur de notifications est armé, ou « Aucun agent sur cet espace · Ajouter un agent » (lien vers Paramètres) ; « Filtrer » ; demandes En attente (crayon et croix au survol), En cours (jeton qui l'a prise, « Libérer »), Traitées (jeton qui l'a traitée ; elles se déplient : réponse, actions avec « Annuler », « Tout annuler »), Annulées repliées. |
 | **Idées** (`#/idees`) | Liste avec ajout rapide, idées classées par l'agent, « Promouvoir » ; tiroir « Promouvoir en tâche » : « Laisser l'agent la formater », ou « la remplir moi-même » (titre, type, priorité). |
 | **Membres** | Modale : invitation par adresse, membres et rôles, invitations en attente (renvoyer, révoquer, lien à copier quand l'e-mail ne part pas), renommer ou supprimer l'espace. |
 | **Invitations reçues** | Modale ouverte depuis le menu du sélecteur d'espace : pour chaque espace qui invite l'utilisateur, l'auteur de l'invitation, « Refuser » et « Rejoindre » (qui ouvre l'espace). |

package/dist/shared/schemas/agent-api.schema.d.ts

@@ -234,6 +234,7 @@ export declare const RequestListResponseSchema: z.ZodObject<{
         name: z.ZodString;
         ownerName: z.ZodString;
         lastUsedAt: z.ZodNullable<z.ZodISODateTime>;
+        listening: z.ZodBoolean;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type RequestListResponse = z.infer<typeof RequestListResponseSchema>;

package/dist/shared/schemas/agent-api.schema.js

@@ -75,8 +75,11 @@ export const RequestListResponseSchema = z.object({
     /** Demandes de l'espace, de la plus récente à la plus ancienne. */
     requests: z.array(RequestViewSchema),
     pendingCount: z.number().int().min(0),
-    /** Jetons actifs qui couvrent l'espace, du plus récemment utilisé au moins récemment. */
-    agents: z.array(AgentRefSchema.extend({ lastUsedAt: TimestampSchema.nullable() })),
+    /**
+     * Jetons actifs qui couvrent l'espace, du plus récemment utilisé au moins
+     * récemment ; `listening` : un veilleur de notifications de ce jeton est armé.
+     */
+    agents: z.array(AgentRefSchema.extend({ lastUsedAt: TimestampSchema.nullable(), listening: z.boolean() })),
 });
 /** Version d'une tâche dans son historique. */
 export const TaskVersionViewSchema = z.object({

package/dist/shared/schemas/agent-tools.schema.d.ts

@@ -25,6 +25,20 @@ export declare const ListRequestsQuerySchema: z.ZodObject<{
     }>>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strict>;
+/** Durée maximale d'une attente longue de `GET requests/wait`, en secondes. */
+export declare const MAX_WAIT_SECONDS = 50;
+/**
+ * `GET requests/wait` : durée de l'attente ; `since`, curseur rendu par
+ * l'attente précédente (les demandes passées en attente depuis sont rendues
+ * aussitôt) ; `watcher=true` pour un veilleur de notifications.
+ */
+export declare const WaitRequestsQuerySchema: z.ZodObject<{
+    timeout_seconds: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    since: z.ZodOptional<z.ZodISODateTime>;
+    watcher: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+    }>>;
+}, z.core.$strict>;
 /** `POST requests/:id/claim` : sans corps. */
 export declare const ClaimRequestBodySchema: z.ZodObject<{}, z.core.$strict>;
 export declare const CompleteRequestBodySchema: z.ZodObject<{
@@ -722,3 +736,88 @@ export declare const PromoteIdeaDataSchema: z.ZodObject<{
         tags: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+/** Présence d'un veilleur de notifications pour le jeton. */
+export declare const AgentWatcherSchema: z.ZodObject<{
+    armed: z.ZodBoolean;
+    since: z.ZodNullable<z.ZodISODateTime>;
+    lastSeen: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+/**
+ * `GET notifications` : jeton et espace de l'agent, demandes en attente,
+ * veilleur du jeton et curseur de départ d'une veille (`since` de la
+ * première attente : seules les demandes passées en attente ensuite sont rendues).
+ */
+export declare const NotificationsDataSchema: z.ZodObject<{
+    token: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>;
+    space: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            personal: "personal";
+            shared: "shared";
+        }>;
+        keyPrefix: z.ZodString;
+    }, z.core.$strip>;
+    pendingCount: z.ZodNumber;
+    watcher: z.ZodObject<{
+        armed: z.ZodBoolean;
+        since: z.ZodNullable<z.ZodISODateTime>;
+        lastSeen: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strip>;
+    cursor: z.ZodISODateTime;
+}, z.core.$strip>;
+/**
+ * `GET requests/wait` : demandes passées en attente (vide à l'expiration) et
+ * curseur à repasser en `since` à l'attente suivante.
+ */
+export declare const WaitRequestsDataSchema: z.ZodObject<{
+    space: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            personal: "personal";
+            shared: "shared";
+        }>;
+        keyPrefix: z.ZodString;
+    }, z.core.$strip>;
+    requests: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            idea: "idea";
+            idea_promotion: "idea_promotion";
+            message: "message";
+            remark: "remark";
+            test_review: "test_review";
+        }>;
+        status: z.ZodEnum<{
+            cancelled: "cancelled";
+            done: "done";
+            failed: "failed";
+            pending: "pending";
+            processing: "processing";
+        }>;
+        text: z.ZodString;
+        author: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            email: z.ZodString;
+        }, z.core.$strip>;
+        contextTask: z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            key: z.ZodString;
+            title: z.ZodString;
+        }, z.core.$strip>>;
+        contextIdeaId: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodISODateTime;
+        claimedAt: z.ZodNullable<z.ZodISODateTime>;
+        claimedByThisToken: z.ZodBoolean;
+        reply: z.ZodNullable<z.ZodString>;
+        failureReason: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    cursor: z.ZodISODateTime;
+    timedOut: z.ZodBoolean;
+}, z.core.$strip>;
+export type WaitRequestsData = z.infer<typeof WaitRequestsDataSchema>;

package/dist/shared/schemas/agent-tools.schema.js

@@ -26,6 +26,20 @@ export const ListRequestsQuerySchema = z
     limit: z.coerce.number().int().min(1).max(MAX_REQUEST_LIST_LIMIT).default(20),
 })
     .strict();
+/** Durée maximale d'une attente longue de `GET requests/wait`, en secondes. */
+export const MAX_WAIT_SECONDS = 50;
+/**
+ * `GET requests/wait` : durée de l'attente ; `since`, curseur rendu par
+ * l'attente précédente (les demandes passées en attente depuis sont rendues
+ * aussitôt) ; `watcher=true` pour un veilleur de notifications.
+ */
+export const WaitRequestsQuerySchema = z
+    .object({
+    timeout_seconds: z.coerce.number().int().min(1).max(MAX_WAIT_SECONDS).default(30),
+    since: TimestampSchema.optional(),
+    watcher: z.enum(["true"]).optional(),
+})
+    .strict();
 /** `POST requests/:id/claim` : sans corps. */
 export const ClaimRequestBodySchema = z.object({}).strict();
 export const CompleteRequestBodySchema = z.object({ reply: z.string().max(MAX_REPLY_LENGTH) }).strict();
@@ -163,3 +177,27 @@ export const ChecklistDataSchema = z.object({
 export const CommentDataSchema = z.object({ task: AgentTaskSummarySchema, commentId: IdSchema });
 export const IdeaDataSchema = z.object({ idea: AgentIdeaSchema });
 export const PromoteIdeaDataSchema = z.object({ idea: AgentIdeaSchema, task: AgentTaskSummarySchema });
+/** Présence d'un veilleur de notifications pour le jeton. */
+export const AgentWatcherSchema = z.object({ armed: z.boolean(), since: TimestampSchema.nullable(), lastSeen: TimestampSchema.nullable() });
+/**
+ * `GET notifications` : jeton et espace de l'agent, demandes en attente,
+ * veilleur du jeton et curseur de départ d'une veille (`since` de la
+ * première attente : seules les demandes passées en attente ensuite sont rendues).
+ */
+export const NotificationsDataSchema = z.object({
+    token: z.object({ id: IdSchema, name: z.string() }),
+    space: AgentSpaceSchema,
+    pendingCount: z.number().int().min(0),
+    watcher: AgentWatcherSchema,
+    cursor: TimestampSchema,
+});
+/**
+ * `GET requests/wait` : demandes passées en attente (vide à l'expiration) et
+ * curseur à repasser en `since` à l'attente suivante.
+ */
+export const WaitRequestsDataSchema = z.object({
+    space: AgentSpaceSchema,
+    requests: z.array(AgentRequestSummarySchema),
+    cursor: TimestampSchema,
+    timedOut: z.boolean(),
+});

package/dist/src/agent-api/notifications.d.ts

@@ -0,0 +1,16 @@
+import { type AgentApiContext, type AgentApiRequest, type AgentApiResponse, type AgentRoute } from "./types.js";
+/**
+ * Notifications de l'agent : état (`GET notifications`) et attente longue
+ * des demandes qui passent en attente (`GET requests/wait`), appelée en
+ * boucle par le veilleur que lance `enable_notifications`.
+ */
+export declare const notificationRoutes: AgentRoute[];
+/**
+ * `GET requests/wait` : rend aussitôt les demandes passées en attente depuis
+ * `since`, sinon attend qu'une demande de l'espace du jeton passe en attente
+ * (création ou libération), au plus `timeout_seconds`. Le curseur rendu est
+ * l'horodatage de la dernière demande rendue, ou le point de départ de
+ * l'attente à l'expiration. Une attente `watcher=true` compte dans la
+ * présence du veilleur du jeton.
+ */
+export declare function waitForPendingRequests(ctx: AgentApiContext, request: AgentApiRequest, signal: AbortSignal): Promise<AgentApiResponse>;

package/dist/src/agent-api/notifications.js

@@ -0,0 +1,92 @@
+import { MAX_REQUEST_LIST_LIMIT, NoQuerySchema, NotificationsDataSchema, WaitRequestsDataSchema, WaitRequestsQuerySchema, } from "../../shared/schemas/agent-tools.schema.js";
+import { resolveAgentToken } from "../core/agent-tokens.js";
+import { requestData, requestLine, spaceData } from "../core/agent.js";
+import { parseInput, respond } from "./types.js";
+/**
+ * Notifications de l'agent : état (`GET notifications`) et attente longue
+ * des demandes qui passent en attente (`GET requests/wait`), appelée en
+ * boucle par le veilleur que lance `enable_notifications`.
+ */
+export const notificationRoutes = [
+    {
+        method: "GET",
+        path: "/notifications",
+        handle: ({ store }, { agent, query }) => {
+            parseInput(NoQuerySchema, query);
+            const watcher = store.watchers.status(agent.token.id);
+            const pendingCount = store.countPendingRequestsOfSpace(agent.space.id);
+            const state = watcher.armed ? `a watcher is armed for this token since ${watcher.since}` : "no watcher is armed for this token";
+            return respond(NotificationsDataSchema, `Space "${agent.space.name}": ${pendingCount} pending request(s); ${state}.`, {
+                token: { id: agent.token.id, name: agent.token.name },
+                space: spaceData(agent.space),
+                pendingCount,
+                watcher,
+                cursor: new Date().toISOString(),
+            });
+        },
+    },
+];
+/** Demandes en attente de l'espace du jeton modifiées strictement après `since`. */
+function pendingSince(ctx, agent, since) {
+    return ctx.store.listAgentRequestsTargeting(agent.space.id, "pending", MAX_REQUEST_LIST_LIMIT).filter((request) => request.updatedAt > since);
+}
+function waitResponse(ctx, agent, requests, cursor, timeoutSeconds) {
+    const data = {
+        space: spaceData(agent.space),
+        requests: requests.map((request) => requestData(ctx.store, agent, request)),
+        cursor,
+        timedOut: requests.length === 0,
+    };
+    if (requests.length === 0)
+        return respond(WaitRequestsDataSchema, `No new pending request in "${agent.space.name}" after ${timeoutSeconds}s.`, data);
+    const lines = requests.map((request) => requestLine(ctx.store, agent, request)).join("\n");
+    return respond(WaitRequestsDataSchema, `${requests.length} new pending request(s) in "${agent.space.name}":\n${lines}\n\nNext: call claim_request with the id of the oldest request.`, data);
+}
+/**
+ * `GET requests/wait` : rend aussitôt les demandes passées en attente depuis
+ * `since`, sinon attend qu'une demande de l'espace du jeton passe en attente
+ * (création ou libération), au plus `timeout_seconds`. Le curseur rendu est
+ * l'horodatage de la dernière demande rendue, ou le point de départ de
+ * l'attente à l'expiration. Une attente `watcher=true` compte dans la
+ * présence du veilleur du jeton.
+ */
+export function waitForPendingRequests(ctx, request, signal) {
+    const agent = resolveAgentToken(ctx.store, request.bearer, ctx.now?.() ?? new Date());
+    const input = parseInput(WaitRequestsQuerySchema, request.query);
+    const startedAt = new Date().toISOString();
+    const since = input.since ?? null;
+    if (since !== null) {
+        const ready = pendingSince(ctx, agent, since);
+        if (ready.length > 0)
+            return Promise.resolve(waitResponse(ctx, agent, ready, ready.map((r) => r.updatedAt).sort().at(-1), input.timeout_seconds));
+    }
+    return new Promise((resolve) => {
+        const releaseWatcher = input.watcher ? ctx.store.watchers.begin(agent.token.id) : () => { };
+        const received = [];
+        let flush = null;
+        const stop = () => {
+            clearTimeout(timer);
+            if (flush)
+                clearImmediate(flush);
+            unsubscribe();
+            signal.removeEventListener("abort", onAbort);
+            releaseWatcher();
+        };
+        const finish = (requests, cursor) => {
+            stop();
+            resolve(waitResponse(ctx, agent, requests, cursor, input.timeout_seconds));
+        };
+        // Les demandes d'une même mutation arrivent ensemble : elles partent dans la même réponse.
+        const unsubscribe = ctx.store.onPendingRequest((pending) => {
+            if (pending.targetSpaceId !== agent.space.id || pending.status !== "pending")
+                return;
+            received.push(pending);
+            flush ??= setImmediate(() => finish(received, received.map((r) => r.updatedAt).sort().at(-1)));
+        });
+        const timer = setTimeout(() => finish([], since ?? startedAt), input.timeout_seconds * 1000);
+        const onAbort = () => stop();
+        signal.addEventListener("abort", onAbort);
+        if (signal.aborted)
+            stop();
+    });
+}

package/dist/src/agent-api/router.js

@@ -2,6 +2,7 @@ import { resolveAgentToken } from "../core/agent-tokens.js";
 import { NotFoundError, OrganizerError } from "../core/errors.js";
 import { checklistRoutes } from "./checklist.js";
 import { ideaRoutes } from "./ideas.js";
+import { notificationRoutes } from "./notifications.js";
 import { requestRoutes } from "./requests.js";
 import { taskRoutes } from "./tasks.js";
 function compile(route) {
@@ -12,7 +13,7 @@ function compile(route) {
     });
     return { route, pattern: new RegExp(`^${source}$`), keys };
 }
-const ROUTES = [...requestRoutes, ...taskRoutes, ...checklistRoutes, ...ideaRoutes].map(compile);
+const ROUTES = [...requestRoutes, ...taskRoutes, ...checklistRoutes, ...ideaRoutes, ...notificationRoutes].map(compile);
 /** Segment de chemin décodé ; un encodage `%` invalide est une erreur 400. */
 function decodeSegment(raw) {
     try {

package/dist/src/cli/watch.d.ts

@@ -0,0 +1 @@
+export declare function runWatchMode(tokenId: string | undefined): Promise<number>;

package/dist/src/cli/watch.js

@@ -0,0 +1,54 @@
+import { MAX_WAIT_SECONDS } from "../../shared/schemas/agent-tools.schema.js";
+import { ConfigError } from "../core/errors.js";
+import { OrganizerSiteClient, SiteError } from "../mcp/client.js";
+import { formatRequestEvent } from "../mcp/notifications.js";
+import { readHandoff } from "../mcp/watch-handoff.js";
+/**
+ * Mode veilleur (`--watch <identifiant du jeton>`).
+ *
+ * Une ligne sur stdout = une demande passée en attente. Ce flux est consommé
+ * par l'outil `Monitor` de l'hôte, qui réveille la session de l'agent à chaque
+ * ligne, y compris quand elle est inactive. Le journal part sur stderr.
+ *
+ * Une panne réseau ou du site est réessayée avec un délai croissant. Un refus
+ * du site (jeton révoqué, expiré, route inconnue) arrête le veilleur après une
+ * dernière ligne qui en donne la raison.
+ */
+const BACKOFF_MIN_MS = 1_000;
+const BACKOFF_MAX_MS = 30_000;
+/** Refus définitif du site : un nouvel essai donnerait la même réponse. */
+function isRefusal(error) {
+    return error instanceof SiteError && error.status !== undefined && error.status >= 400 && error.status < 500 && error.status !== 408 && error.status !== 429;
+}
+export async function runWatchMode(tokenId) {
+    if (!tokenId || tokenId.startsWith("--")) {
+        throw new ConfigError("--watch needs the token id given by the enable_notifications tool: `mcp-organizer --watch <token id>`.");
+    }
+    const handoff = readHandoff(tokenId);
+    if (!handoff) {
+        throw new ConfigError(`No notification handoff for token ${tokenId}: call the enable_notifications tool of the organizer MCP server, then arm the watcher with the command it returns.`);
+    }
+    const client = new OrganizerSiteClient({ url: handoff.url, token: handoff.token });
+    process.stderr.write(`watching token ${tokenId} on ${handoff.url}\n`);
+    let since;
+    let backoff = BACKOFF_MIN_MS;
+    for (;;) {
+        try {
+            const result = await client.waitForRequests({ timeout_seconds: MAX_WAIT_SECONDS, since, watcher: true });
+            backoff = BACKOFF_MIN_MS;
+            since = result.cursor;
+            for (const request of result.requests)
+                process.stdout.write(`${formatRequestEvent(request)}\n`);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            if (isRefusal(error)) {
+                process.stdout.write(`[organizer] notifications stopped: ${detail.replace(/\s+/g, " ")}\n`);
+                return 1;
+            }
+            process.stderr.write(`wait failed, retrying in ${Math.round(backoff / 1000)}s: ${detail}\n`);
+            await new Promise((resolve) => setTimeout(resolve, backoff));
+            backoff = Math.min(backoff * 2, BACKOFF_MAX_MS);
+        }
+    }
+}

package/dist/src/core/requests.d.ts

@@ -40,7 +40,8 @@ export declare function releaseRequest(store: Store, userId: string, requestId:
 export declare function getRequest(store: Store, userId: string, requestId: string): RequestView;
 /**
  * Demandes d'un espace, avec le nombre de demandes en attente et les jetons
- * actifs qui couvrent l'espace, chacun avec son dernier usage.
+ * actifs qui couvrent l'espace, chacun avec son dernier usage et la présence
+ * de son veilleur de notifications.
  */
 export declare function listRequests(store: Store, userId: string, spaceId: string, now?: Date): RequestListResponse;
 /** Annule une action de l'agent. */

package/dist/src/core/requests.js

@@ -190,7 +190,8 @@ export function getRequest(store, userId, requestId) {
 }
 /**
  * Demandes d'un espace, avec le nombre de demandes en attente et les jetons
- * actifs qui couvrent l'espace, chacun avec son dernier usage.
+ * actifs qui couvrent l'espace, chacun avec son dernier usage et la présence
+ * de son veilleur de notifications.
  */
 export function listRequests(store, userId, spaceId, now = new Date()) {
     requireMember(store, spaceId, userId);
@@ -198,7 +199,7 @@ export function listRequests(store, userId, spaceId, now = new Date()) {
     const agents = store
         .listAgentTokensOfSpace(spaceId)
         .filter((token) => tokenState(store, token, now) === "active")
-        .map((token) => ({ ...agentRef(store, token), lastUsedAt: token.lastUsedAt }));
+        .map((token) => ({ ...agentRef(store, token), lastUsedAt: token.lastUsedAt, listening: store.watchers.status(token.id).armed }));
     return { requests, pendingCount: store.countPendingRequestsOfSpace(spaceId), agents };
 }
 // --- Annulation -----------------------------------------------------------------

package/dist/src/core/store.d.ts

@@ -1,4 +1,5 @@
 import type Database from "better-sqlite3";
+import { WatcherRegistry } from "./watchers.js";
 import { type EntityType, type MemberRole, type RequestKind, type RequestStatus, type SpaceKind, type TaskPriority, type TaskStatus, type TaskType, type TestResultValue, type AccessLinkPurpose, type AgentOperation, type UserStatus, type VersionedEntityType } from "../../shared/schemas/enums.schema.js";
 import { type AccessLink, type AgentAction, type AgentRequest, type AgentToken, type Attachment, type Change, type ChecklistItem, type Comment, type EntityVersion, type Idea, type Invitation, type Membership, type Notification, type Session, type Space, type Tag, type Task, type TaskSnapshot, type TestCheckpoint, type TestResult, type TestReview, type User, type UserSettings } from "../../shared/schemas/entities.schema.js";
 /**
@@ -24,6 +25,9 @@ export declare class Store {
     readonly db: Database.Database;
     private activeMutation;
     private emailListener;
+    private readonly pendingRequestListeners;
+    /** Présence des veilleurs de notifications, par jeton d'agent. */
+    readonly watchers: WatcherRegistry;
     constructor(db: Database.Database);
     /** Ouvre (et migre) la base du répertoire de données. */
     static open(dataDir: string): Store;
@@ -180,6 +184,12 @@ export declare class Store {
      * créées.
      */
     setEmailListener(listener: ((notificationIds: string[]) => void) | null): void;
+    /**
+     * Abonne `listener` aux demandes qui passent en attente (créées, ou
+     * libérées par un membre) : il les reçoit après la validation de la
+     * mutation. La fonction rendue désabonne.
+     */
+    onPendingRequest(listener: (request: AgentRequest) => void): () => void;
     /**
      * Point unique d'écriture. `fn` reçoit une `Mutation` et s'exécute dans une
      * transaction exclusive ; à sa sortie, les invariants sont vérifiés sur l'état
@@ -287,6 +297,8 @@ export declare class Mutation {
     private readonly touched;
     /** Notifications créées par la mutation dont le destinataire veut un e-mail. */
     readonly emailNotificationIds: string[];
+    /** Demandes passées en attente par la mutation : créées, ou libérées. */
+    readonly pendingRequestIds: string[];
     /** Demande pour laquelle agit l'agent, lue au début de la mutation. */
     private readonly request;
     /** Jeton avec lequel agit l'agent. */