agstack 2.3.0__tar.gz → 3.0.0__tar.gz

{agstack-2.3.0 → agstack-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 2.3.0
+Version: 3.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>
@@ -86,7 +86,7 @@ pip install agstack
 ### Basic Usage
 
 ```python
-from agstack.llm.flow import (
+from agstack.genai.flow import (
     Tool,
     FlowContext,
     registry,
@@ -130,13 +130,10 @@ agstack/
 ├── schema.py          # Base Pydantic models
 ├── registry.py        # Global component registry
 ├── exceptions.py      # Exception hierarchy
-├── llm/              # LLM and AI features
-│   ├── client.py     # LLM client
-│   └── flow/         # Flow execution framework
-│       ├── agent.py  # Agent definition
-│       ├── tool.py   # Tool definition
-│       ├── flow.py   # Flow orchestration
-│       └── ...
+├── genai/            # Generative AI, three one-way layers
+│   ├── llm/          # Model access: client, call hooks, prompts, token counting
+│   ├── flow/         # Flow execution framework (agent / tool / flow / nodes / guards)
+│   └── harness/      # Runtime: ports, events, projection, metering, overflow, context, spill
 ├── fastapi/          # FastAPI integration
 ├── infra/            # Infrastructure components
 │   ├── db/           # Database

{agstack-2.3.0 → agstack-3.0.0}/README.md

@@ -28,7 +28,7 @@ pip install agstack
 ### Basic Usage
 
 ```python
-from agstack.llm.flow import (
+from agstack.genai.flow import (
     Tool,
     FlowContext,
     registry,
@@ -72,13 +72,10 @@ agstack/
 ├── schema.py          # Base Pydantic models
 ├── registry.py        # Global component registry
 ├── exceptions.py      # Exception hierarchy
-├── llm/              # LLM and AI features
-│   ├── client.py     # LLM client
-│   └── flow/         # Flow execution framework
-│       ├── agent.py  # Agent definition
-│       ├── tool.py   # Tool definition
-│       ├── flow.py   # Flow orchestration
-│       └── ...
+├── genai/            # Generative AI, three one-way layers
+│   ├── llm/          # Model access: client, call hooks, prompts, token counting
+│   ├── flow/         # Flow execution framework (agent / tool / flow / nodes / guards)
+│   └── harness/      # Runtime: ports, events, projection, metering, overflow, context, spill
 ├── fastapi/          # FastAPI integration
 ├── infra/            # Infrastructure components
 │   ├── db/           # Database

agstack-3.0.0/agstack/genai/__init__.py

@@ -0,0 +1,10 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""agstack.genai——生成式 AI 三层（3.0）
+
+- :mod:`.llm`：模型接入（client / hooks / prompts / token），不依赖另外两层；
+- :mod:`.flow`：编排（Agent / Tool / Flow / nodes / guards），依赖 llm；
+- :mod:`.harness`：运行时纪律（ports / events / projection / metering / context / overflow / spill），依赖 llm 与 flow。
+
+依赖单向、不成环；应用对本包的依赖应集中在一处适配层。
+"""

{agstack-2.3.0/agstack/llm → agstack-3.0.0/agstack/genai}/flow/__init__.py

@@ -17,6 +17,7 @@ from .exceptions import (
 )
 from .factory import create_agent, create_tool
 from .flow import Flow
+from .guards import AgentGuards, GuardedToolCalls, GuardState, buffer_plan_text
 from .loader import FlowLoader
 from .nodes import NodeHandler
 from .records import Record, Status
@@ -35,6 +36,10 @@ __all__ = [
     "ToolHook",
     "Deny",
     "Agent",
+    "AgentGuards",
+    "GuardState",
+    "GuardedToolCalls",
+    "buffer_plan_text",
     "Flow",
     "FlowContext",
     "Usage",

{agstack-2.3.0/agstack/llm → agstack-3.0.0/agstack/genai}/flow/agent.py

@@ -7,7 +7,8 @@ import json
 from typing import TYPE_CHECKING, Any, AsyncIterator
 from uuid import uuid4
 
-from ..client import get_llm_client
+from ..harness.overflow import OverflowPolicy, classify_overflow, usage_tokens
+from ..llm.client import get_llm_client
 from . import event
 from .context import Usage
 from .event import EventType
@@ -22,6 +23,9 @@ if TYPE_CHECKING:
 class Agent:
     """Agent 定义"""
 
+    #: 上下文溢出恢复策略（harness.overflow；None 不恢复）。子类可按类属性给缺省，构造参数 ``overflow`` 覆盖
+    overflow: OverflowPolicy | None = None
+
     def __init__(
         self,
         name: str,
@@ -37,6 +41,7 @@ class Agent:
         retry_empty_response: bool = False,
         label: str | None = None,
         echo: bool = False,
+        overflow: OverflowPolicy | None = None,
     ):
         """初始化 Agent
 
@@ -52,6 +57,7 @@ class Agent:
             以 ``request_overrides(..., retry=True)`` 的覆盖参数重试一次
         :param label: 面向用户的展示名称（控制 STEP 进度事件可见性）
         :param echo: 是否转发 TEXT_MESSAGE 给用户
+        :param overflow: 上下文溢出恢复策略（三态判定命中后调 ``compact`` 压缩并同轮重发一次，见 harness.overflow）
         """
         self.name = name
         self.instructions = instructions or f"You are {name}, a helpful AI assistant."
@@ -65,6 +71,8 @@ class Agent:
         self.retry_empty_response = retry_empty_response
         self.label = label
         self.echo = echo
+        if overflow is not None:
+            self.overflow = overflow
 
     def get_system_message(self) -> dict[str, Any]:
         """获取系统消息"""
@@ -102,6 +110,25 @@ class Agent:
                 return tool
         return None
 
+    # ── 溢出恢复（机制；策略在 self.overflow） ──
+
+    def _max_recoveries(self) -> int:
+        return self.overflow.max_recoveries if self.overflow is not None else 0
+
+    def _overflow_kind(self, context: "FlowContext", *, error: BaseException | None = None, **usage: Any) -> str | None:
+        if self.overflow is None:
+            return None
+        if error is not None:
+            return classify_overflow(error=error)
+        return classify_overflow(context_length=self.overflow.window(context), **usage)
+
+    async def _compact_overflow(self, context: "FlowContext", kind: str) -> bool:
+        assert self.overflow is not None
+        try:
+            return bool(await self.overflow.compact(context, kind))
+        except Exception:  # noqa: BLE001 — 压缩失败不替代原错误，按原路报错
+            return False
+
     def _group_tool_calls(self, tool_calls: list[dict[str, Any]]) -> list[list[dict[str, Any]]]:
         """按声明分组：连续的 concurrency_safe 调用聚为一组并发执行，其余单独成组串行
 
@@ -290,6 +317,7 @@ class Agent:
 
         # Agent 循环
         assistant_content = ""
+        recoveries = 0  # 溢出恢复次数（每次运行上限 overflow.max_recoveries）
         for turn in range(1, self.max_turns + 1):
             # 协作式取消检查点：不再开始新的 LLM 轮次
             if context.is_cancelled:
@@ -306,6 +334,8 @@ class Agent:
                 assistant_content = ""
                 tool_calls: list[dict[str, Any]] = []
                 tool_calls_buffer: dict[int, dict[str, Any]] = {}
+                finish_reason: str | None = None
+                turn_usage: Any = None
 
                 try:
                     kwargs: dict[str, Any] = {
@@ -362,6 +392,7 @@ class Agent:
 
                         # 完成
                         if choice.finish_reason:
+                            finish_reason = choice.finish_reason
                             # AG-UI: 工具调用事件
                             for tool_call_data in tool_calls_buffer.values():
                                 tool_calls.append(tool_call_data)
@@ -383,6 +414,7 @@ class Agent:
 
                             # 更新 usage
                             if hasattr(chunk, "usage") and chunk.usage:
+                                turn_usage = chunk.usage
                                 context.add_usage(
                                     Usage(
                                         prompt_tokens=chunk.usage.prompt_tokens or 0,
@@ -392,11 +424,39 @@ class Agent:
                                 )
 
                 except Exception as e:
+                    # 上下文溢出（后端报错态）：尚未放出任何内容时压缩并同轮重发一次（harness.overflow）
+                    kind = self._overflow_kind(context, error=e) if not assistant_content and not tool_calls else None
+                    if kind and recoveries < self._max_recoveries():
+                        recoveries += 1
+                        yield event.custom(
+                            name="agent_overflow", value={"agentName": self.name, "kind": kind, "turn": turn}
+                        )
+                        if await self._compact_overflow(context, kind):
+                            messages = [self.get_system_message()] + context.history + context.get_messages(self.name)
+                            continue
                     error_msg = str(e)
                     # AG-UI: RUN_ERROR
                     yield event.run_error(message=error_msg)
                     raise FlowError("AGENT_EXECUTION_FAILED", 500, {"error": error_msg}) from e
 
+                # 上下文溢出（静默 / length 态）：请求成功但输入已撑爆窗口且本次没有产出，同样压缩重发一次
+                if not tool_calls and not assistant_content.strip():
+                    prompt_tokens, completion_tokens = usage_tokens(turn_usage)
+                    kind = self._overflow_kind(
+                        context,
+                        finish_reason=finish_reason,
+                        prompt_tokens=prompt_tokens,
+                        completion_tokens=completion_tokens,
+                    )
+                    if kind and recoveries < self._max_recoveries():
+                        recoveries += 1
+                        yield event.custom(
+                            name="agent_overflow", value={"agentName": self.name, "kind": kind, "turn": turn}
+                        )
+                        if await self._compact_overflow(context, kind):
+                            messages = [self.get_system_message()] + context.history + context.get_messages(self.name)
+                            continue
+
                 if self.retry_empty_response and attempt == 0 and not tool_calls and not assistant_content.strip():
                     attempt = 1
                     continue

agstack-3.0.0/agstack/genai/flow/guards.py

@@ -0,0 +1,421 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""Agent 工具调用守卫（AgentGuards）
+
+「红线在代码」的一层：模型在给到的工具里自由决策，但以下几条**不靠提示词**，由本模块在
+``Agent._stream_tool_call`` 前后执行：
+
+- 同名同参重复调用直接退回上次结果（:attr:`AgentGuards.duplicate_kind`）；
+- 受上限工具族累计调用达上限后返回「预算用尽」不再执行（:attr:`AgentGuards.cap_kind`）；
+- 应用自定义的执行前守卫（:attr:`AgentGuards.checks`，如「先库后网」）；
+- 工具结果累计 token 超预算时把最早的结果折叠为摘要（:attr:`AgentGuards.fold_kind`；最新一条永不折叠）；
+- 工具结果末尾附应用给的提示（:attr:`AgentGuards.hint`，如「够了就停」的取材提示）。
+
+每个守卫动作写一条与 Tool 管线同形的执行记录进 ``context.execution_records``（随节点 trace 持久化，审计按
+``tool_name`` 呈现）。本模块只有机制；受上限的工具族、上限值、折叠渲染、提示文案、自定义规则全由应用在
+:class:`AgentGuards` 里给。
+
+另附 :func:`buffer_plan_text`：按轮缓冲助手文字——轮以工具调用结束时文字只进 trace（「这次为什么调它」），轮以
+文字结束时放流；轮次耗尽且无可展示文字时按应用给的 closing_line 收尾，不把空串或已记为计划的文字当回答交出去。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import AsyncIterator, Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from . import event
+from .context import FlowContext
+from .event import EventType
+
+
+logger = logging.getLogger(__name__)
+
+#: 守卫动作的缺省 ``tool_name``（审计呈现用；应用可在 :class:`AgentGuards` 覆盖）
+GUARD_DUPLICATE = "guard_duplicate_call"
+GUARD_CAP = "guard_call_cap"
+GUARD_FOLD = "guard_fold_results"
+#: 计划记录的缺省 ``tool_name``
+PLAN_RECORD = "agent_plan"
+
+#: 执行前守卫：``(state, tool_name, raw_arguments) -> (守卫种类, 退给模型的结果) | None``；None 放行
+type GuardCheck = Callable[["GuardState", str, str], tuple[str, dict[str, Any]] | None]
+#: 折叠渲染：``(context, 原工具结果文本) -> 折叠后文本``
+type FoldRenderer = Callable[[FlowContext, str], str]
+#: 结果提示：``(state, tool_name, 结果文本) -> 追加到末尾的提示 | None``
+type HintBuilder = Callable[["GuardState", str, str], str | None]
+#: token 计数：``(text, model) -> tokens``
+type TokenCounter = Callable[[str, str], int]
+
+
+@dataclass
+class GuardState:
+    """一次 Agent 运行的守卫计数（每次 ``stream`` 开始时 :meth:`reset`）
+
+    :param cap: 本次运行的工具族上限；None 取 :attr:`AgentGuards.cap`
+    :param seen_calls: 调用签名 → tool_call_id（重复调用判定）
+    :param calls: 工具名 → 累计放行次数
+    :param family_calls: 受上限工具族累计放行次数
+    """
+
+    cap: int | None = None
+    seen_calls: dict[str, str] = field(default_factory=dict)
+    calls: dict[str, int] = field(default_factory=dict)
+    family_calls: int = 0
+
+    def reset(self) -> None:
+        self.seen_calls = {}
+        self.calls = {}
+        self.family_calls = 0
+
+    def calls_of(self, *names: str) -> int:
+        """给定工具名的累计放行次数之和"""
+        return sum(self.calls.get(n, 0) for n in names)
+
+
+def _default_duplicate_payload(previous_call_id: str) -> dict[str, Any]:
+    return {
+        "note": "与此前一次调用的工具与参数完全相同，结果未变（见前一次结果）；请换查询或直接作答",
+        "previous_tool_call_id": previous_call_id,
+    }
+
+
+def _default_cap_payload(cap: int) -> dict[str, Any]:
+    return {
+        "error": "CALL_BUDGET_EXHAUSTED",
+        "hint": f"本轮该类工具调用次数已达上限（{cap} 次），请基于已取得的结果作答并说明未覆盖之处",
+    }
+
+
+@dataclass
+class AgentGuards:
+    """守卫策略（应用给值）
+
+    :param capped_family: 累计调用受上限的工具族（空＝不限）
+    :param cap: 工具族累计调用上限缺省值（:attr:`GuardState.cap` 可按次运行覆盖）
+    :param checks: 应用自定义执行前守卫，在重复调用与上限之后按序执行
+    :param hint: 工具结果末尾附加的提示构造器（None＝不附）
+    :param fold_budget_ratio: 工具结果累计 token 预算 = ``context_length // ratio``（0＝不折叠）
+    :param fold_renderer: 折叠后文本的渲染（None＝固定一句通知）
+    :param count_tokens: 折叠判定用的 token 计数（None＝不折叠）
+    :param context_length_var / model_var: 从 ``context.variables`` 取上下文窗口与模型名的键
+    :param duplicate_kind / cap_kind / fold_kind: 三类守卫动作写执行记录时的 ``tool_name``
+    :param duplicate_payload / cap_payload: 退给模型的结果构造
+    """
+
+    capped_family: tuple[str, ...] = ()
+    cap: int = 5
+    checks: tuple[GuardCheck, ...] = ()
+    hint: HintBuilder | None = None
+    fold_budget_ratio: int = 3
+    fold_renderer: FoldRenderer | None = None
+    count_tokens: TokenCounter | None = None
+    context_length_var: str = "context_length"
+    context_length_default: int = 32768
+    model_var: str = "llm_model"
+    duplicate_kind: str = GUARD_DUPLICATE
+    cap_kind: str = GUARD_CAP
+    fold_kind: str = GUARD_FOLD
+    duplicate_payload: Callable[[str], dict[str, Any]] = _default_duplicate_payload
+    cap_payload: Callable[[int], dict[str, Any]] = _default_cap_payload
+
+
+# ── 纯函数 ──
+
+
+def call_signature(name: str, arguments: str) -> str:
+    """同名同参重复调用的判定键：参数 JSON 规范化（键排序）后与工具名拼接"""
+    try:
+        parsed = json.loads(arguments) if arguments else {}
+    except ValueError:
+        parsed = arguments
+    return f"{name}:{json.dumps(parsed, ensure_ascii=False, sort_keys=True)}"
+
+
+def check_tool_call(
+    guards: AgentGuards, state: GuardState, name: str, arguments: str
+) -> tuple[str, dict[str, Any]] | None:
+    """执行前守卫：返回 ``(守卫种类, 退给模型的结果)``；None 表示放行
+
+    判定顺序：重复调用 → 工具族上限 → 应用自定义 checks。只读 ``state``，放行后由 :func:`note_tool_call` 记账。
+    """
+    previous = state.seen_calls.get(call_signature(name, arguments))
+    if previous is not None:
+        return guards.duplicate_kind, guards.duplicate_payload(previous)
+    cap = state.cap if state.cap is not None else guards.cap
+    if name in guards.capped_family and state.family_calls >= cap:
+        return guards.cap_kind, guards.cap_payload(cap)
+    for check in guards.checks:
+        hit = check(state, name, arguments)
+        if hit is not None:
+            return hit
+    return None
+
+
+def note_tool_call(guards: AgentGuards, state: GuardState, name: str, arguments: str, call_id: str) -> None:
+    """放行后记账：登记签名、累计工具与工具族次数"""
+    state.seen_calls[call_signature(name, arguments)] = call_id
+    state.calls[name] = state.calls.get(name, 0) + 1
+    if name in guards.capped_family:
+        state.family_calls += 1
+
+
+_FOLDED_NOTE = "（该工具结果已折叠以节省上下文）"
+
+
+def fold_tool_messages(
+    context: FlowContext,
+    agent_name: str,
+    *,
+    budget_tokens: int,
+    model: str,
+    count_tokens: TokenCounter,
+    render: FoldRenderer | None = None,
+) -> int:
+    """工具结果累计超预算时，从最早的工具消息起折叠，返回折叠条数
+
+    最新一条工具消息永不折叠（模型正要读它）；已折叠的消息（``_folded``）不重复处理。
+    """
+    messages = context.messages.get(agent_name) or []
+    tool_idx = [i for i, m in enumerate(messages) if m.get("role") == "tool"]
+    if len(tool_idx) < 2:
+        return 0
+    sizes = {i: count_tokens(str(messages[i].get("content") or ""), model) for i in tool_idx}
+    total = sum(sizes.values())
+    if total <= budget_tokens:
+        return 0
+    folded = 0
+    for i in tool_idx[:-1]:
+        if total <= budget_tokens:
+            break
+        msg = messages[i]
+        if msg.get("_folded"):
+            continue
+        content = str(msg.get("content") or "")
+        replacement = render(context, content) if render else _FOLDED_NOTE
+        messages[i] = {**msg, "content": replacement, "_folded": True}
+        total -= sizes[i] - count_tokens(replacement, model)
+        folded += 1
+    if folded:
+        logger.info("[%s] folded %d tool results (total=%d budget=%d)", agent_name, folded, total, budget_tokens)
+    return folded
+
+
+def add_trace_record(
+    context: FlowContext,
+    tool_name: str,
+    *,
+    args: dict[str, Any] | None = None,
+    result: str = "",
+    summary: str | None = None,
+) -> None:
+    """守卫动作 / 调用计划写一条执行记录（与 Tool 管线写的记录同形，随节点 trace 的 ``tool_calls`` 持久化）"""
+    context.execution_records.append(
+        {
+            "agent_call_id": context.get_variable("_agent_call_id"),
+            "tool_name": tool_name,
+            "tool_args": args or {},
+            "success": True,
+            "result": result,
+            "error": None,
+            "duration_ms": 0,
+            "summary": summary,
+        }
+    )
+
+
+# ── Agent mixin ──
+
+
+class GuardedToolCalls:
+    """给 ``Agent`` 子类接守卫的 mixin：宿主须有 ``guards: AgentGuards``、``guard: GuardState``、``name``、``model``，
+    并在 MRO 上先于 ``Agent``
+
+    ``_stream_tool_call`` 执行前跑 :func:`check_tool_call`，放行后记账并交给基类执行；执行后给结果附提示，
+    再按上下文窗口预算折叠最早的工具结果。
+    """
+
+    guards: AgentGuards
+    guard: GuardState
+    name: str
+    model: str
+
+    async def _stream_tool_call(
+        self,
+        context: FlowContext,
+        tool_call: dict[str, Any],
+        message_sink: list[dict[str, Any]] | None = None,
+    ) -> AsyncIterator[dict[str, Any]]:
+        name = tool_call["name"]
+        arguments = tool_call.get("arguments") or ""
+        hit = check_tool_call(self.guards, self.guard, name, arguments)
+        if hit is not None:
+            kind, payload = hit
+            content = json.dumps(payload, ensure_ascii=False)
+            if message_sink is None:
+                context.add_message(self.name, "tool", content=content, tool_call_id=tool_call["id"])
+            else:
+                message_sink.append({"content": content, "tool_call_id": tool_call["id"]})
+            add_trace_record(
+                context, kind, args={"tool": name, "arguments": arguments}, result=content, summary=f"守卫拦截：{name}"
+            )
+            yield event.tool_call_result(tool_call_id=tool_call["id"], content=content)
+            return
+        note_tool_call(self.guards, self.guard, name, arguments, tool_call["id"])
+        async for evt in super()._stream_tool_call(context, tool_call, message_sink):  # type: ignore[misc]
+            yield evt
+        self._append_hint(context, name, tool_call["id"], message_sink)
+        self._fold(context)
+
+    def _fold(self, context: FlowContext) -> None:
+        guards = self.guards
+        if guards.count_tokens is None or guards.fold_budget_ratio <= 0:
+            return
+        context_length = int(
+            context.get_variable(guards.context_length_var, guards.context_length_default)
+            or guards.context_length_default
+        )
+        budget = context_length // guards.fold_budget_ratio
+        folded = fold_tool_messages(
+            context,
+            self.name,
+            budget_tokens=budget,
+            model=str(context.get_variable(guards.model_var) or self.model),
+            count_tokens=guards.count_tokens,
+            render=guards.fold_renderer,
+        )
+        if folded:
+            add_trace_record(
+                context,
+                guards.fold_kind,
+                args={"folded": folded, "budget_tokens": budget},
+                summary=f"守卫折叠：最早 {folded} 条工具结果折叠为摘要",
+            )
+
+    def _append_hint(
+        self, context: FlowContext, name: str, call_id: str, message_sink: list[dict[str, Any]] | None
+    ) -> None:
+        """把提示追加到刚写回的 tool 消息末尾（消息在 sink 或 context 里，按 tool_call_id 定位）"""
+        if self.guards.hint is None:
+            return
+        target: dict[str, Any] | None = None
+        if message_sink is not None:
+            target = next((m for m in reversed(message_sink) if m.get("tool_call_id") == call_id), None)
+        else:
+            messages = context.messages.get(self.name) or []
+            target = next(
+                (m for m in reversed(messages) if m.get("role") == "tool" and m.get("tool_call_id") == call_id), None
+            )
+        if target is None:
+            return
+        content = str(target.get("content") or "")
+        hint = self.guards.hint(self.guard, name, content)
+        if hint:
+            target["content"] = content + "\n" + hint
+
+
+# ── 过程话语缓冲 ──
+
+
+async def buffer_plan_text(
+    events: AsyncIterator[dict[str, Any]],
+    context: FlowContext,
+    *,
+    agent_name: str,
+    buffer_chars: int = 200,
+    plan_kind: str = PLAN_RECORD,
+    closing_line: Callable[[Sequence[dict[str, Any]]], str | None] | None = None,
+    truncated_line: str = "本轮未能在规定步骤内整理出回答，请换种说法再试一次。",
+    empty_line: str = "本轮没有生成出回答（模型输出为空），请重试或换种说法。",
+) -> AsyncIterator[dict[str, Any]]:
+    """包装 ``Agent.stream`` 的事件流：按轮缓冲助手文字，把「调工具前的过程话语」记为计划而不放流
+
+    - 轮以工具调用结束：缓冲内的文字写一条 ``plan_kind`` 执行记录（``args.next_tool`` 为随后调用的工具、
+      ``args.streamed`` 标记文字是否已有部分放流），不交给用户；
+    - 轮以文字结束：缓冲整体放流；单轮文字超过 ``buffer_chars`` 时从该点起实时放流（长答不等整段）；
+    - 轮次耗尽（输出带 ``truncated``）或末轮无文字：按 ``closing_line(messages)`` 收尾，其返回 None 时用
+      ``truncated_line`` / ``empty_line``，并把输出 ``result`` 改写为该句。
+    """
+    buffer: list[str] = []
+    streamed = ""  # 本轮已放流的文字（超过缓冲阈值后开始放流）
+    plan_done = False  # 本轮文字已记为计划（该轮有工具调用）
+    results_seen = False  # 本轮已出现工具结果：下一个 TEXT / TOOL_CALL_START 属于新一轮
+    async for evt in events:
+        etype = evt.get("type")
+        if etype == EventType.TEXT_MESSAGE_CONTENT:
+            if results_seen:
+                buffer, streamed, plan_done, results_seen = [], "", False, False
+            delta = str(evt.get("delta") or "")
+            if streamed:
+                streamed += delta
+                yield evt
+                continue
+            buffer.append(delta)
+            if sum(len(piece) for piece in buffer) >= buffer_chars:
+                streamed = "".join(buffer)
+                buffer = []
+                yield event.text_message_content(message_id=str(evt.get("messageId") or ""), delta=streamed)
+            continue
+        if etype == EventType.TOOL_CALL_START:
+            if results_seen:
+                buffer, streamed, plan_done, results_seen = [], "", False, False
+            if not plan_done:
+                plan_done = True
+                text = (streamed + "".join(buffer)).strip()
+                buffer = []
+                if text:
+                    add_trace_record(
+                        context,
+                        plan_kind,
+                        args={"next_tool": str(evt.get("toolCallName") or ""), "streamed": bool(streamed)},
+                        result=text,
+                        summary=("（已展示给用户）" if streamed else "") + text[:80],
+                    )
+            yield evt
+            continue
+        if etype == EventType.TOOL_CALL_RESULT:
+            results_seen = True
+            yield evt
+            continue
+        if etype == EventType.TEXT_MESSAGE_END:
+            msg_id = str(evt.get("messageId") or "")
+            if buffer:
+                streamed += "".join(buffer)
+                yield event.text_message_content(message_id=msg_id, delta="".join(buffer))
+                buffer = []
+            out = context.outputs.get(agent_name)
+            if isinstance(out, dict) and not streamed.strip():
+                # 轮次耗尽：最后一轮文字若已被记为计划（未展示），不能当回答交出去；末轮 content 为空同样不能交出空串
+                line = closing_line(context.get_messages(agent_name)) if closing_line else None
+                if out.get("truncated"):
+                    line = line or truncated_line
+                else:
+                    line = line or empty_line
+                    logger.warning("[%s] empty final content, fallback line emitted", agent_name)
+                yield event.text_message_content(message_id=msg_id, delta=line)
+                context.set_output(agent_name, {**out, "result": line})
+        yield evt
+
+
+__all__ = [
+    "GUARD_CAP",
+    "GUARD_DUPLICATE",
+    "GUARD_FOLD",
+    "PLAN_RECORD",
+    "AgentGuards",
+    "FoldRenderer",
+    "GuardCheck",
+    "GuardState",
+    "GuardedToolCalls",
+    "HintBuilder",
+    "TokenCounter",
+    "add_trace_record",
+    "buffer_plan_text",
+    "call_signature",
+    "check_tool_call",
+    "fold_tool_messages",
+    "note_tool_call",
+]

{agstack-2.3.0/agstack/llm → agstack-3.0.0/agstack/genai}/flow/nodes/detect_node.py

@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, Any
 
 from openai.types.chat import ChatCompletionMessageParam
 
-from ...client import get_llm_client
+from ...llm.client import get_llm_client
 from ..context import Usage
 from .base import NodeHandler
 

{agstack-2.3.0/agstack/llm → agstack-3.0.0/agstack/genai}/flow/nodes/echo_node.py

@@ -5,12 +5,12 @@
 from typing import TYPE_CHECKING, Any, AsyncIterator
 from uuid import uuid4
 
-from agstack.llm.flow import event
-from agstack.llm.flow.nodes.base import NodeHandler
+from agstack.genai.flow import event
+from agstack.genai.flow.nodes.base import NodeHandler
 
 
 if TYPE_CHECKING:
-    from agstack.llm.flow.context import FlowContext
+    from agstack.genai.flow.context import FlowContext
 
 
 class EchoNodeHandler(NodeHandler):