fix: consume injected tool call results in tool loop runner

Plugins can inject fake assistant(tool_calls) → tool(result) pairs via
req.append_tool_calls_result(); reset() now appends them after the current
user message so the block belongs to the current turn, matching how
providers assemble the text_chat payload. Export the segment/result types
from astrbot.api.provider and make _save_to_history skip any _no_save
message regardless of role, so temp-marked fake pairs never persist.

Co-Authored-By: deepseek-v4-flash <deepseek-ai@claude-code-best.win>

Author: Rail1bc

astrbot/api/provider/__init__.py

@@ -1,18 +1,26 @@
+from astrbot.core.agent.message import (
+    AssistantMessageSegment,
+    ToolCallMessageSegment,
+)
 from astrbot.core.db.po import Personality
 from astrbot.core.provider import Provider, STTProvider
 from astrbot.core.provider.entities import (
     LLMResponse,
     ProviderMetaData,
     ProviderRequest,
     ProviderType,
+    ToolCallsResult,
 )
 
 __all__ = [
+    "AssistantMessageSegment",
     "LLMResponse",
     "Personality",
     "Provider",
     "ProviderMetaData",
     "ProviderRequest",
     "ProviderType",
     "STTProvider",
+    "ToolCallMessageSegment",
+    "ToolCallsResult",
 ]

astrbot/core/agent/message.py

@@ -215,6 +215,15 @@ class Message(BaseModel):
     _no_save: bool = PrivateAttr(default=False)
     _checkpoint_after: CheckpointData | None = PrivateAttr(default=None)
 
+    def mark_as_temp(self) -> "Message":
+        """Mark this message as provider-facing only, not persisted.
+
+        临时注入（如伪造工具调用对）应成对标记：assistant 与 tool 消息都调用
+        本方法，避免历史中残留悬空的 tool 消息。
+        """
+        self._no_save = True
+        return self
+
     @model_validator(mode="after")
     def check_content_required(self):
         if self.role == CHECKPOINT_ROLE:

astrbot/core/agent/runners/tool_loop_agent_runner.py

@@ -315,6 +315,20 @@ async def reset(
         ):
             m = await self._assemble_request_context_for_provider(request)
             messages.append(Message.model_validate(m))
+        # Plugin-injected tool call results (on_llm_request → req.append_tool_calls_result)
+        # follow the current user message so the assistant(tool_calls) → tool(result)
+        # block belongs to the current turn. Providers consume the same
+        # ProviderRequest.tool_calls_result in this order (see text_chat payload
+        # assembly), so binding it here keeps the in-run context identical to what
+        # a plain provider call would send.
+        if request.tool_calls_result:
+            tool_call_results = (
+                request.tool_calls_result
+                if isinstance(request.tool_calls_result, list)
+                else [request.tool_calls_result]
+            )
+            for tcr in tool_call_results:
+                messages.extend(tcr.to_openai_messages_model())
         if request.system_prompt:
             messages.insert(
                 0,

astrbot/core/pipeline/process_stage/method/agent_sub_stages/internal.py

@@ -465,7 +465,9 @@ async def _save_to_history(
             if message.role == "system" and not skipped_initial_system:
                 skipped_initial_system = True
                 continue
-            if message.role in ["assistant", "user"] and message._no_save:
+            # _no_save 语义与角色无关：临时注入的消息（含伪造工具调用对的
+            # tool 消息）一律不落库，避免历史中残留悬空的 tool 消息。
+            if message._no_save:
                 continue
             messages_to_save.append(message)
 

docs/zh/dev/star/plugin.md

@@ -561,6 +561,61 @@ async def my_custom_hook_1(self, event: AstrMessageEvent, req: ProviderRequest):
 
 > 这里不能使用 yield 来发送消息。如需发送，请直接使用 `event.send()` 方法。
 
+###### 注入工具调用结果
+
+> 适用于 AstrBot 版本 > v4.27.3
+
+如果希望 LLM 在回答本轮问题时"看到"一次工具调用及其结果（例如插件自行检索了长期记忆后，将结果包装成一次记忆召回的工具调用），不要直接向 `req.contexts` 追加消息，而应通过 `req.append_tool_calls_result()` 注入。runner 会保证最终消息顺序为：
+
+```
+history → 当前 user → assistant(tool_calls) → tool(result)
+```
+
+```python
+from astrbot.api.event import filter, AstrMessageEvent
+from astrbot.api.provider import (
+    ProviderRequest,
+    ToolCallsResult,
+    AssistantMessageSegment,
+    ToolCallMessageSegment,
+)
+
+@filter.on_llm_request()
+async def inject_memory_recall(self, event: AstrMessageEvent, req: ProviderRequest):
+    tool_call_id = "fake_recall_memory"
+    req.append_tool_calls_result(
+        ToolCallsResult(
+            tool_calls_info=AssistantMessageSegment(
+                tool_calls=[
+                    {
+                        "id": tool_call_id,
+                        "type": "function",
+                        "function": {
+                            "name": "recall_long_term_memory",
+                            "arguments": '{"query": "..."}',
+                        },
+                    }
+                ]
+            ),
+            tool_calls_result=[
+                ToolCallMessageSegment(
+                    tool_call_id=tool_call_id,
+                    content="<memory json>",
+                )
+            ],
+        )
+    )
+```
+
+注入的工具调用结果**默认会随会话历史持久化**。如果只希望参与本轮请求、不落库，请对 assistant 与 tool 消息**成对**调用 `.mark_as_temp()`：
+
+```python
+tool_calls_info=AssistantMessageSegment(...).mark_as_temp(),
+tool_calls_result=[ToolCallMessageSegment(...).mark_as_temp()],
+```
+
+> 这里不能使用 yield 来发送消息。如需发送，请直接使用 `event.send()` 方法。
+
 ##### LLM 请求完成时
 
 在 LLM 请求完成后，会触发 `on_llm_response` 钩子。

tests/test_conversation_checkpoint.py

@@ -331,6 +331,65 @@ async def test_terminal_tool_result_persists_history_without_checkpoint():
     )
 
 
+@pytest.mark.asyncio
+async def test_temp_injected_tool_pair_not_persisted():
+    """临时注入的伪造工具调用对（成对 mark_as_temp）整对不落库，不残留悬空 tool 消息。"""
+    conversation_manager = AsyncMock()
+    stage = InternalAgentSubStage()
+    stage.conv_manager = conversation_manager
+    event = SimpleNamespace(
+        unified_msg_origin="webchat:FriendMessage:test",
+        get_extra=lambda _key: None,
+    )
+    fake_info = AssistantMessageSegment(
+        tool_calls=[
+            {
+                "id": "fake_1",
+                "type": "function",
+                "function": {"name": "recall", "arguments": "{}"},
+            }
+        ]
+    ).mark_as_temp()
+    fake_result = ToolCallMessageSegment(
+        tool_call_id="fake_1",
+        content="mem",
+    ).mark_as_temp()
+    request = ProviderRequest(
+        conversation=Conversation(
+            platform_id="webchat",
+            user_id="webchat:FriendMessage:test",
+            cid="conversation-1",
+        ),
+        tool_calls_result=ToolCallsResult(
+            tool_calls_info=fake_info,
+            tool_calls_result=[fake_result],
+        ),
+    )
+
+    await stage._save_to_history(
+        event,
+        request,
+        LLMResponse(role="assistant", completion_text="ok"),
+        [
+            Message(role="user", content="hello"),
+            fake_info,
+            fake_result,
+            ToolCallMessageSegment(tool_call_id="real_1", content="real result"),
+        ],
+        runner_stats=None,
+    )
+
+    conversation_manager.update_conversation.assert_awaited_once_with(
+        "webchat:FriendMessage:test",
+        "conversation-1",
+        history=[
+            {"role": "user", "content": "hello"},
+            {"role": "tool", "tool_call_id": "real_1", "content": "real result"},
+        ],
+        token_usage=None,
+    )
+
+
 @pytest.mark.asyncio
 async def test_terminal_tool_result_with_checkpoint_uses_none_token_usage():
     conversation_manager = AsyncMock()

tests/test_tool_loop_agent_runner.py

@@ -14,13 +14,24 @@
 from astrbot.core.agent.agent import Agent
 from astrbot.core.agent.handoff import HandoffTool
 from astrbot.core.agent.hooks import BaseAgentRunHooks
-from astrbot.core.agent.message import ImageURLPart, Message, TextPart
+from astrbot.core.agent.message import (
+    AssistantMessageSegment,
+    ImageURLPart,
+    Message,
+    TextPart,
+    ToolCallMessageSegment,
+)
 from astrbot.core.agent.run_context import ContextWrapper
 from astrbot.core.agent.runners.tool_loop_agent_runner import ToolLoopAgentRunner
 from astrbot.core.agent.tool import FunctionTool, ToolSet
 from astrbot.core.astr_agent_tool_exec import FunctionToolExecutor
 from astrbot.core.exceptions import EmptyModelOutputError
-from astrbot.core.provider.entities import LLMResponse, ProviderRequest, TokenUsage
+from astrbot.core.provider.entities import (
+    LLMResponse,
+    ProviderRequest,
+    TokenUsage,
+    ToolCallsResult,
+)
 from astrbot.core.provider.provider import Provider
 
 
@@ -1559,6 +1570,156 @@ async def test_tool_result_injects_follow_up_notice(
     assert ticket2.consumed is True
 
 
+@pytest.mark.asyncio
+async def test_reset_appends_injected_tool_calls_result_after_user(
+    runner, mock_provider, mock_tool_executor, mock_hooks
+):
+    """reset() 把 on_llm_request 注入的 tool_calls_result 追加在当前 user 消息之后。
+
+    最终顺序：history → 当前 user → assistant(tool_calls) → tool(result)。
+    """
+    request = ProviderRequest(
+        prompt="当前问题",
+        contexts=[
+            {"role": "user", "content": "历史消息"},
+            {"role": "assistant", "content": "历史回答"},
+        ],
+        tool_calls_result=ToolCallsResult(
+            tool_calls_info=AssistantMessageSegment(
+                tool_calls=[
+                    {
+                        "id": "fake_1",
+                        "type": "function",
+                        "function": {
+                            "name": "recall_long_term_memory",
+                            "arguments": "{}",
+                        },
+                    }
+                ]
+            ),
+            tool_calls_result=[
+                ToolCallMessageSegment(
+                    tool_call_id="fake_1",
+                    content="memory json",
+                )
+            ],
+        ),
+    )
+
+    await runner.reset(
+        provider=mock_provider,
+        request=request,
+        run_context=ContextWrapper(context=None),
+        tool_executor=mock_tool_executor,
+        agent_hooks=mock_hooks,
+        streaming=False,
+    )
+
+    roles = [m.role for m in runner.run_context.messages]
+    assert roles == ["user", "assistant", "user", "assistant", "tool"]
+    assert runner.run_context.messages[-2].tool_calls[0].id == "fake_1"
+    assert runner.run_context.messages[-1].tool_call_id == "fake_1"
+
+
+@pytest.mark.asyncio
+async def test_runner_with_openai_provider_preserves_injected_tool_calls_order(
+    mock_tool_executor, mock_hooks
+):
+    """端到端：runner 消费注入的 tool_calls_result 后，OpenAI payload 顺序保持正确。
+
+    覆盖 ToolLoopAgentRunner → ProviderOpenAIOfficial.text_chat → _query 的完整
+    payload 组装路径（真实 provider，仅对 SDK create 的入口 _query 打桩捕获）。
+    顺序：history → 当前 user → assistant(tool_calls) → tool(result)。
+    """
+    from astrbot.core.agent.tool import FunctionTool, ToolSet
+    from astrbot.core.provider.entities import ToolCallsResult
+    from astrbot.core.provider.sources.openai_source import ProviderOpenAIOfficial
+
+    provider = ProviderOpenAIOfficial(
+        provider_config={
+            "id": "test-openai",
+            "type": "openai_chat_completion",
+            "model": "gpt-4o-mini",
+            "key": ["test-key"],
+        },
+        provider_settings={},
+    )
+    captured: dict[str, list[dict[str, Any]]] = {}
+
+    async def fake_query(payloads, func_tool, *, request_max_retries=None):
+        captured["messages"] = [dict(m) for m in payloads["messages"]]
+        return LLMResponse(role="assistant", completion_text="ok")
+
+    provider._query = fake_query  # type: ignore[method-assign]
+
+    tool_set = ToolSet(
+        tools=[
+            FunctionTool(
+                name="test_tool",
+                description="测试工具",
+                parameters={
+                    "type": "object",
+                    "properties": {"query": {"type": "string"}},
+                },
+                handler=AsyncMock(),
+            )
+        ]
+    )
+    request = ProviderRequest(
+        prompt="当前问题",
+        func_tool=tool_set,
+        contexts=[
+            {"role": "user", "content": "历史消息"},
+            {"role": "assistant", "content": "历史回答"},
+        ],
+        tool_calls_result=ToolCallsResult(
+            tool_calls_info=AssistantMessageSegment(
+                tool_calls=[
+                    {
+                        "id": "fake_1",
+                        "type": "function",
+                        "function": {
+                            "name": "recall_long_term_memory",
+                            "arguments": "{}",
+                        },
+                    }
+                ]
+            ),
+            tool_calls_result=[
+                ToolCallMessageSegment(
+                    tool_call_id="fake_1",
+                    content="memory json",
+                )
+            ],
+        ),
+    )
+
+    runner = ToolLoopAgentRunner()
+    try:
+        await runner.reset(
+            provider=provider,
+            request=request,
+            run_context=ContextWrapper(context=None),
+            tool_executor=mock_tool_executor,
+            agent_hooks=mock_hooks,
+            streaming=False,
+        )
+        async for _ in runner.step():
+            pass
+    finally:
+        await provider.terminate()
+
+    assert [m["role"] for m in captured["messages"]] == [
+        "user",
+        "assistant",
+        "user",
+        "assistant",
+        "tool",
+    ]
+    assert captured["messages"][-2]["tool_calls"][0]["id"] == "fake_1"
+    assert captured["messages"][-1]["tool_call_id"] == "fake_1"
+
+
 @pytest.mark.asyncio
 async def test_follow_up_ticket_not_consumed_when_no_next_tool_call(
     runner, mock_provider, provider_request, mock_tool_executor, mock_hooks