langchain-agentx-python 2.2.5__tar.gz → 2.2.7__tar.gz

{langchain-agentx-python-2.2.5/langchain_agentx_python.egg-info → langchain-agentx-python-2.2.7}/PKG-INFO

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

{langchain-agentx-python-2.2.5 → langchain-agentx-python-2.2.7}/langchain_agentx/__init__.py

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

{langchain-agentx-python-2.2.5 → langchain-agentx-python-2.2.7}/langchain_agentx/tool_runtime/base.py

@@ -176,6 +176,12 @@ class RuntimeTool(ABC):
     is_concurrency_safe: bool = False
     """是否支持并发执行。"""
 
+    requires_user_interaction: bool = False
+    """
+    对齐 CC ``Tool.requiresUserInteraction()``。
+    True 时 bypassPermissions / auto allow 不得吞掉上游 ask（如 AskUser gather）。
+    """
+
     never_truncate: bool = False
     """
     禁止 ToolOutputManager 截断输出。
@@ -272,6 +278,15 @@ class RuntimeTool(ABC):
         _ = data, ctx
         return self.is_concurrency_safe
 
+    def requires_user_interaction_for(
+        self,
+        data: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> bool:
+        """该次调用是否强制用户交互；默认读取类属性（对齐 CC requiresUserInteraction）。"""
+        _ = data, ctx
+        return bool(self.requires_user_interaction)
+
     def resolve_capabilities(
         self,
         data: dict[str, Any],

{langchain-agentx-python-2.2.5 → langchain-agentx-python-2.2.7}/langchain_agentx/tool_runtime/inner_permission_chain.py

@@ -4,12 +4,13 @@ inner_permission_chain.py — CC inner 段 1–5（hasPermissionsToUseToolInner
 职责：
     在 PermissionOrchestrator 内编排 global deny/ask → L1 → mode 短路 → path policy
     → acceptEdits 快路径 → passthrough→ask。
+    RUI（requires_user_interaction）上游 ask 对齐 CC step 1e，不被 bypass 吞掉。
 
 链路位置：
     permission_orchestrator._evaluate_inner / _aevaluate_inner
 
 当前裁剪范围：
-    段 6（auto / L3）不在此模块；auto_mode hook 仍由 aauthorize outer 暂存至 Phase 4。
+    段 6（auto / L3）不在此模块。
 """
 
 from __future__ import annotations
@@ -64,6 +65,9 @@ class InnerPermissionChain:
         seg12 = self._segment_1_2_global(tool_name, data, ctx, tool_flags)
         if seg12 is not None:
             if seg12.behavior == "ask":
+                # CC step 1e：RUI + ask 不被 bypassPermissions 吞掉
+                if tool.requires_user_interaction_for(data, ctx):
+                    return seg12
                 seg4 = self._segment_4_mode_shortcircuit(tool, data, ctx, tool_flags)
                 if seg4 is not None:
                     return seg4
@@ -72,6 +76,10 @@ class InnerPermissionChain:
         l1 = tool.run_l1_permission_check(data, ctx)
         if l1.outcome != "continue":
             if l1.outcome == "ask":
+                if l1.decision is None:
+                    raise ValueError(f"L1 outcome={l1.outcome!r} requires decision")
+                if tool.requires_user_interaction_for(data, ctx):
+                    return l1.decision
                 seg4 = self._segment_4_mode_shortcircuit(tool, data, ctx, tool_flags)
                 if seg4 is not None:
                     return seg4

{langchain-agentx-python-2.2.5 → langchain-agentx-python-2.2.7}/langchain_agentx/tool_runtime/outer_permission_resolver.py

@@ -4,12 +4,13 @@ outer_permission_resolver.py — 段 6 outer 裁决（GAP-3）
 职责：
     inner 产出 ask 后：auto 分类器消化 / headless fail-close deny；非 ask 原样返回。
     classifier 熔断到顶：CLI → ask；headless → ClassifierDenialLimitAbort。
+    RUI 工具的 ask 不被 auto allow 吞掉（对齐 CC requiresUserInteraction）。
 
 链路位置：
     PermissionOrchestrator._resolve_outer
 
 当前裁剪范围：
-    不调用 L3 UI；AskUserQuestion gather 仍由 pipeline 特例处理。
+    不调用 L3 UI；AskUserQuestion gather ask 经 RUI 保留后由 pipeline L3 处理。
 """
 
 from __future__ import annotations
@@ -61,6 +62,8 @@ class OuterPermissionResolver:
         tool_flags = ctx.tool_flags if hasattr(ctx, "tool_flags") else {}
         mode = str(tool_flags.get("permission_mode", "default"))
 
+        inner_ask = decision
+
         if mode == "auto":
             auto_decision = await self._run_auto_mode_hook(tool, data, ctx)
             if auto_decision is not None:
@@ -70,12 +73,18 @@ class OuterPermissionResolver:
                     ctx,
                     headless=headless,
                 )
-                if auto_decision.behavior in ("allow", "deny", "ask"):
+                if (
+                    auto_decision.behavior == "allow"
+                    and tool.requires_user_interaction_for(data, ctx)
+                ):
+                    # CC：忽略 auto allow，保留 ask；继续走下方 headless / 透传
+                    pass
+                elif auto_decision.behavior in ("allow", "deny", "ask"):
                     return auto_decision
 
         if headless:
-            return self._headless_deny(decision)
-        return decision
+            return self._headless_deny(inner_ask)
+        return inner_ask
 
     @staticmethod
     async def _run_auto_mode_hook(

{langchain-agentx-python-2.2.5 → langchain-agentx-python-2.2.7}/langchain_agentx/tool_runtime/pipeline.py

@@ -31,8 +31,10 @@ runtime/pipeline.py — 工具执行管道与输出大小管控
         IdenticalCallMemo；命中则直接返回带 Hint 的 ToolResultEnvelope（不执行 invoke），
         作为“软提示防重复”策略的执行层硬约束替代。
 
-    AskUserQuestion：
-        `truncate_if_needed` 之后发 `ask_user_question_completed`（`_emit_post_invoke_analytics`）。
+    AskUserQuestion（CC L3）：
+        无 answers 时 L1 ask → 进 ``_handle_l3_ask``（不再 pending envelope 短路）；
+        handler 经 ``updated_input`` 注入 answers[+annotations] 后唯一 invoke；
+        `truncate_if_needed` 之后发 `ask_user_question_completed`。
 """
 
 from __future__ import annotations
@@ -77,7 +79,9 @@ from .denial_tracking_bridge import (
     record_l3_response,
     suppression_observability_events,
 )
+from .messages import INTERRUPT_MESSAGE_FOR_TOOL_USE
 from .prompt import (
+    DecisionReasonType,
     HeadlessPromptHandler,
     LegacyResolverPromptHandler,
     PermissionUpdate,
@@ -126,41 +130,6 @@ def _as_run_result(
 _ASK_USER_QUESTION_TOOL_NAME = "AskUserQuestion"
 
 
-def _try_envelope_pending_user_questions_gather(
-    *,
-    tool: RuntimeTool,
-    auth: AuthorizationDecision,
-    headless: bool,
-) -> ToolResultEnvelope | None:
-    """
-    AskUserQuestion：run_l1 / evaluate_permission 以 behavior=ask + metadata.gather_tool 表达「待 UI 收集答案」。
-    在 sync/async pipeline 中于默认 ask→blocked 之前短路，返回 ok envelope（payload 含 questions）。
-    """
-    md = auth.metadata or {}
-    if md.get("gather_tool") != tool.name:
-        return None
-    if headless:
-        return blocked_envelope(
-            tool.name,
-            "AskUserQuestion requires interactive mode.",
-            policy_id="ask_user_question_headless",
-        )
-    return ToolResultEnvelope(
-        status="ok",
-        tool_name=tool.name,
-        summary=auth.ask_prompt or auth.message or "Answer questions?",
-        payload={
-            "pending_user_questions": True,
-            "questions": md.get("questions"),
-        },
-        meta={
-            "gather_tool": tool.name,
-            "permission": "pending_user_questions",
-            "policy_id": auth.policy_id,
-        },
-    )
-
-
 def _emit_ask_user_question_analytics(
     *,
     tool: RuntimeTool,
@@ -173,9 +142,6 @@ def _emit_ask_user_question_analytics(
         return
     if envelope.status != "ok":
         return
-    meta_out = envelope.meta or {}
-    if meta_out.get("permission") == "pending_user_questions":
-        return
     collector = ctx.trace_collector
     session_id = ctx.trace_emit_session_id
     if collector is None or not isinstance(session_id, str) or not session_id.strip():
@@ -763,26 +729,6 @@ class ToolExecutorPipeline:
             )
             return _as_run_result(env, parsed_input=parsed_data, ctx=ctx)
         if auth.behavior == "ask":
-            gather = _try_envelope_pending_user_questions_gather(
-                tool=tool, auth=auth, headless=self._headless
-            )
-            if gather is not None:
-                self._attach_runtime_observability(
-                    gather,
-                    ctx=ctx,
-                    events=[
-                        {
-                            "event": "permission_checked",
-                            "behavior": "pending_user_questions",
-                            "policy_id": auth.policy_id,
-                        },
-                    ],
-                    decision_trace=(auth.metadata or {}).get("decision_trace"),
-                )
-                final_g = self._output_manager.truncate_if_needed(
-                    gather, tool, ctx.tool_call_id
-                )
-                return _as_run_result(final_g, parsed_input=parsed_data, ctx=ctx)
             logger.warning(
                 "tool permission requires ask tool=%s headless=%s policy_id=%s",
                 tool.name,
@@ -960,26 +906,6 @@ class ToolExecutorPipeline:
             )
             return _as_run_result(env, parsed_input=parsed_data, ctx=ctx)
         if auth.behavior == "ask":
-            gather = _try_envelope_pending_user_questions_gather(
-                tool=tool, auth=auth, headless=self._headless
-            )
-            if gather is not None:
-                self._attach_runtime_observability(
-                    gather,
-                    ctx=ctx,
-                    events=[
-                        {
-                            "event": "permission_checked",
-                            "behavior": "pending_user_questions",
-                            "policy_id": auth.policy_id,
-                        },
-                    ],
-                    decision_trace=(auth.metadata or {}).get("decision_trace"),
-                )
-                final_g = self._output_manager.truncate_if_needed(
-                    gather, tool, ctx.tool_call_id
-                )
-                return _as_run_result(final_g, parsed_input=parsed_data, ctx=ctx)
             logger.warning(
                 "tool permission requires ask tool=%s headless=%s policy_id=%s",
                 tool.name,
@@ -1125,6 +1051,12 @@ class ToolExecutorPipeline:
         ctx: ToolExecutionContext,
         auth: AuthorizationDecision,
     ) -> PromptRequest:
+        md = auth.metadata or {}
+        is_gather = md.get("gather_tool") == tool.name
+        questions = md.get("questions") if is_gather else None
+        if is_gather and questions is None:
+            raw_q = parsed_data.get("questions")
+            questions = raw_q if isinstance(raw_q, list) else None
         return PromptRequest(
             tool_name=tool.name,
             input_data=parsed_data,
@@ -1135,6 +1067,8 @@ class ToolExecutorPipeline:
             suggestions=self._suggestions_from_auth(auth),
             headless=False,
             session_headless=self._headless,
+            interaction_kind="gather" if is_gather else "permission",
+            questions=questions if isinstance(questions, list) else None,
         )
 
     def _maybe_suppress_l3_ask(
@@ -1319,21 +1253,51 @@ class ToolExecutorPipeline:
             )
 
         if resp.behavior == "deny":
+            reason = resp.decision_reason
+            is_cancel = (
+                reason is not None and reason.type == DecisionReasonType.USER_ABORT
+            )
+            is_gather = (auth.metadata or {}).get("gather_tool") == tool.name
+            if is_cancel:
+                msg = resp.message or resp.reason or INTERRUPT_MESSAGE_FOR_TOOL_USE
+                behavior_evt = "ask_cancelled_by_user"
+                extra_meta = {
+                    "l3_outcome": "cancel",
+                    "source_status": "interrupted",
+                    "error_kind": "aborted",
+                }
+            else:
+                if is_gather:
+                    msg = (
+                        resp.message
+                        or resp.reason
+                        or "User declined to answer questions."
+                    )
+                else:
+                    msg = (
+                        resp.message
+                        or resp.reason
+                        or auth.ask_prompt
+                        or "User rejected the operation."
+                    )
+                behavior_evt = "ask_rejected_by_resolver"
+                extra_meta = {"l3_outcome": "decline"}
             env = attach_permission_tool_input(
                 blocked_envelope(
                     tool.name,
-                    resp.message or resp.reason or auth.ask_prompt or "User rejected the operation.",
+                    msg,
                     policy_id=auth.policy_id,
                 ),
                 parsed_data,
             )
+            env.meta = {**(env.meta or {}), **extra_meta}
             attach_denial_tracking_meta(env, tool, ctx, auth)
             self._attach_runtime_observability(
                 env,
                 ctx=ctx,
                 events=[
                     self._permission_checked_event(
-                        "ask_rejected_by_resolver",
+                        behavior_evt,
                         auth.policy_id,
                         parsed_data,
                         decision_source=resp.decision_source.value,

{langchain-agentx-python-2.2.5 → langchain-agentx-python-2.2.7}/langchain_agentx/tool_runtime/prompt/__init__.py

@@ -16,6 +16,7 @@ from .race import HitlRaceCoordinator, PromptBranch, PromptClassifier
 from .types import (
     DecisionReason,
     DecisionReasonType,
+    InteractionKind,
     PermissionUpdate,
     PromptDecisionSource,
     PromptRequest,
@@ -26,6 +27,7 @@ __all__ = [
     "PermissionPromptHandler",
     "DecisionReason",
     "DecisionReasonType",
+    "InteractionKind",
     "PermissionUpdate",
     "PromptDecisionSource",
     "PromptRequest",

{langchain-agentx-python-2.2.5 → langchain-agentx-python-2.2.7}/langchain_agentx/tool_runtime/prompt/types.py

@@ -4,12 +4,15 @@ prompt/types.py — L3 HITL 数据契约
 职责：
     PromptRequest / PromptResponse 与 PermissionUpdate、PromptDecisionSource。
     L2 ask 决策打包为 PromptRequest，L3 产出二态 PromptResponse。
+    AskUser gather：interaction_kind=gather；updated_input 可含 answers[+annotations]。
 
 链路位置：
-    ToolExecutorPipeline ask 分支 → PermissionPromptHandler.handle（Phase 3 接线）。
+    ToolExecutorPipeline ask 分支 → PermissionPromptHandler.handle。
 
 当前裁剪：
-    PermissionUpdate 为 CC addRules/replaceRules 等的最小 Python 镜像；持久化由 Phase 3 接入。
+    PermissionUpdate 为 CC addRules/replaceRules 等的最小 Python 镜像。
+    A2：cancel=USER_ABORT / decline=USER_REJECT；reject_with_feedback=P1。
+    A3：图片 contentBlocks 旁路未建模。
 """
 
 from __future__ import annotations
@@ -28,6 +31,8 @@ from .messages import (
 )
 from ..messages import REJECT_MESSAGE, SUBAGENT_REJECT_MESSAGE
 
+InteractionKind = Literal["gather", "permission"]
+
 
 class PromptDecisionSource(StrEnum):
     """L3 决议来源，对齐 CC decisionReason.type。"""
@@ -108,11 +113,19 @@ class PromptRequest:
     display_label: str | None = None
     """UI 短摘要；来自 tool.summary_for_ui_call()。None 时 L3 fallback tool_name。"""
     suggestions: tuple[PermissionUpdate, ...] = field(default_factory=tuple)
+    interaction_kind: InteractionKind = "permission"
+    """permission=Allow/Deny；gather=AskUser Q→A（对 CC AskUserQuestionPermissionRequest）。"""
+    questions: list[Any] | None = None
+    """gather 时的问题列表（常来自 auth.metadata.questions）；permission 为 None。"""
 
 
 @dataclass(frozen=True)
 class PromptResponse:
-    """L3 → Pipeline 出参；behavior 仅 allow/deny。"""
+    """L3 → Pipeline 出参；behavior 仅 allow/deny。
+
+    allow 时 ``updated_input`` 可含 answers 与可选 annotations（A1）。
+    deny 时用 ``decision_reason.type`` 区分 cancel（USER_ABORT）与 decline（USER_REJECT）（A2 MVP）。
+    """
 
     behavior: Literal["allow", "deny"]
     decision_source: PromptDecisionSource

{langchain-agentx-python-2.2.5 → langchain-agentx-python-2.2.7}/langchain_agentx/tools/ask_user_question/tool.py

@@ -2,13 +2,16 @@
 tools/ask_user_question/tool.py — AskUserQuestionTool
 
 职责：
-    CC AskUserQuestion 对齐：normalize → validate → permissions（含待答两跳）→ invoke → present。
+    CC AskUserQuestion 对齐：normalize → validate → L1 ask（无 answers）→
+    L3 注入 answers[+annotations] → invoke → present。
 
 链路位置：
-    ToolRuntimeLoader.register_default_tools；pipeline 对 gather_tool 短路返回 pending envelope。
+    ToolRuntimeLoader.register_default_tools；pipeline 对 gather ask 走
+    ``_handle_l3_ask``（不再 pending envelope 短路）。
 
 当前裁剪范围：
-    v3：preview HTML 校验（ctx.question_preview_format）、annotations、present 摘要；渠道禁用集合对齐 CC。
+    v3：preview HTML 校验、annotations、present 摘要；渠道禁用集合对齐 CC。
+    A3 图片 contentBlocks 旁路未做。
 """
 
 from __future__ import annotations
@@ -40,7 +43,7 @@ from .prompt import (
 )
 from .validators import QuestionValidator
 
-# AuthorizationDecision.metadata：pipeline 识别待答短路（值须等于 RuntimeTool.name）
+# AuthorizationDecision.metadata：L3 PromptRequest.interaction_kind=gather 识别键
 GATHER_TOOL_META_KEY = "gather_tool"
 
 # CC isEnabled：Telegram/Discord 等无 TUI 渠道
@@ -84,6 +87,7 @@ class AskUserQuestionTool(RuntimeTool):
     is_read_only: bool = True
     is_destructive: bool = False
     is_concurrency_safe: bool = True
+    requires_user_interaction: bool = True
     never_truncate: bool = False
     dedupe_identical_calls: bool = False
     max_result_size_chars: int = 100_000

{langchain-agentx-python-2.2.5 → langchain-agentx-python-2.2.7}/langchain_agentx/tools/plan_mode/tool.py

@@ -183,6 +183,8 @@ class ExitPlanModeRuntimeTool(_PlanModeRuntimeToolBase):
     description: str = EXIT_PLAN_MODE_DESCRIPTION
     input_model = ExitPlanModeInput
     output_model = ExitPlanModeOutput
+    # 对齐 CC ExitPlanMode.requiresUserInteraction：bypass/auto 不得静默放行确认
+    requires_user_interaction: bool = True
 
     def prompt_for_model(self, ctx: ToolPromptContext) -> str:
         _ = ctx

{langchain-agentx-python-2.2.5 → langchain-agentx-python-2.2.7/langchain_agentx_python.egg-info}/PKG-INFO

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

{langchain-agentx-python-2.2.5 → langchain-agentx-python-2.2.7}/pyproject.toml

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