feat: Telegram adapter — session lifecycle, memory compaction & crash recovery

[henrieopenclaw]

Supersedes #60. Full Telegram adapter replacing Discord, plus team/personal chat modes.

Architecture

graph LR
    U(["👤 Telegram User"]) <-->|Bot API| AB["agent-broker (Rust)"]
    AB <-->|"ACP stdio JSON-RPC"| CLI["kiro-cli / claude / codex / gemini"]

Loading

Chat Modes

	Personal (default)	Team
Any message in #general	Auto-creates topic, replies	Silent buffer 👀
@mention in #general	Auto-creates topic, replies	Replies in-place
!kiro in #general	Auto-creates topic	Creates topic (restricted to topic_creator_id)
Plain message in topic	Replies directly	Silent buffer 👀
@mention in topic	Replies directly	Replies directly

Session Lifecycle

flowchart TD
    M([User message]) --> GC[get_or_create]
    GC -->|alive| USE[use existing session]
    GC -->|dead/new| SP[spawn CLI]
    SP --> SN[session/new or session/load]
    SN --> PC{pending_context?}
    PC -->|yes| PP[prepend summary]
    PC -->|no| ST
    PP --> ST[stream_prompt]
    ST --> PD[prompt_done]
    PD --> CI[cleanup_idle every 15min]
    CI --> IT{idle > TTL?}
    IT -->|yes| CO[compact → evict → notify]
    CO --> SS[summary stored, injected on resume]

Loading

Memory Management

Idle Eviction

flowchart TD
    A([User idle for 2 hours]) --> B[cleanup_idle detects idle > TTL]
    B --> C[Send compaction prompt to live kiro process]
    C --> D[Receive summary → store in summaries]
    D --> E[Kill kiro process, notify user ⏱]
    E --> F([User sends next message])
    F --> G[Spawn new kiro → inject summary]
    G --> H[Kiro remembers previous conversation ✅]

Loading

Crash Recovery

flowchart TD
    A([User sends message]) --> B[record_user_message → VecDeque max 20]
    B --> C{... kiro crashes ...}
    C --> D[cleanup_idle detects !alive]
    D --> E[Attempt compaction → fails]
    E --> F[Fallback: VecDeque → Recent messages before crash]
    F --> G[Store in summaries]
    G --> H([User sends next message])
    H --> I[Spawn new kiro → inject crash context]
    I --> J[Kiro recalls recent context ✅ partial memory]

Loading

Key changes

• Telegram adapter replacing Discord (teloxide)
• Forum topic threading — one topic per conversation
• personal vs team mode via config.toml
• Memory compaction — summarizes session before eviction, injects on resume
• Crash recovery — stores last 20 user messages as fallback context when kiro crashes before compaction
• Deadlock fix — silent_prompt/rename_topic no longer hold write lock during stream
• Security fix (relates to [Security] Empty allowed_channels should not default to allowing all channels #91) — bot refuses to start if allowed_users is empty
• Resilient streaming — 200ms drain window, 30s alive check, 30min hard timeout
• Session recovery — on crash/timeout: partial summary stored, session evicted so next message resumes with context
• Mermaid diagrams replacing ASCII throughout README

Known limitations (marked as WORKAROUND in code)

• stream_prompt still holds the write lock for its duration — a hung task blocks other messages until timeout fires. Proper fix requires lock-free streaming (same pattern as silent_prompt).
• Drain window (200ms) and hard timeout (30min) are hardcoded — should be configurable.
• These are workarounds pending better ACP lifecycle signals (heartbeat, cancellation, sequence numbers).