@miller-tech/uap 1.118.1 → 1.118.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.118.1",
+  "version": "1.118.2",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",

package/tools/agents/scripts/anthropic_proxy.py

@@ -340,6 +340,83 @@ _WRITE_TOOL_CLASS = frozenset({
     "write_file", "edit_file", "save_file",
 })
 
+# Open-ended exploration tools the agent uses to make a DIFFERENT move once a
+# read/grep/glob loop is broken. The code cannot enumerate every exploration
+# tool, but these are the universal escape hatches. Cycle-break narrowing must
+# NEVER strip these: a cycling *Bash* means "vary the command" (handled by the
+# injected cycle hint), NOT "lose the ability to run bash at all". Excluding
+# Bash here stranded autonomous ("auto mode") agents with no way to explore the
+# filesystem — the whole toolset minus its exploration escape hatch.
+_EXPLORATION_ESCAPE_TOOLS = frozenset({
+    "bash", "shell", "sh", "run_bash", "runbash", "run_command",
+    "run_terminal_cmd", "execute_command", "executecommand", "terminal",
+    "webfetch", "web_fetch", "fetch", "websearch", "web_search",
+    "agent", "task", "dispatch_agent",
+})
+
+
+def _narrow_tools_for_cycle_break(tools, cycling_tool_names, session_banned_tools):
+    """Drop cycling + session-banned tools from the toolset, expanding to the
+    whole read-only class when any excluded tool is read-only.
+
+    The open-ended exploration escape hatch (Bash/WebFetch/Agent) is kept out of
+    the CYCLING-derived exclusion: a cycling Bash means "vary the command"
+    (handled by the injected cycle hint), not "lose the ability to run bash".
+    An explicit session ban is a stronger, deliberate signal (a tool that keeps
+    malforming) and IS still honored, even for those tools.
+
+    Returns ``(narrowed_tools, expanded_read_only_class)``. Tool-name matching is
+    case-insensitive so "Bash"/"bash" and "Read"/"read" behave identically.
+    """
+    read_only_lower = {c.lower() for c in _READ_ONLY_TOOL_CLASS}
+    cycling_lower = {n.lower() for n in cycling_tool_names}
+    banned_lower = {n.lower() for n in session_banned_tools}
+    # Expand to the full read-only class if any excluded tool is read-only
+    # (preserves the original trigger over cycling ∪ banned).
+    expanded = any(n in read_only_lower for n in (cycling_lower | banned_lower))
+    cycling_exclude = set(cycling_lower)
+    if expanded:
+        cycling_exclude |= read_only_lower
+    # Never let the cycling path narrow away the exploration escape hatch — that
+    # is exactly the filesystem-exploration capability the cycle-break is trying
+    # to redirect the agent toward.
+    cycling_exclude -= _EXPLORATION_ESCAPE_TOOLS
+    exclude_set = cycling_exclude | banned_lower
+
+    def _name(t):
+        return ((t.get("function", {}) or {}).get("name", "") or "").lower()
+
+    narrowed = [t for t in tools if _name(t) not in exclude_set]
+
+    # Floor invariant: a loop-breaker must never strand the agent. If narrowing
+    # would remove the last way to make a DIFFERENT move — i.e. no exploration
+    # escape hatch AND no write tool survives, but the original set had one —
+    # keep the original toolset. This closes the door where an explicit ban of
+    # the sole exploration tool re-creates the very "can't explore" bug.
+    write_lower = {w.lower() for w in _WRITE_TOOL_CLASS}
+
+    def _has_action_path(tool_list):
+        names = {_name(t) for t in tool_list}
+        return bool(names & _EXPLORATION_ESCAPE_TOOLS) or bool(names & write_lower)
+
+    if _has_action_path(tools) and not _has_action_path(narrowed):
+        return list(tools), expanded
+    return narrowed, expanded
+
+
+def _should_auto_ban(name, cycle_count, ban_at):
+    """Whether a cycling tool should be added to session_banned_tools this round.
+
+    The auto-ban accumulator is itself cycling-derived (ban after N detections),
+    so exploration escape-hatch tools (Bash/WebFetch/Agent) are NEVER auto-banned
+    — banning Bash would re-strip the agent's only way to explore the filesystem
+    on the Nth cycle, re-creating the bug the narrowing exemption fixes for
+    earlier cycles. Repeated Bash is redirected via the injected cycle hint.
+    """
+    if name.lower() in _EXPLORATION_ESCAPE_TOOLS:
+        return False
+    return cycle_count >= ban_at
+
 PROXY_GUARDRAIL_RETRY = os.environ.get("PROXY_GUARDRAIL_RETRY", "on").lower() not in {
     "0",
     "false",
@@ -4028,7 +4105,13 @@ def _resolve_state_machine_tool_choice(
                     and PROXY_COORDINATION_BAN_THRESHOLD > 0
                 )
                 ban_at = PROXY_COORDINATION_BAN_THRESHOLD if is_coord else 3
-                if monitor.tool_cycle_counts[name] >= ban_at and name not in monitor.session_banned_tools:
+                # Exploration escape-hatch tools are never auto-banned — see
+                # _should_auto_ban (banning Bash re-creates the "can't explore"
+                # bug since the ban is itself cycling-derived).
+                if (
+                    _should_auto_ban(name, monitor.tool_cycle_counts[name], ban_at)
+                    and name not in monitor.session_banned_tools
+                ):
                     monitor.session_banned_tools.add(name)
                     logger.warning(
                         "TOOL BAN: '%s' banned for session after %d cycle detections "
@@ -4853,16 +4936,15 @@ def build_openai_request(
                 (monitor.cycling_tool_names or monitor.session_banned_tools)
                 and "tools" in openai_body
             ):
-                exclude_set = set(monitor.cycling_tool_names) | monitor.session_banned_tools
-                # Expand to full read-only class if any cycling tool is read-only
-                if any(n.lower() in {c.lower() for c in _READ_ONLY_TOOL_CLASS} for n in exclude_set):
-                    exclude_set |= _READ_ONLY_TOOL_CLASS
                 original_count = len(openai_body["tools"])
-                narrowed = [
-                    t
-                    for t in openai_body["tools"]
-                    if t.get("function", {}).get("name") not in exclude_set
-                ]
+                # Drop cycling/banned tools (and the read-only class if any
+                # cycling tool is read-only) but always keep the exploration
+                # escape hatch — see _narrow_tools_for_cycle_break.
+                narrowed, expanded_read_only = _narrow_tools_for_cycle_break(
+                    openai_body["tools"],
+                    monitor.cycling_tool_names,
+                    monitor.session_banned_tools,
+                )
                 if narrowed:
                     openai_body["tools"] = narrowed
                     # Only log on first activation or phase transitions to reduce noise
@@ -4872,7 +4954,7 @@ def build_openai_request(
                             original_count,
                             len(narrowed),
                             monitor.cycling_tool_names,
-                            any(n.lower() in {c.lower() for c in _READ_ONLY_TOOL_CLASS} for n in monitor.cycling_tool_names),
+                            expanded_read_only,
                         )
                 else:
                     logger.warning(

package/tools/agents/tests/test_anthropic_proxy_streaming.py

@@ -3465,8 +3465,10 @@ class TestCycleBreakOptions(unittest.TestCase):
             setattr(proxy, "PROXY_TOOL_STATE_STAGNATION_THRESHOLD", old_stagnation)
             setattr(proxy, "PROXY_TOOL_STATE_CYCLE_WINDOW", old_cycle_window)
 
-    def test_cycle_break_narrows_tools(self):
-        """Option 2: cycling tools are excluded from the tools array during review."""
+    def test_cycle_break_keeps_bash_exploration(self):
+        """Cycling on Bash must NOT strip the Bash tool — it is the agent's
+        exploration escape hatch. (Regression: the cycle-break used to exclude
+        Bash by name, blocking all filesystem exploration.)"""
         old_state = getattr(proxy, "PROXY_TOOL_STATE_MACHINE")
         old_min_msgs = getattr(proxy, "PROXY_TOOL_STATE_MIN_MESSAGES")
         old_forced = getattr(proxy, "PROXY_TOOL_STATE_FORCED_BUDGET")
@@ -3516,9 +3518,10 @@ class TestCycleBreakOptions(unittest.TestCase):
 
             openai = proxy.build_openai_request(body, monitor)
             self.assertEqual(monitor.tool_turn_phase, "review")
-            # Bash should be excluded, Read and Write should remain
+            # Bash is the exploration escape hatch — it must remain available
+            # even while cycling. Read and Write remain too.
             tool_names = [t["function"]["name"] for t in openai.get("tools", [])]
-            self.assertNotIn("Bash", tool_names)
+            self.assertIn("Bash", tool_names)
             self.assertIn("Read", tool_names)
             self.assertIn("Write", tool_names)
         finally:
@@ -4548,7 +4551,8 @@ class TestReadOnlyCycleClassExclusion(unittest.TestCase):
                 setattr(proxy, k, v)
 
     def test_non_read_tool_cycling_no_class_expansion(self):
-        """When 'bash' is cycling, only 'bash' is excluded, not read-only tools."""
+        """When 'bash' is cycling, the read-only class is NOT expanded, and bash
+        itself is preserved as the exploration escape hatch."""
         old_vals = {
             "PROXY_TOOL_STATE_MACHINE": getattr(proxy, "PROXY_TOOL_STATE_MACHINE"),
             "PROXY_TOOL_STATE_MIN_MESSAGES": getattr(proxy, "PROXY_TOOL_STATE_MIN_MESSAGES"),
@@ -4581,8 +4585,9 @@ class TestReadOnlyCycleClassExclusion(unittest.TestCase):
             remaining_names = [
                 t.get("function", {}).get("name") for t in openai_body.get("tools", [])
             ]
-            self.assertNotIn("bash", remaining_names)
-            # Read-only tools should still be available
+            # bash is an exploration escape hatch — cycling does not strip it.
+            self.assertIn("bash", remaining_names)
+            # Read-only tools should still be available (no class expansion)
             self.assertIn("read", remaining_names)
             self.assertIn("glob", remaining_names)
             self.assertIn("grep", remaining_names)
@@ -4685,16 +4690,20 @@ class TestPersistentCycleExclusion(unittest.TestCase):
             body = self._make_body_with_tools(all_tools)
             monitor = proxy.SessionMonitor(context_window=262144)
 
-            # Simulate bash cycling that triggers review
-            monitor.cycling_tool_names = ["bash"]
+            # Simulate a non-exploration tool cycling that triggers review. (Bash
+            # is exempt from cycling exclusion, so use 'edit' to exercise the
+            # persistence path.)
+            monitor.cycling_tool_names = ["edit"]
             monitor.tool_turn_phase = "act"
             monitor.tool_state_forced_budget_remaining = 5
 
             openai = proxy.build_openai_request(body, monitor)
 
-            # In act phase with cycling_tool_names set, bash should be excluded
+            # In act phase with cycling_tool_names set, the cycling tool stays
+            # excluded — but the exploration escape hatch (bash) is preserved.
             remaining = [t["function"]["name"] for t in openai.get("tools", [])]
-            self.assertNotIn("bash", remaining)
+            self.assertNotIn("edit", remaining)
+            self.assertIn("bash", remaining)
             self.assertIn("read", remaining)
             self.assertIn("write", remaining)
         finally:

package/tools/agents/tests/test_cycle_break_exploration.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Unit tests for cycle-break tool narrowing preserving the exploration escape hatch.
+
+Regression: the CYCLE BREAK narrowing removed every cycling tool by name (and the
+whole read-only class if any cycling tool was read-only). Because Bash can be a
+cycling tool, the agent lost the Bash tool entirely and could no longer run any
+bash command to explore the filesystem. The narrowing must keep the open-ended
+exploration escape hatch (Bash/WebFetch/Agent) available so the agent can make a
+DIFFERENT move — the cycle *hint* handles "vary the command".
+"""
+
+import importlib.util
+import unittest
+from pathlib import Path
+
+
+def _load_proxy_module():
+    proxy_path = Path(__file__).resolve().parents[1] / "scripts" / "anthropic_proxy.py"
+    spec = importlib.util.spec_from_file_location("anthropic_proxy", proxy_path)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+proxy = _load_proxy_module()
+
+
+def _tools(*names):
+    return [{"function": {"name": n}} for n in names]
+
+
+def _names(tools):
+    return sorted(t["function"]["name"] for t in tools)
+
+
+class TestCycleBreakExploration(unittest.TestCase):
+    def test_cycling_bash_keeps_bash(self):
+        """The core bug: cycling on Bash must NOT remove the Bash tool."""
+        tools = _tools("Bash", "Read", "Write")
+        narrowed, expanded = proxy._narrow_tools_for_cycle_break(tools, {"Bash"}, set())
+        self.assertIn("Bash", _names(narrowed))
+        self.assertFalse(expanded)  # Bash is not read-only, so no class expansion
+
+    def test_read_only_cycle_expands_class_but_keeps_exploration(self):
+        """Cycling a read-only tool drops the whole read-only class, yet the
+        exploration escape hatch (Bash/WebFetch/Agent) survives."""
+        tools = _tools("Read", "Grep", "Glob", "Bash", "WebFetch", "Agent", "Write")
+        narrowed, expanded = proxy._narrow_tools_for_cycle_break(tools, {"Grep"}, set())
+        self.assertTrue(expanded)
+        kept = _names(narrowed)
+        # read-only class dropped
+        for n in ("Read", "Grep", "Glob"):
+            self.assertNotIn(n, kept)
+        # exploration escape hatch + writes preserved
+        for n in ("Bash", "WebFetch", "Agent", "Write"):
+            self.assertIn(n, kept)
+
+    def test_session_ban_is_honored_even_for_exploration_tools(self):
+        """An explicit session ban is a stronger, deliberate signal than cycling
+        and IS honored — even for an exploration tool. (Only the cycling path
+        preserves the escape hatch.)"""
+        tools = _tools("Bash", "Read", "Write")
+        narrowed, _ = proxy._narrow_tools_for_cycle_break(tools, set(), {"Bash"})
+        self.assertNotIn("Bash", _names(narrowed))
+
+    def test_cycling_bash_kept_even_when_another_tool_is_banned(self):
+        """A cycling Bash is preserved even while an unrelated tool is banned."""
+        tools = _tools("Bash", "Read", "Task")
+        narrowed, _ = proxy._narrow_tools_for_cycle_break(tools, {"Bash"}, {"Task"})
+        kept = _names(narrowed)
+        self.assertIn("Bash", kept)       # cycling exploration hatch preserved
+        self.assertNotIn("Task", kept)    # explicit ban honored
+
+    def test_case_insensitive_matching(self):
+        """Lowercase 'bash' in the cycling set must still match a 'Bash' tool
+        (and keep it), and 'read' must drop a 'Read' tool."""
+        tools = _tools("Bash", "Read")
+        narrowed, expanded = proxy._narrow_tools_for_cycle_break(
+            tools, {"bash", "read"}, set()
+        )
+        kept = _names(narrowed)
+        self.assertIn("Bash", kept)      # exploration hatch kept despite cycling
+        self.assertNotIn("Read", kept)   # read-only dropped
+        self.assertTrue(expanded)
+
+    def test_floor_keeps_last_action_tool_when_ban_would_strip_it(self):
+        """Floor invariant: if honoring a ban would leave NO exploration tool and
+        NO write tool, keep the original set — a loop-breaker must never strand
+        the agent with no way to make a different move."""
+        tools = _tools("Bash", "Read")  # Read is read-only, not an action path
+        narrowed, _ = proxy._narrow_tools_for_cycle_break(tools, set(), {"Bash"})
+        self.assertIn("Bash", _names(narrowed))  # floor restored the escape hatch
+
+    def test_floor_not_triggered_when_a_write_tool_survives(self):
+        """The ban IS honored when another action path (a write tool) remains."""
+        tools = _tools("Bash", "Read", "Write")
+        narrowed, _ = proxy._narrow_tools_for_cycle_break(tools, set(), {"Bash"})
+        kept = _names(narrowed)
+        self.assertNotIn("Bash", kept)  # honored: Write still gives an action path
+        self.assertIn("Write", kept)
+
+    def test_tool_class_taxonomy_is_pairwise_disjoint(self):
+        """Regression insurance: the three tool-class sets must never overlap, or
+        convergence accounting / cycle-break scope would silently change."""
+        ro = {c.lower() for c in proxy._READ_ONLY_TOOL_CLASS}
+        wr = {c.lower() for c in proxy._WRITE_TOOL_CLASS}
+        ex = {c.lower() for c in proxy._EXPLORATION_ESCAPE_TOOLS}
+        self.assertEqual(ro & wr, set())
+        self.assertEqual(ro & ex, set())
+        self.assertEqual(wr & ex, set())
+
+    def test_non_exploration_non_readonly_tool_dropped(self):
+        """A cycling tool that is neither read-only nor an exploration hatch is
+        dropped, and the read-only class is NOT expanded."""
+        tools = _tools("SomeTool", "Read", "Bash")
+        narrowed, expanded = proxy._narrow_tools_for_cycle_break(
+            tools, {"SomeTool"}, set()
+        )
+        kept = _names(narrowed)
+        self.assertNotIn("SomeTool", kept)
+        self.assertIn("Read", kept)      # class not expanded, Read survives
+        self.assertIn("Bash", kept)
+        self.assertFalse(expanded)
+
+
+class TestAutoBanExemption(unittest.TestCase):
+    """The session-ban accumulator is cycling-derived (ban after N detections).
+    Exploration escape-hatch tools must never be auto-banned, or the 'cannot
+    explore the filesystem' bug reappears on the Nth cycle."""
+
+    def test_bash_never_auto_banned_even_far_past_threshold(self):
+        self.assertFalse(proxy._should_auto_ban("bash", cycle_count=99, ban_at=3))
+        self.assertFalse(proxy._should_auto_ban("Bash", cycle_count=3, ban_at=3))
+
+    def test_other_exploration_tools_never_auto_banned(self):
+        for name in ("webfetch", "WebSearch", "agent", "task"):
+            self.assertFalse(proxy._should_auto_ban(name, cycle_count=10, ban_at=3))
+
+    def test_non_exploration_tool_banned_at_threshold(self):
+        self.assertTrue(proxy._should_auto_ban("edit", cycle_count=3, ban_at=3))
+        self.assertTrue(proxy._should_auto_ban("read", cycle_count=3, ban_at=3))
+
+    def test_non_exploration_tool_not_banned_below_threshold(self):
+        self.assertFalse(proxy._should_auto_ban("edit", cycle_count=2, ban_at=3))
+
+
+if __name__ == "__main__":
+    unittest.main()