Session & Delivery

源码版本v2026.7.20

Responsibility

Two things: (1) Session — attribute "where the message came from" (platform, chat, sender) to a stable key, and persist the conversation to disk so the agent can continue with context across restarts; (2) Delivery Ledger — record a "delivery obligation" for the agent's final reply, so that after a crash undelivered replies can be identified and re-sent, guaranteeing the user ultimately receives them. Both live in the gateway layer, decoupled from the agent.

Key Files

• class SessionSource:149-299 — message source dataclass (platform/chat/sender, with hash)
• class SessionContext:299-700 — session context (key, source, continuation strategy)
• id hashing:40-74 — _hash_id / _hash_sender_id / _hash_chat_id (privacy + stability)
• path safety check:100-149 — _is_path_unsafe / _is_session_key_unsafe (session keys flow into filesystem paths)
• auto_continue freshness window:26-40 — auto_continue_freshness_window
• delivery ledger docs:1-58 — design goal: best-effort, never blocks the main flow on failure
• compute_obligation_id:146-155 — unique obligation id (session key + message ref + content)
• state machine:155-203 — record_obligation / mark_attempting / mark_delivered / mark_failed
• sweep_recoverable:203-276 — scan recoverable obligations after a crash and re-send
• SQLite connection:77-102 — _db_path / _connect, persisted in local sqlite

Data Flow

1. The adapter receives a platform event and carries SessionSource out via MessageEvent:1759.
2. SessionSource:149 hashes out a stable chat/sender id (gateway/session.py:40).
3. A SessionContext:299 is constructed, yielding a session key (used as a disk path after the path safety check:109).
4. The session key decides which file to load history from, fed to the agent to continue context.
5. After the agent produces its final reply, the gateway records it in record_obligation:155 → sends → mark_delivered.
6. If a crash happens during send, the next startup's sweep_recoverable (gateway/delivery_ledger.py:203) scans for obligations in attempting state whose owning process is dead, and re-sends or marks them failed.

Summary

The session layer owns "which ongoing conversation this message belongs to", mapping external identities safely to disk files via hashing + path validation. The delivery ledger owns "whether the agent's intended final reply actually reached the user", using a sqlite state machine for crash recovery. Both are best-effort but critical reliability layers.