Sesión y entrega

源码版本v2026.7.20

Responsabilidad

Dos tareas: ① Sesión (Session) — agrupar «de dónde viene el mensaje» (plataforma, chat, remitente) bajo una clave estable y persistir la conversación a disco, para que el agent continúe el contexto entre reinicios; ② Libro de entrega (Delivery Ledger) — anota para la respuesta final del agent una «obligación de entrega», de modo que tras un crash pueda identificar respuestas no entregadas y reenviarlas, garantizando que el usuario las reciba. Ambas viven en la capa del gateway, desacopladas del agent.

Archivos clave

• class SessionSource:149-299 — dataclass del origen del mensaje (platform/chat/sender, con hash)
• class SessionContext:299-700 — contexto de sesión (key, origen, estrategia de continuación)
• hash de id:40-74 — _hash_id / _hash_sender_id / _hash_chat_id (privacidad + estabilidad)
• validación de seguridad de ruta:100-149 — _is_path_unsafe / _is_session_key_unsafe (la session key fluye a una ruta del sistema de archivos)
• ventana de auto_continue:26-40 — auto_continue_freshness_window
• doc del libro de entrega:1-58 — objetivo de diseño: best-effort, los fallos nunca bloquean el flujo principal
• compute_obligation_id:146-155 — id único de obligación (session key + ref de mensaje + contenido)
• máquina de estados:155-203 — record_obligation / mark_attempting / mark_delivered / mark_failed
• sweep_recoverable:203-276 — tras un crash, explora obligaciones recuperables y las reenvía
• conexión SQLite:77-102 — _db_path / _connect, persistencia en sqlite local

Flujo de datos

1. El adaptador recibe un evento de plataforma, del que extrae SessionSource vía MessageEvent:1759.
2. SessionSource:149 hashea un id estable de chat/sender (gateway/session.py:40).
3. Se construye un SessionContext:299, obteniendo la session key (tras validación de seguridad de ruta:109, se usa como ruta en disco).
4. La session key determina desde qué archivo se carga el historial, que se entrega al agent para continuar el contexto.
5. Tras producir la respuesta final, el gateway anota en record_obligation:155 → envía → mark_delivered.
6. Si el envío cae a mitad, en el siguiente arranque sweep_recoverable (gateway/delivery_ledger.py:203) explora obligaciones en estado attempting cuyo proceso propietario ya no existe, y las reenvía o marca como fallidas.

Resumen

La capa de sesión se encarga de «a qué conversación continua pertenece este mensaje»: con hash + validación de ruta proyecta identidades externas a archivos en disco de forma segura. El libro de entrega se encarga de «si la respuesta final que el agent quería enviar realmente llegó al usuario»: una máquina de estados en sqlite hace la recuperación tras crash. Ambas son best-effort pero imprescindibles como capa de fiabilidad.