agstack 1.25.1__tar.gz → 2.0.0__tar.gz

{agstack-1.25.1 → agstack-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.25.1
+Version: 2.0.0
 Summary: Production-ready toolkit for building FastAPI and LLM applications
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{agstack-1.25.1 → agstack-2.0.0}/agstack/llm/flow/agent.py

@@ -10,7 +10,7 @@ from ..client import get_llm_client
 from . import event
 from .context import Usage
 from .event import EventType
-from .exceptions import FlowError
+from .exceptions import AgentError, FlowError
 
 
 if TYPE_CHECKING:
@@ -32,6 +32,7 @@ class Agent:
         max_turns: int = 10,
         *,
         tool_choice: str = "auto",
+        on_max_turns: str = "finalize",
         label: str | None = None,
         echo: bool = False,
     ):
@@ -44,6 +45,7 @@ class Agent:
         :param temperature: 温度参数
         :param max_tokens: 最大 token 数
         :param max_turns: 最大轮次
+        :param on_max_turns: max_turns 耗尽时的行为，"finalize"（降级输出并标记 truncated）或 "error"（抛出异常）
         :param label: 面向用户的展示名称（控制 STEP 进度事件可见性）
         :param echo: 是否转发 TEXT_MESSAGE 给用户
         """
@@ -55,6 +57,7 @@ class Agent:
         self.max_tokens = max_tokens
         self.max_turns = max_turns
         self.tool_choice = tool_choice
+        self.on_max_turns = on_max_turns
         self.label = label
         self.echo = echo
 
@@ -117,6 +120,7 @@ class Agent:
         client = get_llm_client()
 
         # Agent 循环
+        assistant_content = ""
         for _ in range(self.max_turns):
             context.increment_turn()
 
@@ -257,11 +261,21 @@ class Agent:
                     )
                     continue
 
-                # 解析 LLM 返回的工具参数
+                # 解析 LLM 返回的工具参数；解析失败作为该次调用的失败反馈给模型，由模型自行重试
                 try:
                     tool_args = json.loads(tool_call["arguments"]) if tool_call["arguments"] else {}
-                except json.JSONDecodeError:
-                    tool_args = {}
+                except json.JSONDecodeError as e:
+                    error_content = json.dumps(
+                        {
+                            "error": f"Invalid tool arguments (JSON parse failed): {e}",
+                            "raw_arguments": tool_call["arguments"][:500],
+                        },
+                        ensure_ascii=False,
+                    )
+                    context.add_message(self.name, "tool", content=error_content, tool_call_id=tool_call["id"])
+                    # AG-UI: TOOL_CALL_RESULT (错误)
+                    yield event.tool_call_result(tool_call_id=tool_call["id"], content=error_content)
+                    continue
 
                 # 执行前进度事件
                 progress_label = tool.get_progress_label(tool_args)
@@ -323,3 +337,18 @@ class Agent:
 
             # 更新消息列表，继续下一轮
             messages = [self.get_system_message()] + context.history + context.get_messages(self.name)
+
+        # max_turns 耗尽：必须显式收尾，禁止静默截断
+        if self.on_max_turns == "error":
+            error_msg = f"Agent {self.name} exceeded max_turns={self.max_turns}"
+            yield event.run_error(message=error_msg, code="AGENT_MAX_TURNS_EXCEEDED")
+            raise AgentError("AGENT_MAX_TURNS_EXCEEDED", 500, {"agent": self.name})
+
+        # finalize：最后一轮已生成的部分文本作为降级输出，带截断标记
+        yield event.custom(
+            name="agent_max_turns",
+            value={"agentName": self.name, "maxTurns": self.max_turns},
+        )
+        context.set_output(self.name, {"result": assistant_content, "truncated": True})
+        yield event.text_message_end(message_id=msg_id)
+        context.set_variable("_agent_call_id", None)

{agstack-1.25.1 → agstack-2.0.0}/agstack/llm/flow/context.py

@@ -80,6 +80,10 @@ class FlowContext:
         """设置变量值"""
         self.variables[key] = value
 
+    def pop_variable(self, key: str, default: Any = None) -> Any:
+        """取出并移除变量"""
+        return self.variables.pop(key, default)
+
     def update_variables(self, updates: dict[str, Any]) -> None:
         """批量更新变量"""
         self.variables.update(updates)

{agstack-1.25.1 → agstack-2.0.0}/agstack/llm/flow/flow.py

@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING, Any, AsyncIterator
 from uuid import uuid4
 
 from . import event
+from .context import Usage
 from .exceptions import NodeExecutionError
 
 
@@ -39,6 +40,23 @@ def _parse_literal(s: str) -> Any:
     return s
 
 
+def _usage_snapshot(usage: Usage) -> tuple[int, int, int]:
+    """记录节点执行前的用量快照，用于差值归因"""
+    return (usage.prompt_tokens, usage.completion_tokens, usage.total_tokens)
+
+
+def _usage_delta(usage: Usage, before: tuple[int, int, int]) -> Usage | None:
+    """节点执行前后的用量差值；全零返回 None，避免 trace 体积膨胀"""
+    delta = Usage(
+        prompt_tokens=usage.prompt_tokens - before[0],
+        completion_tokens=usage.completion_tokens - before[1],
+        total_tokens=usage.total_tokens - before[2],
+    )
+    if delta.prompt_tokens or delta.completion_tokens or delta.total_tokens:
+        return delta
+    return None
+
+
 @dataclass
 class RetryPolicy:
     """节点重试策略"""
@@ -262,120 +280,14 @@ class Flow:
         return False
 
     async def run(self, context: "FlowContext") -> dict[str, Any]:
-        """执行 Flow"""
-        if not self.edges:
-            for node in self.nodes:
-                node_id = node.get("id")
-                if not node_id:
-                    continue
-                context.current_node = node_id
-                node_type: str = node.get("type", "")
-                handler = self._node_handlers.get(node_type)
-                if handler:
-                    result = await handler.execute(node, context)
-                    context.set_output(node_id, result)
-                else:
-                    raise NodeExecutionError("UNKNOWN_NODE_TYPE", args={"node_type": node_type})
-        else:
-            current_node_id: str | None = self.nodes[0]["id"] if self.nodes else None
-            visit_count: dict[str, int] = {}
-
-            while current_node_id:
-                node = self.get_node_config(current_node_id)
-                if not node:
-                    break
-
-                # 循环计数与超限检测
-                visit_count[current_node_id] = visit_count.get(current_node_id, 0) + 1
-                force_fallback = self._check_cycle_limit(current_node_id, visit_count)
-                if force_fallback:
-                    current_node_id = self._resolve_next_node(current_node_id, context, force_fallback=True)
-                    continue
-
-                context.current_node = current_node_id
-                node_type: str = node.get("type", "")
-
-                if node_type == "message":
-                    config = node.get("config", {})
-                    template = config.get("content", "")
-                    text = template.format_map(_SafeFormatDict(context.variables))
-                    context.set_output(current_node_id, {"result": text})
-                    current_node_id = self._resolve_next_node(current_node_id, context)
-
-                elif node_type == "parallel":
-                    config = node.get("config", {})
-                    branches: list[str] = config.get("branches", [])
-
-                    async def _run_branch(branch_id: str) -> None:
-                        branch_node = self.get_node_config(branch_id)
-                        if not branch_node:
-                            return
-                        context.current_node = branch_id
-                        branch_type: str = branch_node.get("type", "")
-                        branch_handler = self._node_handlers.get(branch_type)
-                        if branch_handler:
-                            result = await branch_handler.execute(branch_node, context)
-                            context.set_output(branch_id, result)
-
-                    await asyncio.gather(*[_run_branch(bid) for bid in branches])
-                    merged: dict[str, Any] = {}
-                    for bid in branches:
-                        branch_result = context.outputs.get(bid, {})
-                        if isinstance(branch_result, dict):
-                            merged.update(branch_result)
-                    context.set_output(current_node_id, merged)
-                    current_node_id = self._resolve_next_node(current_node_id, context)
-
-                elif node_type == "iteration":
-                    config = node.get("config", {})
-                    items_ref = config.get("items", "")
-                    items = context.resolve_reference(items_ref) if isinstance(items_ref, str) else items_ref
-                    if not isinstance(items, list):
-                        items = [items]
-
-                    item_var = config.get("item_variable", "item")
-                    index_var = config.get("index_variable", "index")
-                    body_nodes: list[str] = config.get("body", [])
-                    results: list[Any] = []
-
-                    for idx, item in enumerate(items):
-                        context.set_variable(item_var, item)
-                        context.set_variable(index_var, idx)
-                        for body_node_id in body_nodes:
-                            body_node = self.get_node_config(body_node_id)
-                            if not body_node:
-                                continue
-                            body_type: str = body_node.get("type", "")
-                            body_handler = self._node_handlers.get(body_type)
-                            if body_handler:
-                                body_result = await body_handler.execute(body_node, context)
-                                context.set_output(body_node_id, body_result)
-                        if body_nodes:
-                            results.append(context.outputs.get(body_nodes[-1]))
-
-                    context.set_output(current_node_id, {"results": results})
-                    current_node_id = self._resolve_next_node(current_node_id, context)
-
-                elif node_type in self._node_handlers:
-                    handler = self._node_handlers[node_type]
-                    try:
-                        result = await handler.execute(node, context)
-                    except Exception as e:
-                        iter_target = self._find_iterator_fallback(current_node_id)
-                        if iter_target:
-                            context.set_variable(f"_iter_{iter_target}_error", str(e))
-                            context.set_output(current_node_id, {"error": str(e)})
-                            context.set_variable("_prev_node_id", current_node_id)
-                            current_node_id = iter_target
-                            continue
-                        raise
-                    context.set_output(current_node_id, result)
-                    context.set_variable("_prev_node_id", current_node_id)
-                    current_node_id = self._resolve_next_node(current_node_id, context)
-
-                else:
-                    raise NodeExecutionError("UNKNOWN_NODE_TYPE", args={"node_type": node_type})
+        """执行 Flow（非流式）
 
+        stream() 的消费包装：两条路径共享同一执行引擎，重试策略、
+        FlowTrace、output_mode、iterator 状态清理等行为完全一致。
+        节点失败抛 NodeExecutionError（包装原始异常）。
+        """
+        async for _ in self.stream(context):
+            pass
         return context.outputs
 
     async def stream(self, context: "FlowContext") -> AsyncIterator[dict[str, Any]]:
@@ -459,6 +371,7 @@ class Flow:
             if node_type == "message":
                 msg_config = node.get("config", {})
                 context.trace.record_node_start(current_node_id, "message", inputs=msg_config)
+                usage_before = _usage_snapshot(context.usage)
 
                 # message 节点增加 STEP 事件
                 msg_sid = str(uuid4())
@@ -485,7 +398,11 @@ class Flow:
                 fin_evt["_echo"] = msg_config.get("echo", True)
                 yield fin_evt
 
-                context.trace.record_node_end(current_node_id, outputs={"result": text})
+                context.trace.record_node_end(
+                    current_node_id,
+                    outputs={"result": text},
+                    usage=_usage_delta(context.usage, usage_before),
+                )
                 current_node_id = self._resolve_next_node(current_node_id, context)
 
             elif node_type == "parallel":
@@ -493,6 +410,7 @@ class Flow:
                 branches = config.get("branches", [])
 
                 context.trace.record_node_start(current_node_id, "parallel", inputs=config)
+                usage_before = _usage_snapshot(context.usage)
 
                 parallel_sid = str(uuid4())
                 step_evt = event.step_started(step_name=f"parallel:{current_node_id}", step_id=parallel_sid)
@@ -523,7 +441,12 @@ class Flow:
                     try:
                         result = await branch_handler.execute(branch_node, context)
                         context.set_output(branch_id, result)
-                        context.trace.record_node_end(branch_id, outputs=result)
+                        # 分支并发共享 context，差值无法按分支切分——分支不记 usage，整体归因容器节点
+                        context.trace.record_node_end(
+                            branch_id,
+                            outputs=result,
+                            error=context.pop_variable("_last_node_error"),
+                        )
                     except Exception as e:
                         context.trace.record_node_end(branch_id, error=str(e))
                         raise
@@ -542,7 +465,11 @@ class Flow:
                 fin_evt["_echo"] = False
                 yield fin_evt
 
-                context.trace.record_node_end(current_node_id, outputs=merged)
+                context.trace.record_node_end(
+                    current_node_id,
+                    outputs=merged,
+                    usage=_usage_delta(context.usage, usage_before),
+                )
                 current_node_id = self._resolve_next_node(current_node_id, context)
 
             elif node_type == "iteration":
@@ -586,6 +513,7 @@ class Flow:
                             parent_id=context.trace._qualify_id(current_node_id),
                             iteration_index=idx,
                         )
+                        body_usage_before = _usage_snapshot(context.usage)
                         body_result = await body_handler.execute(body_node, context)
                         context.set_output(body_node_id, body_result)
                         # 收集 body 节点产生的 execution_records
@@ -593,6 +521,8 @@ class Flow:
                         context.trace.record_node_end(
                             body_node_id,
                             outputs=body_result,
+                            error=context.pop_variable("_last_node_error"),
+                            usage=_usage_delta(context.usage, body_usage_before),
                             tool_calls=body_tool_calls if body_tool_calls else None,
                         )
                     if body_nodes:
@@ -607,6 +537,7 @@ class Flow:
                 fin_evt["_echo"] = False
                 yield fin_evt
 
+                # body 串行执行已按差值归因 usage，容器不重复归因
                 context.trace.record_node_end(current_node_id, outputs=iteration_output)
                 current_node_id = self._resolve_next_node(current_node_id, context)
 
@@ -622,6 +553,7 @@ class Flow:
                     inputs=resolved_inputs,
                     label=config.get("label"),
                 )
+                usage_before = _usage_snapshot(context.usage)
 
                 # output_mode: "append" — 保存执行前的历史
                 append_mode = config.get("output_mode") == "append"
@@ -666,6 +598,9 @@ class Flow:
                 context.trace.record_node_end(
                     current_node_id,
                     outputs=context.outputs.get(current_node_id),
+                    # 节点内部容错的失败（如 tool 节点 on_error: "continue"）经 context 传递
+                    error=context.pop_variable("_last_node_error"),
+                    usage=_usage_delta(context.usage, usage_before),
                     tool_calls=tool_calls if tool_calls else None,
                     messages=messages,
                 )

{agstack-1.25.1 → agstack-2.0.0}/agstack/llm/flow/nodes/tool_node.py

@@ -33,5 +33,10 @@ class ToolNodeHandler(NodeHandler):
         tool = self._create_tool(config)
         result = await tool.execute_async(context, inputs=resolved)
         if not result.success:
+            # on_error: "continue" — 失败降级为节点输出，flow 继续走边路由，
+            # 条件边可用 $o.<node>.success == false 分流；默认 "raise" 保持原语义
+            if config.get("on_error") == "continue":
+                context.set_variable("_last_node_error", result.error)
+                return {"success": False, "error": result.error}
             raise ToolExecutionError("TOOL_EXECUTION_FAILED", args={"tool_name": tool.name, "error": result.error})
         return result.result

{agstack-1.25.1 → agstack-2.0.0}/agstack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.25.1
+Version: 2.0.0
 Summary: Production-ready toolkit for building FastAPI and LLM applications
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{agstack-1.25.1 → agstack-2.0.0}/agstack.egg-info/SOURCES.txt

@@ -70,6 +70,7 @@ agstack/security/casbin.py
 agstack/security/crypt.py
 tests/test_cache_memory.py
 tests/test_cache_redis.py
+tests/test_flow_error_semantics.py
 tests/test_flow_io.py
 tests/test_flow_iterator.py
 tests/test_flow_switch_subflow.py

{agstack-1.25.1 → agstack-2.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agstack"
-version = "1.25.1"
+version = "2.0.0"
 description = "Production-ready toolkit for building FastAPI and LLM applications"
 readme = "README.md"
 license = "MIT"

agstack-2.0.0/tests/test_flow_error_semantics.py

@@ -0,0 +1,501 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""Flow 系统失败语义测试 — 1.26.0 修复的五项缺陷（D1-D5）验收用例
+
+D1: Agent max_turns 耗尽显式收尾
+D2: 工具参数 JSON 解析失败反馈给模型
+D3: tool 节点 on_error 开关
+D4: NodeTrace.usage 按节点归因
+D5: run() 收敛为 stream() 消费者
+"""
+
+import asyncio
+import json
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from agstack.llm.flow.agent import Agent
+from agstack.llm.flow.context import FlowContext
+from agstack.llm.flow.event import EventType
+from agstack.llm.flow.exceptions import AgentError, NodeExecutionError
+from agstack.llm.flow.flow import Flow
+from agstack.llm.flow.registry import registry
+from agstack.llm.flow.tool import Tool
+
+
+def _run(coro):
+    return asyncio.get_event_loop().run_until_complete(coro)
+
+
+# ── 可编程 LLM 流式客户端桩 ──
+
+
+def _text_chunk(text: str):
+    return SimpleNamespace(
+        choices=[SimpleNamespace(delta=SimpleNamespace(content=text, tool_calls=None), finish_reason=None)]
+    )
+
+
+def _tool_call_chunk(call_id: str, name: str, arguments: str):
+    tc = SimpleNamespace(index=0, id=call_id, function=SimpleNamespace(name=name, arguments=arguments))
+    return SimpleNamespace(
+        choices=[SimpleNamespace(delta=SimpleNamespace(content=None, tool_calls=[tc]), finish_reason=None)]
+    )
+
+
+def _finish_chunk(reason: str = "stop"):
+    return SimpleNamespace(
+        choices=[SimpleNamespace(delta=SimpleNamespace(content=None, tool_calls=None), finish_reason=reason)]
+    )
+
+
+class FakeStreamClient:
+    """按轮次返回预编程 chunk 序列；超出编程轮次时重复最后一轮"""
+
+    def __init__(self, turns: list[list]):
+        self.turns = turns
+        self.requests: list[dict] = []
+
+    async def chat(self, stream: bool = True, **kwargs):
+        self.requests.append(kwargs)
+        idx = min(len(self.requests) - 1, len(self.turns) - 1)
+        chunks = self.turns[idx]
+
+        async def _gen():
+            for c in chunks:
+                yield c
+
+        return _gen()
+
+
+async def _collect(aiter):
+    return [evt async for evt in aiter]
+
+
+# ── D1: Agent max_turns 耗尽显式收尾 ──
+
+
+class TestAgentMaxTurns:
+    def _looping_tool(self, counter: dict) -> Tool:
+        def fn(context, inputs):
+            counter["n"] = counter.get("n", 0) + 1
+            return {"note": "need more tool calls"}
+
+        return Tool(name="looper", description="always asks for more", function=fn)
+
+    @patch("agstack.llm.flow.agent.get_llm_client")
+    def test_exhaustion_finalizes_explicitly(self, mock_get_client):
+        """打满场景：END 事件闭合、agent_max_turns CUSTOM 事件、输出含 truncated 标记"""
+        counter: dict = {}
+        turn = [
+            _text_chunk("thinking"),
+            _tool_call_chunk("tc1", "looper", "{}"),
+            _finish_chunk("tool_calls"),
+        ]
+        mock_get_client.return_value = FakeStreamClient([turn])
+
+        agent = Agent(name="worker", tools=[self._looping_tool(counter)], max_turns=2)
+        ctx = FlowContext(variables={"input": "go"})
+        events = _run(_collect(agent.stream(ctx)))
+
+        types = [e["type"] for e in events]
+        assert types.count(EventType.TEXT_MESSAGE_END) == 1
+        customs = [e for e in events if e["type"] == EventType.CUSTOM and e.get("name") == "agent_max_turns"]
+        assert len(customs) == 1
+        assert customs[0]["value"] == {"agentName": "worker", "maxTurns": 2}
+        assert ctx.outputs["worker"]["truncated"] is True
+        assert ctx.outputs["worker"]["result"] == "thinking"
+        assert ctx.get_variable("_agent_call_id") is None
+        assert counter["n"] == 2  # 两轮各执行一次工具
+
+    @patch("agstack.llm.flow.agent.get_llm_client")
+    def test_normal_exit_unchanged(self, mock_get_client):
+        """正常场景：无 truncated 键、无 agent_max_turns 事件"""
+        mock_get_client.return_value = FakeStreamClient([[_text_chunk("hello"), _finish_chunk()]])
+
+        agent = Agent(name="worker", max_turns=2)
+        ctx = FlowContext(variables={"input": "hi"})
+        events = _run(_collect(agent.stream(ctx)))
+
+        assert ctx.outputs["worker"] == {"result": "hello"}
+        assert "truncated" not in ctx.outputs["worker"]
+        assert [e["type"] for e in events].count(EventType.TEXT_MESSAGE_END) == 1
+        assert not any(e["type"] == EventType.CUSTOM and e.get("name") == "agent_max_turns" for e in events)
+
+    @patch("agstack.llm.flow.agent.get_llm_client")
+    def test_run_returns_partial_text_on_exhaustion(self, mock_get_client):
+        counter: dict = {}
+        turn = [
+            _text_chunk("partial"),
+            _tool_call_chunk("tc1", "looper", "{}"),
+            _finish_chunk("tool_calls"),
+        ]
+        mock_get_client.return_value = FakeStreamClient([turn])
+
+        agent = Agent(name="worker", tools=[self._looping_tool(counter)], max_turns=2)
+        result = _run(agent.run(FlowContext(variables={"input": "go"})))
+        assert "partial" in result["result"]
+
+    @patch("agstack.llm.flow.agent.get_llm_client")
+    def test_on_max_turns_error_mode(self, mock_get_client):
+        """严格模式：yield RUN_ERROR 后抛 AgentError"""
+        counter: dict = {}
+        turn = [_tool_call_chunk("tc1", "looper", "{}"), _finish_chunk("tool_calls")]
+        mock_get_client.return_value = FakeStreamClient([turn])
+
+        agent = Agent(name="worker", tools=[self._looping_tool(counter)], max_turns=1, on_max_turns="error")
+        ctx = FlowContext(variables={"input": "go"})
+
+        async def _consume():
+            events = []
+            with pytest.raises(AgentError):
+                async for evt in agent.stream(ctx):
+                    events.append(evt)
+            return events
+
+        events = _run(_consume())
+        assert any(e["type"] == EventType.RUN_ERROR and e.get("code") == "AGENT_MAX_TURNS_EXCEEDED" for e in events)
+
+
+# ── D2: 工具参数 JSON 解析失败反馈给模型 ──
+
+
+class TestToolArgsParseFailure:
+    @patch("agstack.llm.flow.agent.get_llm_client")
+    def test_invalid_json_feeds_error_back_to_model(self, mock_get_client):
+        """解析失败：工具不被调用，错误进 tool message 与 TOOL_CALL_RESULT，下一轮模型可见"""
+        counter: dict = {"n": 0}
+
+        def fn(context, inputs):
+            counter["n"] += 1
+            return {"docs": []}
+
+        tool = Tool(name="search", description="retrieval", function=fn)
+        bad_args = '{"query": "未闭合'
+        client = FakeStreamClient(
+            [
+                [_tool_call_chunk("tc1", "search", bad_args), _finish_chunk("tool_calls")],
+                [_text_chunk("done"), _finish_chunk()],
+            ]
+        )
+        mock_get_client.return_value = client
+
+        agent = Agent(name="worker", tools=[tool])
+        ctx = FlowContext(variables={"input": "find it"})
+        events = _run(_collect(agent.stream(ctx)))
+
+        # 工具函数不被调用
+        assert counter["n"] == 0
+
+        # 事件流出现含 parse failed 信息的 TOOL_CALL_RESULT
+        results = [e for e in events if e["type"] == EventType.TOOL_CALL_RESULT]
+        assert len(results) == 1
+        payload = json.loads(results[0]["content"])
+        assert "JSON parse failed" in payload["error"]
+        assert payload["raw_arguments"] == bad_args
+
+        # 下一轮模型请求的 messages 中含该 tool 角色错误消息
+        second_request_messages = client.requests[1]["messages"]
+        tool_msgs = [m for m in second_request_messages if m.get("role") == "tool"]
+        assert len(tool_msgs) == 1
+        assert "JSON parse failed" in tool_msgs[0]["content"]
+        assert tool_msgs[0]["tool_call_id"] == "tc1"
+
+        # 循环正常继续并结束
+        assert ctx.outputs["worker"] == {"result": "done"}
+
+    @patch("agstack.llm.flow.agent.get_llm_client")
+    def test_empty_arguments_still_calls_tool(self, mock_get_client):
+        """arguments 为空字符串维持现行为：无参工具正常调用"""
+        captured: dict = {"n": 0}
+
+        def fn(context, inputs):
+            captured["n"] += 1
+            captured["inputs"] = inputs
+            return {"ok": True}
+
+        tool = Tool(name="noargs", description="no-arg tool", function=fn)
+        client = FakeStreamClient(
+            [
+                [_tool_call_chunk("tc1", "noargs", ""), _finish_chunk("tool_calls")],
+                [_text_chunk("done"), _finish_chunk()],
+            ]
+        )
+        mock_get_client.return_value = client
+
+        agent = Agent(name="worker", tools=[tool])
+        _run(_collect(agent.stream(FlowContext(variables={"input": "go"}))))
+        assert captured["n"] == 1
+        assert captured["inputs"] == {}
+
+
+# ── D3: tool 节点 on_error 开关 ──
+
+
+def _fail_fn(context, inputs):
+    raise ValueError("boom")
+
+
+class TestToolNodeOnError:
+    def test_default_raise_preserved(self):
+        """不写 on_error：失败仍中断 flow（NodeExecutionError 包装）"""
+        registry.register_tool("d3_fail_raise", Tool(name="d3_fail_raise", description="", function=_fail_fn))
+        flow = Flow(
+            flow_id="t",
+            name="t",
+            nodes=[{"id": "search", "type": "tool", "config": {"tool_name": "d3_fail_raise"}}],
+        )
+        with pytest.raises(NodeExecutionError):
+            _run(flow.run(FlowContext()))
+
+    def test_on_error_continue_routes_condition_edge(self):
+        """on_error: continue：flow 不中断，条件边按 success == false 分流，trace 记录 error"""
+        registry.register_tool("d3_fail_cont", Tool(name="d3_fail_cont", description="", function=_fail_fn))
+        flow = Flow(
+            flow_id="t",
+            name="t",
+            nodes=[
+                {
+                    "id": "search",
+                    "type": "tool",
+                    "config": {"tool_name": "d3_fail_cont", "on_error": "continue"},
+                },
+                {
+                    "id": "fallback",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'handled': True}"},
+                },
+                {
+                    "id": "happy",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'happy': True}"},
+                },
+            ],
+            edges=[
+                {"source": "search", "condition": "$o.search.success == false", "target": "fallback"},
+                {"source": "search", "target": "happy"},
+            ],
+        )
+        ctx = FlowContext()
+        _run(flow.run(ctx))
+
+        assert ctx.outputs["search"]["success"] is False
+        assert "boom" in ctx.outputs["search"]["error"]
+        assert ctx.outputs["fallback"] == {"handled": True}
+        assert "happy" not in ctx.outputs
+
+        search_trace = next(n for n in ctx.trace.nodes if n.node_id == "search")
+        assert search_trace.error is not None and "boom" in search_trace.error
+
+
+# ── D4: NodeTrace.usage 按节点归因 ──
+
+
+def _chat_response(text: str, prompt: int, completion: int):
+    resp = MagicMock()
+    choice = MagicMock()
+    choice.message.content = text
+    resp.choices = [choice]
+    resp.usage = MagicMock(prompt_tokens=prompt, completion_tokens=completion, total_tokens=prompt + completion)
+    return resp
+
+
+_NEVER_EDGE = {"condition": "$v._never == yes"}  # 恒不满足且无 fallback：驱动 edge-driven 路径后自然结束
+
+
+class TestNodeUsageAttribution:
+    @patch("agstack.llm.flow.nodes.llm_chat_node.get_llm_client")
+    def test_single_llm_node(self, mock_get_client):
+        mock_client = AsyncMock()
+        mock_client.chat = AsyncMock(return_value=_chat_response("hi", 10, 5))
+        mock_get_client.return_value = mock_client
+
+        flow = Flow(
+            flow_id="t",
+            name="t",
+            nodes=[{"id": "chat1", "type": "llm_chat", "config": {"prompt": "hello"}}],
+            edges=[{"source": "chat1", "target": "chat1", **_NEVER_EDGE}],
+        )
+        ctx = FlowContext()
+        _run(flow.run(ctx))
+
+        node = next(n for n in ctx.trace.nodes if n.node_id == "chat1")
+        assert node.usage is not None
+        assert node.usage.total_tokens == 15
+        assert node.usage.total_tokens == ctx.trace.total_usage.total_tokens
+
+    @patch("agstack.llm.flow.nodes.llm_chat_node.get_llm_client")
+    def test_two_serial_llm_nodes_sum_to_total(self, mock_get_client):
+        mock_client = AsyncMock()
+        mock_client.chat = AsyncMock(side_effect=[_chat_response("a", 10, 5), _chat_response("b", 6, 2)])
+        mock_get_client.return_value = mock_client
+
+        flow = Flow(
+            flow_id="t",
+            name="t",
+            nodes=[
+                {"id": "chat1", "type": "llm_chat", "config": {"prompt": "one"}},
+                {"id": "chat2", "type": "llm_chat", "config": {"prompt": "two"}},
+            ],
+            edges=[{"source": "chat1", "target": "chat2"}],
+        )
+        ctx = FlowContext()
+        _run(flow.run(ctx))
+
+        n1 = next(n for n in ctx.trace.nodes if n.node_id == "chat1")
+        n2 = next(n for n in ctx.trace.nodes if n.node_id == "chat2")
+        assert n1.usage is not None and n2.usage is not None
+        assert n1.usage.total_tokens == 15
+        assert n2.usage.total_tokens == 8
+        assert n1.usage.total_tokens + n2.usage.total_tokens == ctx.trace.total_usage.total_tokens
+
+    def test_non_llm_node_usage_is_none(self):
+        """无 LLM 调用的节点：usage 为 None 而非零值 Usage"""
+        flow = Flow(
+            flow_id="t",
+            name="t",
+            nodes=[
+                {
+                    "id": "py1",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'ok': True}"},
+                }
+            ],
+            edges=[{"source": "py1", "target": "py1", **_NEVER_EDGE}],
+        )
+        ctx = FlowContext()
+        _run(flow.run(ctx))
+        node = next(n for n in ctx.trace.nodes if n.node_id == "py1")
+        assert node.usage is None
+
+    @patch("agstack.llm.flow.nodes.llm_chat_node.get_llm_client")
+    def test_parallel_container_owns_branch_usage(self, mock_get_client):
+        """parallel 容器 usage = 分支用量总和，分支节点 usage 为 None"""
+        mock_client = AsyncMock()
+        mock_client.chat = AsyncMock(side_effect=[_chat_response("a", 10, 5), _chat_response("b", 6, 2)])
+        mock_get_client.return_value = mock_client
+
+        flow = Flow(
+            flow_id="t",
+            name="t",
+            nodes=[
+                {"id": "par", "type": "parallel", "config": {"branches": ["b1", "b2"]}},
+                {"id": "b1", "type": "llm_chat", "config": {"prompt": "one"}},
+                {"id": "b2", "type": "llm_chat", "config": {"prompt": "two"}},
+            ],
+            edges=[{"source": "par", "target": "par", **_NEVER_EDGE}],
+        )
+        ctx = FlowContext()
+        _run(flow.run(ctx))
+
+        par = next(n for n in ctx.trace.nodes if n.node_id == "par")
+        assert par.usage is not None
+        assert par.usage.total_tokens == 23
+        for branch_id in ("b1", "b2"):
+            branch = next(n for n in ctx.trace.nodes if n.node_id == branch_id)
+            assert branch.usage is None
+
+
+# ── D5: run() 收敛为 stream() 消费者 ──
+
+
+class TestRunStreamConvergence:
+    def test_run_applies_retry_policy(self):
+        """首次必失败、二次成功 + retry 配置：run() 成功返回"""
+        calls = {"n": 0}
+
+        def flaky(context, inputs):
+            calls["n"] += 1
+            if calls["n"] == 1:
+                raise ValueError("first attempt fails")
+            return {"ok": True}
+
+        registry.register_tool("d5_flaky", Tool(name="d5_flaky", description="", function=flaky))
+        flow = Flow(
+            flow_id="t",
+            name="t",
+            nodes=[
+                {
+                    "id": "job",
+                    "type": "tool",
+                    "config": {
+                        "tool_name": "d5_flaky",
+                        "retry": {"max_retries": 2, "delay": 0.001, "backoff": 1.0},
+                    },
+                }
+            ],
+        )
+        ctx = FlowContext()
+        outputs = _run(flow.run(ctx))
+        assert calls["n"] == 2
+        assert outputs["job"] == {"ok": True}
+
+    def test_run_populates_trace(self):
+        flow = Flow(
+            flow_id="t",
+            name="t",
+            nodes=[
+                {
+                    "id": "py1",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'ok': True}"},
+                }
+            ],
+            edges=[{"source": "py1", "target": "py1", **_NEVER_EDGE}],
+        )
+        ctx = FlowContext()
+        _run(flow.run(ctx))
+        assert len(ctx.trace.nodes) == 1
+        assert ctx.trace.started_at is not None
+        assert ctx.trace.finished_at is not None
+        assert ctx.trace.total_usage is ctx.usage
+
+    def test_run_output_mode_append(self):
+        """output_mode: append 的节点被访问两次后输出是长度 2 的 list"""
+        flow = Flow(
+            flow_id="t",
+            name="t",
+            nodes=[
+                {
+                    "id": "gen",
+                    "type": "python",
+                    "config": {
+                        "code": "def main(**kwargs):\n    return {'tick': 1}",
+                        "output_mode": "append",
+                    },
+                },
+                {
+                    "id": "end",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'end': True}"},
+                },
+            ],
+            edges=[
+                {"source": "gen", "condition": "$v.always == yes", "target": "gen"},
+                {"source": "gen", "target": "end"},
+            ],
+            cycle_limits={"gen": 2},
+        )
+        ctx = FlowContext(variables={"always": "yes"})
+        _run(flow.run(ctx))
+        assert isinstance(ctx.outputs["gen"], list)
+        assert len(ctx.outputs["gen"]) == 2
+        assert ctx.outputs["end"] == {"end": True}
+
+    def test_run_wraps_errors_as_node_execution_error(self):
+        """异常类型收窄：run() 节点失败抛 NodeExecutionError（1.25.1 抛原始异常）"""
+        flow = Flow(
+            flow_id="t",
+            name="t",
+            nodes=[
+                {
+                    "id": "bad",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    raise RuntimeError('inner')"},
+                }
+            ],
+        )
+        with pytest.raises(NodeExecutionError):
+            _run(flow.run(FlowContext()))