xpander-sdk 2.0.396__tar.gz → 2.0.397__tar.gz

{xpander_sdk-2.0.396/src/xpander_sdk.egg-info → xpander_sdk-2.0.397}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.396
+Version: 2.0.397
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI

{xpander_sdk-2.0.396 → xpander_sdk-2.0.397}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="xpander-sdk",
-    version="2.0.396",
+    version="2.0.397",
     author="xpanderAI",
     author_email="dev@xpander.ai",
     description="xpander.ai Backend-as-a-service for AI Agents - SDK",

{xpander_sdk-2.0.396 → xpander_sdk-2.0.397}/src/xpander_sdk/__init__.py

@@ -15,7 +15,7 @@ Main Components:
 For more information, visit: https://xpander.ai
 """
 
-__version__ = "2.0.396"
+__version__ = "2.0.397"
 
 # Backend-related imports
 from .modules.backend.backend_module import Backend

{xpander_sdk-2.0.396 → xpander_sdk-2.0.397}/src/xpander_sdk/core/context_optimizer/constants.py

@@ -248,3 +248,17 @@ PLAN_BLOCK_LABEL = "Execution plan steps"
 # the tool with empty args. 32K covers any realistic single tool call
 # while modern Claude models allow far more.
 LLM_MAX_OUTPUT_TOKENS = _env_int("XPANDER_LLM_MAX_OUTPUT_TOKENS", 32_000)
+
+# Args-agnostic per-tool volume ceiling. Pagination runaways vary the cursor
+# on every call and alternating-tool loops reset the consecutive counters, so
+# neither the identical-args detector nor the error-streak breaker ever fires
+# on them. This counts TOTAL calls of one tool across the task (xp* exempt).
+TOTAL_TOOL_CALLS_WARN_AT = _env_int("XPANDER_TOTAL_TOOL_CALLS_WARN_AT", 15)
+MAX_TOTAL_TOOL_CALLS_PER_TOOL = _env_int("XPANDER_MAX_TOTAL_TOOL_CALLS_PER_TOOL", 25)
+
+# Plan-churn breaker. Planning/reasoning tools are exempt from stuck detection
+# (they legitimately repeat), so a pure plan/think loop - re-emitting the same
+# decision step with no real tool call in between - previously ran unbounded.
+# Counts consecutive planning/reasoning calls; any other tool resets it.
+PLAN_CHURN_WARN_AT = _env_int("XPANDER_PLAN_CHURN_WARN_AT", 10)
+MAX_PLAN_CHURN = _env_int("XPANDER_MAX_PLAN_CHURN", 16)

{xpander_sdk-2.0.396 → xpander_sdk-2.0.397}/src/xpander_sdk/core/context_optimizer/finalize_mode.py

@@ -40,6 +40,8 @@ FinalizeReason = Literal[
     "stagnant_compactions",
     "repeated_tool_call",
     "error_streak",
+    "tool_overuse",
+    "plan_churn",
 ]
 
 # System-prompt override appended to the agent's instructions while

{xpander_sdk-2.0.396 → xpander_sdk-2.0.397}/src/xpander_sdk/models/action_ledger.py

@@ -141,6 +141,8 @@ class FinalizeOnlyState(XPanderSharedModel):
             "stagnant_compactions",
             "repeated_tool_call",
             "error_streak",
+            "tool_overuse",
+            "plan_churn",
         ]
     ] = None
 

{xpander_sdk-2.0.396 → xpander_sdk-2.0.397}/src/xpander_sdk/modules/backend/frameworks/agno.py

@@ -26,10 +26,14 @@ from xpander_sdk.core.context_optimizer.constants import (
     FINALIZE_MODE_ENABLED,
     LEDGER_ENABLED,
     LLM_MAX_OUTPUT_TOKENS,
+    MAX_PLAN_CHURN,
+    MAX_TOTAL_TOOL_CALLS_PER_TOOL,
     PLAN_BLOCK_LABEL,
+    PLAN_CHURN_WARN_AT,
     MANUAL_COMPACT_TOOL_ENABLED,
     MAX_REPEATED_TOOL_CALLS,
     REPEATED_TOOL_CALL_WARN_AT,
+    TOTAL_TOOL_CALLS_WARN_AT,
     TRUNCATED_TOOL_CALL_MESSAGE,
 )
 from xpander_sdk.core.context_optimizer.context_optimizer import (
@@ -75,6 +79,8 @@ from xpander_sdk.modules.backend.utils.tool_call_events import (
     get_tool_call_summary,
     is_agent_gateway_task,
     is_reasoning_tool,
+    PLANNING_TOOLS,
+    REASONING_TOOLS,
     report_reasoning_event,
     report_tool_call_request,
     report_tool_call_result,
@@ -667,6 +673,36 @@ def _bump_error_streak(
     return streak
 
 
+def _bump_total_calls(task, function_name: str) -> int:
+    """Task-scoped args-agnostic total call count for one tool (0 when no task to pin state on)."""
+    if task is None:
+        return 0
+    counts = getattr(task, "_xp_tool_total_calls", None)
+    if not isinstance(counts, dict):
+        counts = {}
+        try:
+            object.__setattr__(task, "_xp_tool_total_calls", counts)
+        except Exception:
+            return 0
+    counts[function_name] = counts.get(function_name, 0) + 1
+    return counts[function_name]
+
+
+_PLAN_CHURN_TOOLS = PLANNING_TOOLS | REASONING_TOOLS
+
+
+def _bump_plan_churn(task, function_name: str) -> int:
+    """Consecutive planning/reasoning calls with no real tool in between; any other tool resets."""
+    if task is None:
+        return 0
+    streak = (getattr(task, "_xp_plan_churn_streak", 0) + 1) if function_name in _PLAN_CHURN_TOOLS else 0
+    try:
+        object.__setattr__(task, "_xp_plan_churn_streak", streak)
+    except Exception:
+        return 0
+    return streak
+
+
 def _schema_satisfiable_by_empty(prop_schema: Any) -> bool:
     """True when ``{}`` (or omission) validates against *prop_schema*.
 
@@ -1364,6 +1400,80 @@ async def build_agent_args(
         except Exception:
             pass
 
+        # Args-agnostic per-tool volume guard: pagination varies the cursor every
+        # call and alternating-tool loops reset the consecutive counters, so the
+        # detectors above never fire on those runaway shapes.
+        try:
+            if not function_name.startswith("xp"):
+                total_calls = _bump_total_calls(task, function_name)
+                if total_calls >= MAX_TOTAL_TOOL_CALLS_PER_TOOL:
+                    optimizer_for_volume = args.get("compression_manager")
+                    if isinstance(optimizer_for_volume, XPanderContextOptimizer):
+                        try:
+                            enter_finalize_mode(optimizer_for_volume, reason="tool_overuse")
+                        except Exception as exc:
+                            logger.warning(
+                                f"[tool-volume] failed to enter finalize mode after "
+                                f"{total_calls}x '{function_name}': {exc}"
+                            )
+                    logger.warning(
+                        f"[tool-volume] aborting tool '{function_name}' for agent "
+                        f"{xpander_agent.id}: {total_calls} total calls this task "
+                        f"(cap {MAX_TOTAL_TOOL_CALLS_PER_TOOL}); entering finalize mode"
+                    )
+                    return TOOL_GATE_REJECTION_MESSAGE
+                if total_calls >= TOTAL_TOOL_CALLS_WARN_AT and not stuck_warning:
+                    stuck_warning = (
+                        f"⚠️ TOOL VOLUME: '{function_name}' has been called {total_calls} times in "
+                        f"this task (hard cap {MAX_TOTAL_TOOL_CALLS_PER_TOOL}). Stop paginating or "
+                        f"re-querying - work with the data you already have, or report the task as "
+                        f"blocked with a short status."
+                    )
+                    logger.warning(
+                        f"[tool-volume] '{function_name}' at {total_calls} total calls for "
+                        f"agent {xpander_agent.id}"
+                    )
+        except Exception:
+            pass
+
+        # Plan-churn breaker: planning/reasoning tools are exempt from the guards
+        # above, so a pure plan/think loop (re-adding the same decision step with
+        # no real tool call in between) previously ran unbounded.
+        try:
+            optimizer_for_churn = args.get("compression_manager")
+            # finalize mode's allowed read tools (xpget_agent_plan) must not re-trip the breaker
+            finalize_already_active = isinstance(
+                optimizer_for_churn, XPanderContextOptimizer
+            ) and is_finalize_active(optimizer_for_churn)
+            plan_churn = 0 if finalize_already_active else _bump_plan_churn(task, function_name)
+            if plan_churn >= MAX_PLAN_CHURN:
+                if isinstance(optimizer_for_churn, XPanderContextOptimizer):
+                    try:
+                        enter_finalize_mode(optimizer_for_churn, reason="plan_churn")
+                    except Exception as exc:
+                        logger.warning(
+                            f"[plan-churn] failed to enter finalize mode after "
+                            f"{plan_churn} consecutive plan/reasoning calls: {exc}"
+                        )
+                logger.warning(
+                    f"[plan-churn] aborting tool '{function_name}' for agent "
+                    f"{xpander_agent.id}: {plan_churn} consecutive planning/reasoning "
+                    f"calls with no real work (cap {MAX_PLAN_CHURN}); entering finalize mode"
+                )
+                return TOOL_GATE_REJECTION_MESSAGE
+            if plan_churn >= PLAN_CHURN_WARN_AT and not stuck_warning:
+                stuck_warning = (
+                    f"⚠️ PLAN CHURN: {plan_churn} consecutive planning/reasoning calls with no "
+                    f"real tool call in between (hard cap {MAX_PLAN_CHURN}). Stop re-planning - "
+                    f"execute the next plan step with an actual tool, or report the task as blocked."
+                )
+                logger.warning(
+                    f"[plan-churn] {plan_churn} consecutive plan/reasoning calls for "
+                    f"agent {xpander_agent.id} (latest '{function_name}')"
+                )
+        except Exception:
+            pass
+
         # Generate a fresh request_id for this tool invocation so multiple
         # calls to the same tool remain distinct in the activity thread.
         # Deep-planning tools are excluded from activity reporting.

{xpander_sdk-2.0.396 → xpander_sdk-2.0.397/src/xpander_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.396
+Version: 2.0.397
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI