langchain-agentx-python 0.9.2__tar.gz → 0.9.3__tar.gz

{langchain-agentx-python-0.9.2 → langchain-agentx-python-0.9.3}/PKG-INFO

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

{langchain-agentx-python-0.9.2 → langchain-agentx-python-0.9.3}/langchain_agentx/__init__.py

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

{langchain-agentx-python-0.9.2 → langchain-agentx-python-0.9.3}/langchain_agentx/observability/events/finish_event_payload_composer.py

@@ -22,8 +22,10 @@ from langchain_core.messages import AIMessage
 
 from langchain_agentx.loop.exit.reason_codes import (
     ERROR_TERMINAL_REASONS,
+    TERMINAL_REASON_COMPLETED,
     TERMINAL_REASON_ERROR,
     TERMINAL_REASON_MAX_TOKENS,
+    TRANSITION_API_ERROR_TERMINAL,
     TRANSITION_CONTEXT_WINDOW_RECOVERY_EXHAUSTED,
     TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY_EXHAUSTED,
     TRANSITION_WITHHOLD_RECOVERY_EXHAUSTED,
@@ -117,7 +119,9 @@ class FinishEventPayloadComposer:
 
         from langchain_agentx.loop.exit.exit_logic import RECOVERABLE_TERMINAL_REASONS
 
-        is_error = self._resolve_is_error(terminal_reason, withheld_error, snap)
+        is_error = self._resolve_is_error(
+            terminal_reason, withheld_error, snap, messages=messages
+        )
         recoverable = (
             terminal_reason in RECOVERABLE_TERMINAL_REASONS if terminal_reason else False
         )
@@ -125,6 +129,14 @@ class FinishEventPayloadComposer:
         recovery_exhausted = (
             transition_reason in _RECOVERY_EXHAUSTED_TRANSITIONS if is_error else False
         )
+        if (
+            not recovery_exhausted
+            and is_error
+            and terminal_reason == TERMINAL_REASON_MAX_TOKENS
+            and resolve_overflow_kind(withheld_error) == "context_window"
+            and bool(snap.get("has_attempted_reactive_compact"))
+        ):
+            recovery_exhausted = True
         error_kind = self._infer_error_kind(
             terminal_reason=terminal_reason,
             is_error=is_error,
@@ -166,7 +178,14 @@ class FinishEventPayloadComposer:
         terminal_reason: str | None,
         withheld_error: dict[str, Any] | None,
         snap: dict[str, Any],
+        *,
+        messages: list[Any] | None = None,
     ) -> bool:
+        transition_reason = _transition_reason(snap)
+        if transition_reason == TRANSITION_API_ERROR_TERMINAL:
+            return True
+        if _is_api_error_message(_last_ai_message(messages)):
+            return True
         if terminal_reason in ERROR_TERMINAL_REASONS:
             return True
         if isinstance(withheld_error, dict) and withheld_error and snap.get("should_end"):
@@ -185,6 +204,13 @@ class FinishEventPayloadComposer:
         if not is_error:
             return None
 
+        last_ai = _last_ai_message(messages)
+        if (
+            transition_reason == TRANSITION_API_ERROR_TERMINAL
+            or _is_api_error_message(last_ai)
+        ):
+            return "api_error"
+
         overflow_kind = resolve_overflow_kind(withheld_error)
         if terminal_reason == TERMINAL_REASON_MAX_TOKENS:
             if overflow_kind == "context_window" or (
@@ -198,9 +224,9 @@ class FinishEventPayloadComposer:
             return "unknown"
 
         if terminal_reason == TERMINAL_REASON_ERROR:
-            last_ai = _last_ai_message(messages)
-            if _is_api_error_message(last_ai):
-                return "api_error"
+            return "unknown"
+
+        if terminal_reason == TERMINAL_REASON_COMPLETED:
             return "unknown"
 
         return "unknown"

{langchain-agentx-python-0.9.2 → langchain-agentx-python-0.9.3}/langchain_agentx/session/__init__.py

@@ -6,12 +6,22 @@ from .conversation_factory import create_conversation_session
 from .conversation_session import ConversationSession
 from .factory import create_agent_session
 from .protocol import LoopContainer
+from .recovery import (
+    SessionRecoveryRunResult,
+    finish_outcome_from_graph_output,
+    parse_result_finish_outcome,
+    run_with_recovery_loop,
+)
 
 __all__ = [
     "AgentSession",
     "ConversationSession",
     "LoopContainer",
+    "SessionRecoveryRunResult",
     "create_agent_session",
     "create_conversation_session",
+    "finish_outcome_from_graph_output",
     "load_session_messages",
+    "parse_result_finish_outcome",
+    "run_with_recovery_loop",
 ]

{langchain-agentx-python-0.9.2 → langchain-agentx-python-0.9.3}/langchain_agentx/session/agent_session.py

@@ -29,8 +29,13 @@ from ..command.builtin import (
     make_memory_command,
     make_reload_plugins_command,
 )
-from ..observability.events.finish_outcome import enrich_run_result
+from ..observability.events.finish_outcome import RecoveryPolicyMode, enrich_run_result
 from ..loop.config import merge_run_config
+from .recovery import (
+    SessionRecoveryRunResult,
+    finish_outcome_from_graph_output,
+    run_with_recovery_loop,
+)
 from ..loop.context.compaction_service import default_loop_context_compaction
 from ..loop.context.message_utils import total_estimated_tokens_for_messages
 from ..loop.hook.types import HookContext, HookEvent
@@ -74,6 +79,7 @@ class AgentSession:
         self._enable_trace = enable_trace
         self._transcript_writer = transcript_writer
         self._last_transcript_uuid: str | None = None
+        self._last_finish_outcome: dict[str, Any] | None = None
         self._session_memory_manager: Any | None = None
         self._capabilities = capabilities or RuntimeCapabilities.build(
             resource_root=workspace_cfg.workspace_root,
@@ -119,10 +125,48 @@ class AgentSession:
             await self._plugin_loader.unload_all()
 
     async def run_loop(self, user_input: str) -> dict[str, Any]:
+        result = await self._run_loop_turn(user_input=user_input)
+        return result
+
+    async def resume_after_compact(self) -> dict[str, Any]:
+        """compact 后重跑当前轮：不再 append 新的 HumanMessage。
+
+        适用于 CLI `/compact` 或 headless auto 恢复的第二跳；与 ``run_loop(same_query)``
+        不同，不会把同一用户问题重复写入 messages / transcript。
+        """
+        return await self._run_loop_turn(user_input=None)
+
+    async def run_with_recovery(
+        self,
+        user_input: str,
+        *,
+        mode: RecoveryPolicyMode = "auto",
+        max_outer_retries: int = 1,
+        progress_callback: Any = None,
+    ) -> SessionRecoveryRunResult:
+        """B1 外层自动恢复：recoverable 时 compact + resume，受 ``max_outer_retries`` 约束。
+
+        - ``mode="auto"``：可恢复且未 exhausted 时自动 compact 并 resume。
+        - ``mode="interactive"``：只跑一轮，把 ``RecoveryAction`` 留给 CLI 决策。
+        """
+        return await run_with_recovery_loop(
+            user_input=user_input,
+            mode=mode,
+            max_outer_retries=max_outer_retries,
+            run_new_turn=lambda inp: self._run_loop_turn(user_input=inp),
+            resume_current_turn=lambda: self._run_loop_turn(user_input=None),
+            compact=self.compact_context,
+            progress_callback=progress_callback,
+        )
+
+    async def _run_loop_turn(self, *, user_input: str | None) -> dict[str, Any]:
         if self._graph is None:
             raise RuntimeError("AgentSession graph is not initialized")
-        appended_message = HumanMessage(content=user_input)
-        self._messages.append(appended_message)
+
+        appended_message: HumanMessage | None = None
+        if user_input is not None:
+            appended_message = HumanMessage(content=user_input)
+            self._messages.append(appended_message)
         baseline_count = len(self._messages)
         run_config = merge_run_config(self._graph, None)
         try:
@@ -134,20 +178,26 @@ class AgentSession:
                 config=run_config,
             )
         except Exception:
-            # 回滚本轮 append，避免异常路径重复累积 user 消息。
-            if self._messages and self._messages[-1] is appended_message:
+            if appended_message is not None and self._messages and self._messages[-1] is appended_message:
                 self._messages.pop()
             raise
+
         if isinstance(result, dict) and isinstance(result.get("messages"), list):
             new_messages = list(result["messages"])
             self._messages = new_messages
-            self._append_transcript_message(appended_message)
+            if appended_message is not None:
+                self._append_transcript_message(appended_message)
             for message in new_messages[baseline_count:]:
                 self._append_transcript_message(message)
         self._active_files.extend(self._extract_accessed_files(result))
+
+        enriched: dict[str, Any]
         if isinstance(result, dict):
-            return enrich_run_result(dict(result))
-        return dict(result) if isinstance(result, dict) else {"result": result}
+            enriched = enrich_run_result(dict(result))
+        else:
+            enriched = {"result": result}
+        self._last_finish_outcome = enriched.get("finish_outcome")
+        return enriched
 
     async def stream_loop_events(
         self,
@@ -161,6 +211,10 @@ class AgentSession:
         说明：
             该方法用于需要 astream_events 的场景（如 SSE），执行完成后会尝试
             从 on_chain_end(LangGraph) 事件回填消息列表，保持与 run_loop 一致的上下文累积语义。
+
+        契约：
+            ``last_finish_outcome`` 仅在事件流完整消费到 ``on_chain_end(name=LangGraph)``
+            后可靠；中途 break / 异常时可能仍为 None 或上一轮快照。
         """
         if self._graph is None:
             raise RuntimeError("AgentSession graph is not initialized")
@@ -168,6 +222,7 @@ class AgentSession:
         self._messages.append(appended_message)
         baseline_count = len(self._messages)
         output_messages: list[Any] | None = None
+        graph_output: dict[str, Any] | None = None
         run_config = merge_run_config(self._graph, config)
         try:
             async for event in self._graph.astream_events(
@@ -181,6 +236,8 @@ class AgentSession:
                 if event.get("event") == "on_chain_end" and event.get("name") == "LangGraph":
                     data = event.get("data", {}) or {}
                     output = data.get("output")
+                    if isinstance(output, dict):
+                        graph_output = dict(output)
                     if isinstance(output, dict) and isinstance(output.get("messages"), list):
                         output_messages = list(output["messages"])
                 yield event
@@ -193,6 +250,21 @@ class AgentSession:
             self._append_transcript_message(appended_message)
             for message in output_messages[baseline_count:]:
                 self._append_transcript_message(message)
+        if graph_output is not None:
+            self._last_finish_outcome = finish_outcome_from_graph_output(graph_output)
+            if isinstance(graph_output.get("_accessed_files"), list):
+                self._active_files.extend(
+                    [item for item in graph_output["_accessed_files"] if isinstance(item, str)]
+                )
+
+    @property
+    def last_finish_outcome(self) -> dict[str, Any] | None:
+        """最近一次 run_loop / resume / stream 结束后的 finish_outcome 快照。
+
+        流式路径：仅当 ``stream_loop_events`` 完整消费到 LangGraph ``on_chain_end`` 后更新；
+        中途中断时可能为 None 或 stale，勿当作本轮终态。
+        """
+        return self._last_finish_outcome
 
     @property
     def active_files(self) -> list[str]:
@@ -347,4 +419,4 @@ class AgentSession:
         self._runtime_command_registry.register(make_reload_plugins_command())
 
 
-__all__ = ["AgentSession"]
+__all__ = ["AgentSession", "SessionRecoveryRunResult"]

langchain-agentx-python-0.9.3/langchain_agentx/session/recovery.py

@@ -0,0 +1,111 @@
+"""
+session/recovery.py — AgentSession 外层恢复编排（B1 auto / interactive 分流）
+
+职责：
+    在 run_loop + compact_context 之上封装「compact 后继续同一问题」与 auto 模式重试预算，
+    避免消费方重复 append 同一条 HumanMessage。
+
+链路位置：
+    AgentSession.run_with_recovery / resume_after_compact → 本模块
+
+当前裁剪范围：
+    - 不做图内 reactive_compact 拓扑修复（见 release 文档缺口 2）
+    - 不做 B2 透明自恢复（单次 invoke 内无感知恢复）
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Protocol
+
+from langchain_agentx.observability.events.finish_outcome import (
+    FinishOutcome,
+    FinishOutcomeParser,
+    RecoveryAction,
+    RecoveryActionResolver,
+    RecoveryPolicyMode,
+)
+
+
+class _CompactCallable(Protocol):
+    async def __call__(self, *, progress_callback: Any = None) -> tuple[int, int]: ...
+
+
+class _RunOnceCallable(Protocol):
+    async def __call__(self) -> dict[str, Any]: ...
+
+
+@dataclass(frozen=True)
+class SessionRecoveryRunResult:
+    """run_with_recovery 返回：最后一轮 graph 结果 + 终态语义 + 外层 compact 次数。"""
+
+    result: dict[str, Any]
+    outcome: FinishOutcome
+    action: RecoveryAction
+    outer_recovery_attempts: int
+
+
+def parse_result_finish_outcome(result: dict[str, Any]) -> FinishOutcome:
+    raw = result.get("finish_outcome")
+    if isinstance(raw, dict):
+        return FinishOutcomeParser().parse_finish_data(raw)
+    return FinishOutcomeParser().from_loop_state(result)
+
+
+def finish_outcome_from_graph_output(output: dict[str, Any] | None) -> dict[str, Any]:
+    """从 LangGraph on_chain_end output 构建 finish_outcome 字典（流式路径）。"""
+    if not isinstance(output, dict):
+        return FinishOutcomeParser().from_loop_state({}).to_dict()
+    outcome = FinishOutcomeParser().from_loop_state(output)
+    return outcome.to_dict()
+
+
+async def run_with_recovery_loop(
+    *,
+    user_input: str,
+    mode: RecoveryPolicyMode,
+    max_outer_retries: int,
+    run_new_turn: Callable[[str], Awaitable[dict[str, Any]]],
+    resume_current_turn: Callable[[], Awaitable[dict[str, Any]]],
+    compact: _CompactCallable,
+    progress_callback: Any = None,
+) -> SessionRecoveryRunResult:
+    """B1 外层编排：首轮 run_new_turn；recoverable 时 compact + resume（不重复 append）。"""
+    if max_outer_retries < 0:
+        raise ValueError("max_outer_retries must be >= 0")
+
+    result = await run_new_turn(user_input)
+    outcome = parse_result_finish_outcome(result)
+    action = RecoveryActionResolver.resolve(outcome, mode=mode)
+    attempts = 0
+
+    while attempts < max_outer_retries:
+        if outcome.succeeded:
+            break
+        if RecoveryActionResolver.blocks_auto_compact(outcome):
+            break
+        if mode == "interactive":
+            break
+        resolved = RecoveryActionResolver.resolve(outcome, mode="auto")
+        if resolved != RecoveryAction.AUTO_COMPACT:
+            break
+        await compact(progress_callback=progress_callback)
+        attempts += 1
+        result = await resume_current_turn()
+        outcome = parse_result_finish_outcome(result)
+        action = RecoveryActionResolver.resolve(outcome, mode=mode)
+
+    return SessionRecoveryRunResult(
+        result=result,
+        outcome=outcome,
+        action=action,
+        outer_recovery_attempts=attempts,
+    )
+
+
+__all__ = [
+    "SessionRecoveryRunResult",
+    "finish_outcome_from_graph_output",
+    "parse_result_finish_outcome",
+    "run_with_recovery_loop",
+]

{langchain-agentx-python-0.9.2 → langchain-agentx-python-0.9.3}/langchain_agentx/tool_runtime/path_safety.py

@@ -52,6 +52,12 @@ _WORKTREES_SEGMENT = "worktrees"
 # agent_home_segment 下需 ask 的子目录（对齐 isClaudeConfigFilePath 的 commands/agents/skills）
 _AGENT_CONFIG_SUBDIRS: tuple[str, ...] = ("commands", "agents", "skills")
 
+# agent_home 下允许静默写入的子目录（对齐 CC checkEditableInternalPath）。
+# 与 agent_home_segment 绑定：.langchain_agentx / .claude / .cursor 均适用 memory/、sessions/。
+_AGENT_INTERNAL_WRITABLE_SUBDIRS: frozenset[str] = frozenset(
+    {"memory", "sessions", "worktrees"}
+)
+
 _IDE_SETTINGS_PARENTS: tuple[str, ...] = (".vscode", ".cursor")
 
 
@@ -104,7 +110,6 @@ class PathSafetyEvaluator:
             s.lower() for s in (*config.dangerous_directory_segments, config.agent_home_segment)
         )
         self._agent_home_lower = home
-        self._worktrees_lower = config.worktrees_segment.lower()
 
     def evaluate_unc_path(self, path: str) -> AuthorizationDecision | None:
         """UNC / extended-length 前缀：Read 与 Write 均先拦截（CC 对齐）。"""
@@ -162,7 +167,7 @@ class PathSafetyEvaluator:
                 continue
             if seg_lower == self._agent_home_lower:
                 next_part = parts[i + 1] if i + 1 < len(parts) else None
-                if next_part and next_part.lower() == self._worktrees_lower:
+                if next_part and next_part.lower() in _AGENT_INTERNAL_WRITABLE_SUBDIRS:
                     continue
             return True
 

{langchain-agentx-python-0.9.2 → langchain-agentx-python-0.9.3}/langchain_agentx_python.egg-info/PKG-INFO

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

{langchain-agentx-python-0.9.2 → langchain-agentx-python-0.9.3}/langchain_agentx_python.egg-info/SOURCES.txt

@@ -208,6 +208,7 @@ langchain_agentx/session/conversation_recovery.py
 langchain_agentx/session/conversation_session.py
 langchain_agentx/session/factory.py
 langchain_agentx/session/protocol.py
+langchain_agentx/session/recovery.py
 langchain_agentx/task_runtime/__init__.py
 langchain_agentx/task_runtime/core/__init__.py
 langchain_agentx/task_runtime/core/ids.py

{langchain-agentx-python-0.9.2 → langchain-agentx-python-0.9.3}/pyproject.toml

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