feat: concat chunked Telegram messages for multi-part pastes (#186)

[IliyaBrook]

Summary

When a user pastes text longer than 4096 characters, the Telegram client silently splits it into multiple messages. Previously, each fragment triggered a separate Claude run — wasteful, slow, and producing poor results since Claude would see incomplete text fragments.

This PR adds a per-user debounce buffer that detects Telegram-split chunks (messages near the 4096-char limit), accumulates them, and submits the combined text as a single Claude request.

How it works

• Messages >= 4000 chars (configurable) are considered potential chunks and buffered
• A 500ms debounce timer (configurable) waits for more chunks to arrive
• Short "tail" chunks flush the buffer immediately — no timer wait needed
• Chunks are joined with no delimiter ("".join()) since Telegram splits at character boundaries
• User sees "Receiving message…" while buffering, then the normal "Working..." flow
• Stop button cancels pending buffers
• Per-user lock prevents concurrent Claude runs from timer-fired flushes

New settings

• CHUNK_BUFFER_TIMEOUT (default 0.5) — seconds to wait for more chunks
• CHUNK_BUFFER_THRESHOLD (default 4000) — min message length to trigger buffering

Changed files

• src/bot/utils/message_buffer.py — new MessageBuffer class
• src/bot/orchestrator.py — extracted _process_agentic_text(), added buffer logic to agentic_text()
• src/config/settings.py — new settings
• src/utils/constants.py — new defaults
• tests/unit/test_bot/test_message_buffer.py — 20 unit tests
• tests/unit/test_bot/test_middleware.py — fixture update for new settings

Test plan

• All 550 existing tests pass
• 20 new unit tests for MessageBuffer (chunk detection, buffering, timer flush, cancel, key independence, concatenation)
• Manually tested with ~27k char paste (7 chunks) — single "Receiving message…" → single Claude response

Closes #186

[MatveyF]

Hey, thank you for the PR
I have one suggestion - the default CHUNK_BUFFER_THRESHOLD of 4000 may be too high. In my testing, Telegram's client splits at paragraph/line boundaries rather than at the 4096 char limit itself, so chunks can land well below 4000. I had a real case where the first chunk was 3397 chars, which slipped under a 3500 threshold I was testing locally and fired as a separate Claude run.

Or maybe at least add a note to the docs.

[IliyaBrook]

Good catch, thanks! You're right — I had the same thought after reading your example. I've lowered the default CHUNK_BUFFER_THRESHOLD from 4000 to 3000, which should cover the paragraph/line-boundary splits you described (including your 3397-char case).

[RichardAtCT]

Good work — the buffer is well built and the tests drive real timers. Four things before I merge.

1. The join mashes words together. constants.py:94 justifies the 3000 threshold by saying clients split at paragraph and line boundaries. A client that splits there drops the separator. _pop_result then joins with "" (message_buffer.py:218), so the last word of one chunk runs into the first word of the next.

The threshold rationale and the join cannot both be right. Join with "\n", or keep "" and say why.

2. There is no off switch. chunk_buffer_threshold is clamped ge=2000 and there is no feature flag, so every message over 3000 characters now waits 0.5s and gets a "Receiving message…" send-and-delete. An operator cannot turn that off. Please allow 0 to disable.

Also: the description says the default is 4000, the code says 3000, and neither setting is in .env.example. Your tests all use 4000, so the shipped default is untested.

3. Timer-flushed runs skip the global lock. _on_buffer_flush runs _process_agentic_text in a detached task under a per-user lock only, outside StopAwareUpdateProcessor._sequential_lock. No deadlock, but two users Claude runs can now overlap where they could not before.

That may be fine, or even wanted — but it is a real change to how the bot serialises work and it is not mentioned. Tell me it is deliberate and I am happy.

4. Stop drops a pending buffer silently. orchestrator.py:1773 cancels the buffer, throws the result away, then replies "Already completed." A paste made during a flushed run disappears with no message.

Worth adding one orchestrator-level test too — the buffer itself is covered, the wiring is not.

Item 1 is the one that would bite users.