langchain-agentx-python 0.9.5__tar.gz → 0.9.7__tar.gz

{langchain-agentx-python-0.9.5 → langchain-agentx-python-0.9.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 0.9.5
+Version: 0.9.7
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License

{langchain-agentx-python-0.9.5 → langchain-agentx-python-0.9.7}/langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "0.9.5"
+__version__ = "0.9.7"
 
 from .loop import (  # noqa: F401
     create_loop_agent,

{langchain-agentx-python-0.9.5 → langchain-agentx-python-0.9.7}/langchain_agentx/loop/exit/reason_codes.py

@@ -15,6 +15,7 @@ TERMINAL_REASON_STOP_HOOK_PREVENTED = "stop_hook_prevented"
 TERMINAL_REASON_ERROR = "error"
 TERMINAL_REASON_API_ERROR = "api_error"
 TERMINAL_REASON_GRAPH_RUNTIME_ERROR = "graph_runtime_error"
+TERMINAL_REASON_RUNTIME_BUDGET_EXHAUSTED = "runtime_budget_exhausted"
 TERMINAL_REASON_PROMPT_TOO_LONG = "prompt_too_long"
 TERMINAL_REASON_MAX_OUTPUT_TOKENS = "max_output_tokens"
 TERMINAL_REASON_INVARIANT_VIOLATION = "invariant_violation"
@@ -50,6 +51,7 @@ ERROR_TERMINAL_REASONS = frozenset(
         TERMINAL_REASON_ERROR,
         TERMINAL_REASON_API_ERROR,
         TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
+        TERMINAL_REASON_RUNTIME_BUDGET_EXHAUSTED,
         TERMINAL_REASON_PROMPT_TOO_LONG,
         TERMINAL_REASON_MAX_OUTPUT_TOKENS,
         TERMINAL_REASON_INVARIANT_VIOLATION,
@@ -69,6 +71,7 @@ __all__ = [
     "TERMINAL_REASON_ERROR",
     "TERMINAL_REASON_API_ERROR",
     "TERMINAL_REASON_GRAPH_RUNTIME_ERROR",
+    "TERMINAL_REASON_RUNTIME_BUDGET_EXHAUSTED",
     "TERMINAL_REASON_PROMPT_TOO_LONG",
     "TERMINAL_REASON_MAX_OUTPUT_TOKENS",
     "TERMINAL_REASON_INVARIANT_VIOLATION",

{langchain-agentx-python-0.9.5 → langchain-agentx-python-0.9.7}/langchain_agentx/loop/exit/terminal.py

@@ -24,6 +24,7 @@ from .reason_codes import (
     TERMINAL_REASON_STOP_HOOK_PREVENTED,
     TERMINAL_REASON_API_ERROR,
     TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
+    TERMINAL_REASON_RUNTIME_BUDGET_EXHAUSTED,
     TERMINAL_REASON_INVARIANT_VIOLATION,
     TERMINAL_REASON_MAX_OUTPUT_TOKENS,
     TERMINAL_REASON_MAX_TOKENS,
@@ -53,6 +54,7 @@ _ERROR_TERMINAL_REASONS = frozenset(
         TERMINAL_REASON_CONTENT_FILTER,
         TERMINAL_REASON_API_ERROR,
         TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
+        TERMINAL_REASON_RUNTIME_BUDGET_EXHAUSTED,
         TERMINAL_REASON_HOOK_STOPPED,
         TERMINAL_REASON_ABORTED_STREAMING,
         TERMINAL_REASON_ABORTED_TOOLS,

{langchain-agentx-python-0.9.5 → langchain-agentx-python-0.9.7}/langchain_agentx/loop/model/tool_call_degradation_corrector.py

@@ -163,6 +163,68 @@ class ToolCallDegradationCorrector:
             allowed_tool_names=self._allowed_tool_names | new_names,
         )
 
+    def bind(self, **kwargs: Any) -> "ToolCallDegradationCorrector":
+        """保住 wrapper：底层 ``bind(**model_settings)`` 后重新包装。
+
+        必须存在的原因：
+            ``get_bound_model`` 在「请求未携带工具」分支会执行
+            ``request.model.bind(**model_settings)``。如果只透传 ``__getattr__``，
+            返回的是底层 LLM 的 ``RunnableBinding``，纠偏逻辑会被剥掉，
+            导致 ``ainvoke`` 路径同样出现 silent drop。
+        """
+        bound = self._llm.bind(**kwargs)
+        return ToolCallDegradationCorrector(
+            llm=bound,
+            allowed_tool_names=set(self._allowed_tool_names),
+        )
+
+    def with_config(self, *args: Any, **kwargs: Any) -> "ToolCallDegradationCorrector":
+        """保住 wrapper：底层 ``with_config(...)`` 后重新包装。
+
+        必须存在的原因：
+            ``ModelNode._bind_llm_callback_handler`` 在 ``trace.enabled=True``
+            时会执行 ``model.with_config({"callbacks": [...]})``。若不覆写，
+            ``__getattr__`` 透传到底层 LLM，返回 ``RunnableBinding``，
+            纠偏逻辑同样被剥掉。
+        """
+        bound = self._llm.with_config(*args, **kwargs)
+        return ToolCallDegradationCorrector(
+            llm=bound,
+            allowed_tool_names=set(self._allowed_tool_names),
+        )
+
+    def with_retry(self, *args: Any, **kwargs: Any) -> "ToolCallDegradationCorrector":
+        """保住 wrapper：``Runnable.with_retry`` 入口必须返回 corrector，不退化为底层 binding。"""
+        bound = self._llm.with_retry(*args, **kwargs)
+        return ToolCallDegradationCorrector(
+            llm=bound,
+            allowed_tool_names=set(self._allowed_tool_names),
+        )
+
+    def with_fallbacks(self, *args: Any, **kwargs: Any) -> "ToolCallDegradationCorrector":
+        """保住 wrapper：``Runnable.with_fallbacks`` 入口必须返回 corrector。"""
+        bound = self._llm.with_fallbacks(*args, **kwargs)
+        return ToolCallDegradationCorrector(
+            llm=bound,
+            allowed_tool_names=set(self._allowed_tool_names),
+        )
+
+    def with_listeners(self, *args: Any, **kwargs: Any) -> "ToolCallDegradationCorrector":
+        """保住 wrapper：``Runnable.with_listeners`` 入口必须返回 corrector。"""
+        bound = self._llm.with_listeners(*args, **kwargs)
+        return ToolCallDegradationCorrector(
+            llm=bound,
+            allowed_tool_names=set(self._allowed_tool_names),
+        )
+
+    def with_types(self, *args: Any, **kwargs: Any) -> "ToolCallDegradationCorrector":
+        """保住 wrapper：``Runnable.with_types`` 入口必须返回 corrector。"""
+        bound = self._llm.with_types(*args, **kwargs)
+        return ToolCallDegradationCorrector(
+            llm=bound,
+            allowed_tool_names=set(self._allowed_tool_names),
+        )
+
     # ----------------------------
     # Runnable 接口：invoke / ainvoke
     # ----------------------------

{langchain-agentx-python-0.9.5 → langchain-agentx-python-0.9.7}/langchain_agentx/loop/stream/graph_driver.py

@@ -16,6 +16,8 @@ from __future__ import annotations
 import logging
 from typing import Any, AsyncIterator
 
+from langgraph.errors import GraphRecursionError
+
 from .result import StreamDriverResult
 from .synthetic_events import (
     build_synthetic_error_visible_event,
@@ -50,6 +52,24 @@ class GraphStreamDriver:
                 self._observe_event(event)
                 yield event
             self.result.graph_completed = True
+        except GraphRecursionError as exc:
+            self.result.final_error = exc
+            logger.exception("GraphStreamDriver recursion limit exceeded: %s", exc)
+            if not self.result.saw_error_visible_surface:
+                self.result.saw_error_visible_surface = True
+                yield build_synthetic_error_visible_event(
+                    message="Runtime budget exhausted (recursion limit reached)",
+                    error_kind="graph_recursion_error",
+                )
+            if not self.result.saw_finish_surface:
+                synthetic_output = dict(self.result.graph_output or {})
+                if "messages" not in synthetic_output:
+                    synthetic_output["messages"] = []
+                self.result.graph_output = synthetic_output
+                self.result.saw_finish_surface = True
+                self.result.saw_root_chain_end = True
+                yield build_synthetic_root_chain_end(graph_output=synthetic_output)
+            raise
         except Exception as exc:
             self.result.final_error = exc
             logger.exception("GraphStreamDriver graph stream failed: %s", exc)

{langchain-agentx-python-0.9.5 → langchain-agentx-python-0.9.7}/langchain_agentx/loop/stream/loop_driver.py

@@ -16,7 +16,12 @@ from __future__ import annotations
 import logging
 from typing import Any, AsyncIterator
 
-from ..exit.reason_codes import TERMINAL_REASON_GRAPH_RUNTIME_ERROR
+from langgraph.errors import GraphRecursionError
+
+from ..exit.reason_codes import (
+    TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
+    TERMINAL_REASON_RUNTIME_BUDGET_EXHAUSTED,
+)
 from ..exit.terminal import apply_terminal_reason_projection, build_loop_terminal
 from .result import StreamDriverResult
 from .synthetic_events import (
@@ -60,6 +65,36 @@ class LoopStreamDriver:
                 self._observe_event(event)
                 yield event
             self.result.graph_completed = True
+        except GraphRecursionError as exc:
+            self.result.final_error = exc
+            self._log_catch_error(exc)
+            for repair in self._orphan_tool_result_repairs():
+                yield repair
+            if not self.result.saw_error_visible_surface:
+                self.result.saw_error_visible_surface = True
+                yield build_synthetic_error_visible_event(
+                    message="Runtime budget exhausted (recursion limit reached)",
+                    error_kind="graph_recursion_error",
+                )
+            if not self.result.saw_finish_surface:
+                terminal = build_loop_terminal(
+                    reason=TERMINAL_REASON_RUNTIME_BUDGET_EXHAUSTED,
+                    error_kind="graph_recursion_error",
+                    step=(self.result.last_loop_snapshot or {}).get("step"),
+                    turn_count=(self.result.last_loop_snapshot or {}).get("turn_count"),
+                    provider_finish_reason=(self.result.last_loop_snapshot or {}).get("finish_reason"),
+                    errors=[str(exc)],
+                    metadata={
+                        "langgraph_error_type": "GraphRecursionError",
+                    },
+                )
+                self.result.terminal = terminal
+                synthetic_output = self._build_synthetic_graph_output(terminal)
+                self.result.graph_output = synthetic_output
+                self.result.saw_finish_surface = True
+                yield build_synthetic_root_chain_end(graph_output=synthetic_output)
+            self._log_catch_error_diagnostic(exc)
+            raise
         except Exception as exc:
             self.result.final_error = exc
             # CC catch 协议 §5.3.3：先记录日志 / 观测，再补 stream surface，最后 re-raise

{langchain-agentx-python-0.9.5 → langchain-agentx-python-0.9.7}/langchain_agentx/observability/events/langchain_agentx_event_adapter.py

@@ -98,6 +98,9 @@ class LangchainAgentEventType(Enum):
     # 错误
     ERROR = "error"
 
+    # Artifact（方案 A：通过自定义事件传递 artifact）
+    TOOL_ARTIFACT = "tool-artifact"
+
     # Task Runtime（对齐 CC task_started/task_progress）
     TASK_STARTED = "task-started"
     TASK_PROGRESS = "task-progress"
@@ -820,6 +823,35 @@ class LangGraphToLangchainAgentEventAdapter:
 
         # 图结束：如果仍有打开的 step，先补齐 finish-step，再发 finish
         if name == self.state.graph_name:
+            # ===== 兜底：关闭可能未完成的 model 输出状态 =====
+            # 原因：LangGraph 不保证 100% 发出 on_chat_model_end（见 LangChain callback 体系限制）
+            # 可能不发出的场景：
+            #   1. 流异常中断（网络断、超时、进程被杀）
+            #   2. LLM 节点内部用 sync invoke，吞掉细粒度事件
+            #   3. RunnableConfig 未透传，子 runnable 事件丢失
+            #   4. 自定义节点直接写 state，不走标准 LLM 回调
+            #   5. 大参数工具调用阻塞（见 github.com/langchain-ai/langchain/issues/24021）
+            # 而 on_chain_end(LangGraph) 是可靠信号，在此处兜底可确保事件成对。
+            #
+            # 注意：正常流程下 on_chat_model_end 已发出，is_text_active/is_reasoning_active
+            #       已为 false，此代码不会重复发事件。
+            if self.enable_reasoning_events and self.state.is_reasoning_active:
+                yield self._event(
+                    event_type=LangchainAgentEventType.REASONING_END,
+                    data={},
+                    step_index=self.state.step_index,
+                )
+                self.state.is_reasoning_active = False
+
+            if self.state.is_text_active:
+                yield self._event(
+                    event_type=LangchainAgentEventType.TEXT_END,
+                    data={},
+                    step_index=self.state.step_index,
+                )
+                self.state.is_text_active = False
+            # ===== 兜底结束 =====
+
             if self.enable_step_events and self.state.is_step_started and self.state.step_index > 0:
                 yield self._event(
                     event_type=LangchainAgentEventType.FINISH_STEP,
@@ -1307,6 +1339,36 @@ class LangGraphToLangchainAgentEventAdapter:
             )
             return
 
+        # 处理 tool_artifact 自定义事件（方案 A：解决 on_tool_end 不包含 artifact）
+        if event_name == "tool_artifact":
+            data = event.get("data", {})
+            if not isinstance(data, dict):
+                return
+            artifact = data.get("artifact")
+            if not isinstance(artifact, dict):
+                return
+            tool_name = data.get("tool_name", "")
+            status = data.get("status", "ok")
+            tool_call_id = data.get("tool_call_id", "")
+            # 发送 TOOL_ARTIFACT 事件，包含完整的 artifact 数据（含 display）
+            artifact_event_data = {
+                "tool_name": tool_name,
+                "tool_call_id": tool_call_id,
+                "status": status,
+            }
+            # 平铺 artifact v1 字段
+            artifact_event_data.update(self._flatten_artifact_v1_fields(artifact))
+            # 单独处理 display 字段
+            if "display" in artifact:
+                artifact_event_data["display"] = artifact["display"]
+            yield self._event(
+                event_type=LangchainAgentEventType.TOOL_ARTIFACT,
+                data=artifact_event_data,
+                step_index=self.state.step_index,
+                tool_name=tool_name,
+            )
+            return
+
         if not self.enable_subagent_events:
             return
 

{langchain-agentx-python-0.9.5 → langchain-agentx-python-0.9.7}/langchain_agentx/tool_runtime/adapter.py

@@ -453,7 +453,7 @@ class LangChainAdapter:
                 run_result=run_result,
                 ctx=ctx,
             )
-            return adapter.envelope_to_structured_tool_return(
+            content, artifact = adapter.envelope_to_structured_tool_return(
                 run_result.envelope,
                 tool=tool,
                 ctx=ctx,
@@ -461,6 +461,28 @@ class LangChainAdapter:
                 invoke_result=run_result.invoke_result,
             )
 
+            # 方案 A：发送 tool_artifact 自定义事件
+            # 将 artifact 通过自定义事件传递给下游，解决 on_tool_end 不包含 artifact 的问题
+            if artifact and isinstance(artifact, dict):
+                try:
+                    from langchain_core.callbacks import adispatch_custom_event
+
+                    await adispatch_custom_event(
+                        "tool_artifact",
+                        {
+                            "artifact": artifact,
+                            "tool_name": str(tool.name),
+                            "tool_call_id": ctx.tool_call_id,
+                            "status": artifact.get("status", "ok"),
+                        },
+                        config=config,
+                    )
+                except Exception:
+                    # 忽略事件发送失败，不影响工具功能
+                    pass
+
+            return content, artifact
+
         return StructuredTool(
             name=tool.name,
             description=tool.description,

{langchain-agentx-python-0.9.5 → langchain-agentx-python-0.9.7}/langchain_agentx/tool_runtime/pipeline.py

@@ -42,6 +42,10 @@ import logging
 import os
 import time
 import warnings
+from dataclasses import is_dataclass
+from datetime import date, datetime
+from enum import Enum
+from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from pydantic import ValidationError
@@ -639,6 +643,32 @@ class ToolExecutorPipeline:
                 tool.name,
                 run_result.envelope.status,
             )
+
+            # 方案 A：发送 tool_artifact 自定义事件
+            # 将 artifact 通过自定义事件传递给下游，解决 on_tool_end 不包含 artifact 的问题
+            if ctx.runnable_config is not None:
+                # 从 envelope 构建 artifact（不依赖 adapter，避免循环依赖）
+                artifact = self._build_artifact_from_envelope(
+                    run_result.envelope, tool, ctx, run_result.parsed_input, run_result.invoke_result
+                )
+                if artifact and isinstance(artifact, dict):
+                    try:
+                        from langchain_core.callbacks import adispatch_custom_event
+
+                        await adispatch_custom_event(
+                            "tool_artifact",
+                            {
+                                "artifact": artifact,
+                                "tool_name": str(tool.name),
+                                "tool_call_id": ctx.tool_call_id,
+                                "status": artifact.get("status", "ok"),
+                            },
+                            config=ctx.runnable_config,
+                        )
+                    except Exception:
+                        # 忽略事件发送失败，不影响工具功能
+                        pass
+
             await self._emit_tool_outcome_telemetry_async(
                 run_result.envelope, ctx, raw_input=raw_input
             )
@@ -662,6 +692,59 @@ class ToolExecutorPipeline:
         """异步执行完整 pipeline，始终返回 ToolResultEnvelope。"""
         return (await self.arun_with_result(tool=tool, raw_input=raw_input, ctx=ctx)).envelope
 
+    @staticmethod
+    def _build_artifact_from_envelope(
+        env: Any,
+        tool: Any,
+        ctx: ToolExecutionContext,
+        parsed_input: dict[str, Any] | None = None,
+        invoke_result: Any = None,
+    ) -> dict[str, Any]:
+        """从 envelope 构建 artifact（简化版，不依赖 LangChainAdapter）。"""
+        from dataclasses import asdict
+
+        def json_safe(value: Any) -> Any:
+            if value is None or isinstance(value, (bool, int, float, str)):
+                return value
+            if isinstance(value, Enum):
+                return value.value
+            if isinstance(value, Path):
+                return str(value)
+            if isinstance(value, (datetime, date)):
+                return value.isoformat()
+            if isinstance(value, bytes):
+                return value.decode("utf-8", errors="replace")
+            if is_dataclass(value) and not isinstance(value, type):
+                return json_safe(asdict(value))
+            if isinstance(value, dict):
+                return {str(k): json_safe(v) for k, v in value.items()}
+            if isinstance(value, (list, tuple)):
+                return [json_safe(v) for v in value]
+            return value
+
+        # 获取 envelope 数据
+        if hasattr(env, "envelope"):
+            # 如果是 PipelineRunResult，先提取 envelope
+            envelope = env.envelope
+        elif hasattr(env, "__dataclass_fields__"):
+            envelope = env
+        else:
+            return {}
+
+        artifact = json_safe(asdict(envelope))
+        artifact["schema_version"] = "2"
+
+        # 添加 display 字段（如果工具有 present_for_display 方法）
+        if hasattr(tool, "present_for_display") and parsed_input is not None:
+            try:
+                display = tool.present_for_display(parsed_input, invoke_result, ctx)
+                if display:
+                    artifact["display"] = display
+            except Exception:
+                pass
+
+        return artifact
+
     # ---- 内部实现 ----
 
     def _run(

{langchain-agentx-python-0.9.5 → langchain-agentx-python-0.9.7}/langchain_agentx/tools/bash/backend.py

@@ -1254,15 +1254,18 @@ class BashBackend:
         shell_exe = self._posix_shell_executable(env)
         spawn_env = self._spawn_env_with_shell(env, shell_exe)
         effective_cwd, reset_prefix = _prepare_spawn_cwd(cwd, fallback=fallback_cwd)
-        if effective_cwd is None:
-            msg = reset_prefix.strip() or "Shell cwd invalid and no valid fallback"
-            return ExecuteResult(
-                stdout="",
+        # effective_cwd is None 有两种情况：
+        # 1. reset_prefix 为空：用户未指定 cwd，使用当前进程工作目录（有效）
+        # 2. reset_prefix 非空：cwd 无效且无有效 fallback（错误）
+        if effective_cwd is None and reset_prefix:
+            yield BashStreamEvent(kind="chunk", chunk=reset_prefix)
+            yield BashStreamEvent(
+                kind="final",
                 exit_code=126,
                 interrupted=False,
-                stderr=msg + "\n",
-                cwd_warning=msg,
+                cwd_after=None,
             )
+            return
         if reset_prefix:
             yield BashStreamEvent(kind="chunk", chunk=reset_prefix)
         _cf = self._win32_creationflags()

{langchain-agentx-python-0.9.5 → langchain-agentx-python-0.9.7}/langchain_agentx_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 0.9.5
+Version: 0.9.7
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License

{langchain-agentx-python-0.9.5 → langchain-agentx-python-0.9.7}/pyproject.toml

@@ -4,7 +4,7 @@
 
  [project]
  name = "langchain-agentx-python"
- version = "0.9.5"
+ version = "0.9.7"
  description = "LangChain/LangGraph-based agent utilities for CodeBaseX."
  readme = "README.md"
  requires-python = ">=3.11"