[Bug] Group image caption can be overtaken by a following text message

[PeiPei233]

Description

When built-in group chat context awareness and image captioning are enabled, a text message sent immediately after an image can overtake the image while its caption is being generated.

The LLM request triggered by the text message then receives no context for the preceding image. If captioning fails, the stored group context also loses the image completely and contains only the sender/timestamp prefix.

Reproduction Steps

1. Enable built-in group chat context awareness.
2. Enable group image captioning with a vision provider.
3. Send an image to a group.
4. Immediately send a text comment about that image.
5. Trigger an LLM response from the text message.
6. Inspect the injected group context.

This is also reproducible without third-party plugins by invoking GroupChatContext.handle_message() concurrently: block the first image caption call, then handle a following plain-text event. The plain-text event completes first on current master.

Expected: the image record is completed before the later text record and is included in the text-triggered LLM request.

Actual: the text record can be appended first and the request contains no image caption.

AstrBot Version

v4.27.2 and master at a9bb8a6

Operating System

Linux

Deployment Method

Docker (soulter/astrbot:latest)

Message Platform Adapter

OneBot v11 (NapCat / aiocqhttp)

Error Log

[Core] [INFO] [core.event_bus]: user: [image]
[Core] [INFO] [core.event_bus]: user: text commenting on the image
[Plug] [DBUG] [astrbot.group_chat_context]: [user]: text commenting on the image
[Core] [DBUG] [agent_sub_stages.internal]: ready to request llm provider
[Plug] [DBUG] [astrbot.group_chat_context]: [user]: [Image: caption completed later]

There is no exception in the successful-caption case. Each event is dispatched in its own task while handle_message() waits for _format_message() before acquiring its per-session lock and appending the record.

On caption failure, the related log is:

[Plug] [ERRO] [astrbot.group_chat_context]: 获取图片描述失败: <provider error>
[Plug] [DBUG] [astrbot.group_chat_context]: [user/time]:

Supplementary Information

The issue is in the built-in GroupChatContext; a direct unit-level reproduction loads no third-party plugins.

Checklist

• I searched existing issues and PRs. perf(ltm): pre-caption images outside session lock to unblock subsequent messages #7228 discusses a related main-agent/session-lock tradeoff, but it does not modify the built-in GroupChatContext path and was closed without merging.
• Reproduced directly against the built-in class without loading plugins.
• This is an AstrBot core issue rather than a plugin issue.
• I have read and agree to the project's Code of Conduct.
• I am willing to submit a PR to fix this issue.

[dosubot]

Hi @PeiPei233! I'm Dosu and I'm helping the AstrBotTeam team.

Good analysis. The race condition is clearly visible in the code. In handle_message(), await self._format_message(event, cfg) runs before the per-session lock is acquired [1]. Inside _format_message, the await get_image_caption(...) call yields with no lock held [2]. So the sequence is:

1. Image event → _format_message starts, yields at await get_image_caption(...)
2. Text event → _format_message completes instantly (no async work), acquires the lock, appends its record first
3. Image event resumes, acquires the lock, appends its record after the text record

Because on_req_llm builds the context from raw_list[:prompt_idx] [3], the text-triggered LLM request never sees the image caption.

A few possible fix approaches:

• Reserve a placeholder slot before captioning: acquire the lock, insert a sentinel/Future at the correct position, release the lock, then fill it in after captioning completes. on_req_llm would need to await any pending futures in the records slice before building the context block.
• Timestamp-ordered insertion: record arrival time before the async caption call and insert into the deque in timestamp order rather than append order.
• Serial per-session queue: serialize handle_message calls per umo through an asyncio.Queue so later messages wait for earlier ones to finish formatting.

The slot-reservation pattern is probably the most targeted — it avoids serializing unrelated events across different groups and keeps lock duration short. Since you mentioned willingness to submit a PR, that would be a good starting point.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.