fix: enforce temp-marked tool-call pairs are marked together

Partial mark_as_temp() on an injected pair would persist a dangling
assistant(tool_calls) message that providers reject on the next round.
Validate _no_save consistency in ToolCallsResult.to_openai_messages_model()
so mismatched pairs fail fast at injection time. Also switch Message.
mark_as_temp() to a TypeVar return type (matching ContentPart) and move
comments to English per AGENTS.md.

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

Author: Rail1bc

astrbot/core/agent/message.py

@@ -14,6 +14,7 @@
 from pydantic_core import core_schema
 
 ContentPartT = TypeVar("ContentPartT", bound="ContentPart")
+MessageT = TypeVar("MessageT", bound="Message")
 
 
 class ContentPart(BaseModel):
@@ -215,11 +216,15 @@ class Message(BaseModel):
     _no_save: bool = PrivateAttr(default=False)
     _checkpoint_after: CheckpointData | None = PrivateAttr(default=None)
 
-    def mark_as_temp(self) -> "Message":
+    def mark_as_temp(self: MessageT) -> MessageT:
         """Mark this message as provider-facing only, not persisted.
 
-        临时注入（如伪造工具调用对）应成对标记：assistant 与 tool 消息都调用
-        本方法，避免历史中残留悬空的 tool 消息。
+        Injected pairs (e.g. fake tool-call results) should mark both the
+        assistant and tool messages so no dangling tool message remains in
+        history.
+
+        Returns:
+            Self, for method chaining.
         """
         self._no_save = True
         return self

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

@@ -465,8 +465,9 @@ async def _save_to_history(
             if message.role == "system" and not skipped_initial_system:
                 skipped_initial_system = True
                 continue
-            # _no_save 语义与角色无关：临时注入的消息（含伪造工具调用对的
-            # tool 消息）一律不落库，避免历史中残留悬空的 tool 消息。
+            # _no_save is role-agnostic: temp-injected messages (including the
+            # tool message of a fake tool-call pair) are never persisted, so no
+            # dangling tool message remains in history.
             if message._no_save:
                 continue
             messages_to_save.append(message)

astrbot/core/provider/entities.py

@@ -81,6 +81,16 @@ def to_openai_messages(self) -> list[dict]:
     def to_openai_messages_model(
         self,
     ) -> list[AssistantMessageSegment | ToolCallMessageSegment]:
+        # A tool-call pair must be marked temp together (or not at all): a
+        # partial mark would persist a dangling assistant(tool_calls) that
+        # providers reject on the next round.
+        info_is_temp = self.tool_calls_info._no_save
+        if any(message._no_save != info_is_temp for message in self.tool_calls_result):
+            raise ValueError(
+                "ToolCallsResult pair must be marked temp together: call "
+                "mark_as_temp() on both tool_calls_info and every message in "
+                "tool_calls_result, or on neither."
+            )
         return [
             self.tool_calls_info,
             *self.tool_calls_result,

docs/zh/dev/star/plugin.md

@@ -614,6 +614,10 @@ tool_calls_info=AssistantMessageSegment(...).mark_as_temp(),
 tool_calls_result=[ToolCallMessageSegment(...).mark_as_temp()],
 ```
 
+> **注意**：`.mark_as_temp()` 必须成对使用。只标记其中一方会导致历史中残留悬空的
+> `assistant(tool_calls)` 或 `tool` 消息，下一轮 provider API 会拒绝该请求。
+> 若标记不一致，runner 在组装上下文时会抛出 `ValueError` 提醒。
+
 > 这里不能使用 yield 来发送消息。如需发送，请直接使用 `event.send()` 方法。
 
 ##### LLM 请求完成时

tests/test_tool_loop_agent_runner.py

@@ -1596,12 +1596,12 @@ async def test_reset_appends_injected_tool_calls_result_after_user(
                         },
                     }
                 ]
-            ),
+            ).mark_as_temp(),
             tool_calls_result=[
                 ToolCallMessageSegment(
                     tool_call_id="fake_1",
                     content="memory json",
-                )
+                ).mark_as_temp()
             ],
         ),
     )
@@ -1619,6 +1619,122 @@ async def test_reset_appends_injected_tool_calls_result_after_user(
     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"
+    # _no_save 标记经 reset() 追加后保留，持久化时才会被过滤。
+    assert runner.run_context.messages[-2]._no_save is True
+    assert runner.run_context.messages[-1]._no_save is True
+
+
+@pytest.mark.asyncio
+async def test_reset_appends_multiple_injected_tool_calls_results_in_order(
+    runner, mock_provider, mock_tool_executor, mock_hooks
+):
+    """list 形式的多个 ToolCallsResult 按列表顺序追加在 user 消息之后。"""
+    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 1",
+                    )
+                ],
+            ),
+            ToolCallsResult(
+                tool_calls_info=AssistantMessageSegment(
+                    tool_calls=[
+                        {
+                            "id": "fake_2",
+                            "type": "function",
+                            "function": {
+                                "name": "recall_short_term_memory",
+                                "arguments": "{}",
+                            },
+                        }
+                    ]
+                ),
+                tool_calls_result=[
+                    ToolCallMessageSegment(
+                        tool_call_id="fake_2",
+                        content="memory json 2",
+                    )
+                ],
+            ),
+        ],
+    )
+
+    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",
+        "assistant",
+        "tool",
+    ]
+    tool_calls = [
+        m.tool_calls[0].id
+        for m in runner.run_context.messages
+        if m.role == "assistant" and m.tool_calls
+    ]
+    assert tool_calls == ["fake_1", "fake_2"]
+    tool_results = [
+        m.tool_call_id for m in runner.run_context.messages if m.role == "tool"
+    ]
+    assert tool_results == ["fake_1", "fake_2"]
+
+
+def test_injected_tool_calls_result_partial_temp_mark_raises():
+    """只标记对中一方时抛 ValueError，防止悬空 assistant(tool_calls) 落库。"""
+    partial = ToolCallsResult(
+        tool_calls_info=AssistantMessageSegment(
+            tool_calls=[
+                {
+                    "id": "fake_1",
+                    "type": "function",
+                    "function": {
+                        "name": "recall",
+                        "arguments": "{}",
+                    },
+                }
+            ]
+        ).mark_as_temp(),
+        tool_calls_result=[
+            ToolCallMessageSegment(
+                tool_call_id="fake_1",
+                content="memory json",
+            )
+        ],
+    )
+
+    with pytest.raises(ValueError, match="marked temp together"):
+        partial.to_openai_messages_model()
 
 
 @pytest.mark.asyncio
@@ -1631,8 +1747,6 @@ async def test_runner_with_openai_provider_preserves_injected_tool_calls_order(
     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(