Session et livraison

源码版本v2026.7.20

Responsabilité

Deux choses : (1) Session — associer « d'où vient le message » (plateforme, chat, expéditeur) à une clé stable et persister la conversation sur disque, pour que l'agent puisse reprendre le contexte entre redémarrages ; (2) Registre de livraison (Delivery Ledger) — enregistrer pour la réponse finale de l'agent une « obligation de livraison » ; après un crash, identifier les réponses non livrées et les réexpédier, pour garantir que l'utilisateur finit par les recevoir. Les deux vivent dans la couche passerelle, découplés de l'agent.

Fichiers clés

• class SessionSource:149-299 — dataclass de la source du message (platform/chat/sender, avec hash)
• class SessionContext:299-700 — contexte de session (clé, source, stratégie de reprise)
• hash d'id:40-74 — _hash_id / _hash_sender_id / _hash_chat_id (confidentialité + stabilité)
• validation de sécurité des chemins:100-149 — _is_path_unsafe / _is_session_key_unsafe (la clé de session se retrouve dans un chemin du système de fichiers)
• fenêtre de fraîcheur auto_continue:26-40 — auto_continue_freshness_window
• doc du registre de livraison:1-58 — objectif de conception : best-effort, un échec ne bloque jamais le flux principal
• compute_obligation_id:146-155 — id unique d'obligation (clé de session + ref message + contenu)
• machine à états:155-203 — record_obligation / mark_attempting / mark_delivered / mark_failed
• sweep_recoverable:203-276 — après un crash, balaye les obligations récupérables et les réexpédie
• connexion SQLite:77-102 — _db_path / _connect, persistance en sqlite locale

Flux de données

1. L'adaptateur reçoit l'événement de la plateforme, remonte un SessionSource via MessageEvent:1759.
2. SessionSource:149 produit par hash des id stables de chat/sender (gateway/session.py:40).
3. Construction d'un SessionContext:299 pour obtenir la clé de session (utilisée comme chemin disque après validation de sécurité des chemins:109).
4. La clé de session décide depuis quel fichier l'historique est chargé, puis alimente l'agent pour reprendre le contexte.
5. Une fois la réponse finale produite par l'agent, la passerelle enregistre l'obligation dans record_obligation:155 → envoi → mark_delivered.
6. En cas de crash pendant l'envoi, au prochain démarrage sweep_recoverable (gateway/delivery_ledger.py:203) balaie les obligations à l'état attempting dont le processus propriétaire est mort, les réexpédie ou les marque comme échouées.

Résumé

La couche de session gère « à quelle conversation continue appartient ce message », en mappant l'identité externe vers un fichier disque via hash + validation de chemin. Le registre de livraison gère « la réponse finale que l'agent voulait envoyer est-elle vraiment arrivée à l'utilisateur », via une machine à états sqlite pour la récupération après crash. Les deux sont best-effort mais indispensables à la fiabilité.