@miller-tech/uap 1.15.6 → 1.15.8

package/package.json

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

package/tools/agents/scripts/anthropic_proxy.py

@@ -76,6 +76,7 @@ Dependencies
 """
 
 import asyncio
+import copy
 import hashlib
 import json
 import logging
@@ -254,6 +255,28 @@ PROXY_ANALYSIS_ONLY_MIN_TOOLS = int(
 PROXY_ANALYSIS_ONLY_MAX_MESSAGES = int(
     os.environ.get("PROXY_ANALYSIS_ONLY_MAX_MESSAGES", "2")
 )
+PROXY_TOOL_CALL_GRAMMAR = os.environ.get(
+    "PROXY_TOOL_CALL_GRAMMAR", "on"
+).lower() not in {
+    "0",
+    "false",
+    "off",
+    "no",
+}
+PROXY_TOOL_CALL_GRAMMAR_REQUIRED_ONLY = os.environ.get(
+    "PROXY_TOOL_CALL_GRAMMAR_REQUIRED_ONLY", "on"
+).lower() not in {
+    "0",
+    "false",
+    "off",
+    "no",
+}
+PROXY_TOOL_CALL_GRAMMAR_PATH = os.path.abspath(
+    os.environ.get(
+        "PROXY_TOOL_CALL_GRAMMAR_PATH",
+        os.path.join(os.path.dirname(__file__), "..", "config", "tool-call.gbnf"),
+    )
+)
 
 # ---------------------------------------------------------------------------
 # Logging
@@ -266,6 +289,45 @@ logging.basicConfig(
 logger = logging.getLogger("uap.anthropic_proxy")
 
 
+def _load_tool_call_grammar(path: str) -> str:
+    if not PROXY_TOOL_CALL_GRAMMAR:
+        return ""
+
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            return fh.read().strip()
+    except OSError as exc:
+        logger.warning(
+            "Tool-call grammar disabled: failed to read %s (%s)",
+            path,
+            exc,
+        )
+        return ""
+
+
+TOOL_CALL_GBNF = _load_tool_call_grammar(PROXY_TOOL_CALL_GRAMMAR_PATH)
+
+
+def _apply_tool_call_grammar(
+    request_body: dict, tool_choice: str | None = None
+) -> None:
+    request_body.pop("grammar", None)
+
+    if not PROXY_TOOL_CALL_GRAMMAR or not TOOL_CALL_GBNF:
+        return
+
+    if not request_body.get("tools"):
+        return
+
+    effective_tool_choice = (
+        tool_choice if tool_choice is not None else request_body.get("tool_choice")
+    )
+    if PROXY_TOOL_CALL_GRAMMAR_REQUIRED_ONLY and effective_tool_choice != "required":
+        return
+
+    request_body["grammar"] = TOOL_CALL_GBNF
+
+
 # ---------------------------------------------------------------------------
 # Option F: Session-level Context Window Monitor
 # ---------------------------------------------------------------------------
@@ -876,7 +938,7 @@ async def lifespan(app: FastAPI):
         _resolve_prune_target_fraction() * 100,
     )
     logger.info(
-        "Guardrails: malformed=%s stream_strict=%s force_non_stream=%s args_preflight=%s tool_narrowing=%s thinking_off_on_tools=%s dampener=%s(%d/%d/%d/%d->%d) contamination_breaker=%s(%d forced=%d required_miss=%d) analysis_only_route=%s(min_tools=%d,max_msgs=%d)",
+        "Guardrails: malformed=%s stream_strict=%s force_non_stream=%s args_preflight=%s tool_narrowing=%s thinking_off_on_tools=%s dampener=%s(%d/%d/%d/%d->%d) contamination_breaker=%s(%d forced=%d required_miss=%d) analysis_only_route=%s(min_tools=%d,max_msgs=%d) grammar=%s(required_only=%s loaded=%s path=%s)",
         PROXY_MALFORMED_TOOL_GUARDRAIL,
         PROXY_MALFORMED_TOOL_STREAM_STRICT,
         PROXY_FORCE_NON_STREAM,
@@ -896,6 +958,10 @@ async def lifespan(app: FastAPI):
         PROXY_ANALYSIS_ONLY_ROUTE,
         PROXY_ANALYSIS_ONLY_MIN_TOOLS,
         PROXY_ANALYSIS_ONLY_MAX_MESSAGES,
+        PROXY_TOOL_CALL_GRAMMAR,
+        PROXY_TOOL_CALL_GRAMMAR_REQUIRED_ONLY,
+        bool(TOOL_CALL_GBNF),
+        PROXY_TOOL_CALL_GRAMMAR_PATH,
     )
 
     yield
@@ -1445,6 +1511,8 @@ def build_openai_request(anthropic_body: dict, monitor: SessionMonitor) -> dict:
                 "Thinking disabled for tool turn (PROXY_DISABLE_THINKING_ON_TOOL_TURNS=on)"
             )
 
+        _apply_tool_call_grammar(openai_body)
+
     return openai_body
 
 
@@ -1848,6 +1916,20 @@ def _sanitize_markup_value(value):
     return value, False
 
 
+_REQUIRED_PLACEHOLDER = "__uap_required__"
+_MISSING_REQUIRED_VALUE = object()
+
+
+def _contains_required_placeholder(value) -> bool:
+    if isinstance(value, str):
+        return value.strip() == _REQUIRED_PLACEHOLDER
+    if isinstance(value, list):
+        return any(_contains_required_placeholder(item) for item in value)
+    if isinstance(value, dict):
+        return any(_contains_required_placeholder(item) for item in value.values())
+    return False
+
+
 def _repair_tool_call_markup(openai_resp: dict) -> tuple[dict, int]:
     if not _openai_has_tool_calls(openai_resp):
         return openai_resp, 0
@@ -1919,33 +2001,30 @@ def _repair_tool_call_markup(openai_resp: dict) -> tuple[dict, int]:
 
 
 def _default_required_value(field_name: str, field_schema: dict):
-    expected_type = field_schema.get("type") if isinstance(field_schema, dict) else None
-    if isinstance(expected_type, list):
-        expected_type = expected_type[0] if expected_type else "string"
+    _ = field_name
+    if not isinstance(field_schema, dict):
+        return _MISSING_REQUIRED_VALUE
+
+    if "default" in field_schema:
+        default_value = copy.deepcopy(field_schema.get("default"))
+        if not _contains_required_placeholder(default_value):
+            return default_value
+
+    enum_values = field_schema.get("enum")
+    if isinstance(enum_values, list):
+        for candidate in enum_values:
+            if _required_value_is_empty(candidate):
+                continue
+            if _contains_required_placeholder(candidate):
+                continue
+            return copy.deepcopy(candidate)
 
-    if expected_type == "integer":
-        return 0
-    if expected_type == "number":
-        return 0
-    if expected_type == "boolean":
-        return False
-    if expected_type == "object":
-        return {"value": "__uap_required__"}
-    if expected_type == "array":
-        return ["__uap_required__"]
-
-    key = (field_name or "").lower()
-    if key in {"command", "cmd"}:
-        return "pwd"
-    if key == "cron":
-        return "* * * * *"
-    if key in {"pattern", "glob"}:
-        return "*"
-    if key == "subject":
-        return "task"
-    if key in {"path", "file", "filepath", "file_path"} or key.endswith("_path"):
-        return "."
-    return "__uap_required__"
+    if "const" in field_schema:
+        const_value = copy.deepcopy(field_schema.get("const"))
+        if not _contains_required_placeholder(const_value):
+            return const_value
+
+    return _MISSING_REQUIRED_VALUE
 
 
 def _repair_required_tool_args(
@@ -2008,7 +2087,10 @@ def _repair_required_tool_args(
                     if isinstance(properties.get(field), dict)
                     else {}
                 )
-                parsed_args[field] = _default_required_value(field, field_schema)
+                fallback_value = _default_required_value(field, field_schema)
+                if fallback_value is _MISSING_REQUIRED_VALUE:
+                    continue
+                parsed_args[field] = fallback_value
                 changed = True
 
         if not changed:
@@ -2231,6 +2313,18 @@ def _validate_tool_call_arguments(
             ),
         )
 
+    if _contains_required_placeholder(parsed):
+        return ToolResponseIssue(
+            kind="invalid_tool_args",
+            reason=(
+                f"arguments for '{tool_name}' contain unresolved placeholder values"
+            ),
+            retry_hint=(
+                f"Emit exactly one `{tool_name}` tool call with real schema-valid arguments. "
+                f"Never emit `{_REQUIRED_PLACEHOLDER}` placeholders."
+            ),
+        )
+
     if not isinstance(tool_schema, dict):
         tool_schema = {}
 
@@ -2245,6 +2339,7 @@ def _validate_tool_call_arguments(
     missing: list[str] = []
     empty: list[str] = []
     wrong_type: list[str] = []
+    enum_mismatch: list[str] = []
 
     for field in required:
         if not isinstance(field, str):
@@ -2267,6 +2362,15 @@ def _validate_tool_call_arguments(
             wrong_type.append(field)
             continue
 
+        enum_values = schema.get("enum")
+        if isinstance(enum_values, list) and enum_values and value not in enum_values:
+            enum_mismatch.append(field)
+            continue
+
+        if "const" in schema and value != schema.get("const"):
+            enum_mismatch.append(field)
+            continue
+
         min_length = schema.get("minLength")
         if (
             isinstance(min_length, int)
@@ -2284,7 +2388,7 @@ def _validate_tool_call_arguments(
         ):
             empty.append(field)
 
-    if missing or empty or wrong_type:
+    if missing or empty or wrong_type or enum_mismatch:
         details = []
         if missing:
             details.append(f"missing: {', '.join(missing)}")
@@ -2292,6 +2396,8 @@ def _validate_tool_call_arguments(
             details.append(f"empty: {', '.join(empty)}")
         if wrong_type:
             details.append(f"type mismatch: {', '.join(wrong_type)}")
+        if enum_mismatch:
+            details.append(f"enum mismatch: {', '.join(enum_mismatch)}")
         required_fields = ", ".join(str(f) for f in required if isinstance(f, str))
         required_hint = (
             f"Required fields must be non-empty: {required_fields}. "
@@ -2485,6 +2591,8 @@ def _build_malformed_retry_body(
     if PROXY_DISABLE_THINKING_ON_TOOL_TURNS:
         retry_body["enable_thinking"] = False
 
+    _apply_tool_call_grammar(retry_body, tool_choice=tool_choice)
+
     if retry_hint:
         repair_prompt = (
             f"[TOOL CALL REPAIR attempt {attempt}/{total_attempts}]\n"
@@ -2571,6 +2679,7 @@ async def _apply_unexpected_end_turn_guardrail(
     retry_body = dict(openai_body)
     retry_body["tool_choice"] = "required"
     retry_body["stream"] = False
+    _apply_tool_call_grammar(retry_body, tool_choice="required")
 
     retry_resp = await client.post(
         f"{LLAMA_CPP_BASE}/chat/completions",
@@ -3737,6 +3846,12 @@ async def context_status(request: Request):
         "overflow_count": monitor.overflow_count,
         "prune_threshold": PROXY_CONTEXT_PRUNE_THRESHOLD,
         "recent_history": monitor.context_history[-10:],
+        "tool_call_grammar": {
+            "enabled": PROXY_TOOL_CALL_GRAMMAR,
+            "required_only": PROXY_TOOL_CALL_GRAMMAR_REQUIRED_ONLY,
+            "path": PROXY_TOOL_CALL_GRAMMAR_PATH,
+            "loaded": bool(TOOL_CALL_GBNF),
+        },
         # Loop protection stats
         "loop_protection": {
             "enabled": PROXY_LOOP_BREAKER,

package/tools/agents/tests/test_anthropic_proxy_streaming.py

@@ -514,6 +514,41 @@ class TestMalformedToolGuardrail(unittest.TestCase):
         self.assertEqual(proxy._retry_tool_choice_for_attempt(True, 2, 3), "auto")
         self.assertEqual(proxy._retry_tool_choice_for_attempt(False, 0, 3), "auto")
 
+    def test_malformed_retry_body_applies_grammar_only_for_required_tool_choice(self):
+        old_enabled = getattr(proxy, "PROXY_TOOL_CALL_GRAMMAR")
+        old_required_only = getattr(proxy, "PROXY_TOOL_CALL_GRAMMAR_REQUIRED_ONLY")
+        old_grammar = getattr(proxy, "TOOL_CALL_GBNF")
+        try:
+            setattr(proxy, "PROXY_TOOL_CALL_GRAMMAR", True)
+            setattr(proxy, "PROXY_TOOL_CALL_GRAMMAR_REQUIRED_ONLY", True)
+            setattr(proxy, "TOOL_CALL_GBNF", 'root ::= "<tool_call>"')
+
+            openai_body = {
+                "model": "test",
+                "messages": [{"role": "user", "content": "fix"}],
+            }
+            anthropic_body = {
+                "tools": [{"name": "Read", "input_schema": {"type": "object"}}]
+            }
+
+            required_retry = proxy._build_malformed_retry_body(
+                openai_body,
+                anthropic_body,
+                tool_choice="required",
+            )
+            auto_retry = proxy._build_malformed_retry_body(
+                openai_body,
+                anthropic_body,
+                tool_choice="auto",
+            )
+
+            self.assertEqual(required_retry.get("grammar"), 'root ::= "<tool_call>"')
+            self.assertNotIn("grammar", auto_retry)
+        finally:
+            setattr(proxy, "PROXY_TOOL_CALL_GRAMMAR", old_enabled)
+            setattr(proxy, "PROXY_TOOL_CALL_GRAMMAR_REQUIRED_ONLY", old_required_only)
+            setattr(proxy, "TOOL_CALL_GBNF", old_grammar)
+
     def test_clean_guardrail_response_does_not_promise_future_tool_call(self):
         guardrail = proxy._build_clean_guardrail_openai_response(
             {"model": "test-model"}
@@ -608,7 +643,11 @@ class TestMalformedToolGuardrail(unittest.TestCase):
                         "type": "object",
                         "required": ["cron", "command"],
                         "properties": {
-                            "cron": {"type": "string", "minLength": 1},
+                            "cron": {
+                                "type": "string",
+                                "minLength": 1,
+                                "default": "* * * * *",
+                            },
                             "command": {"type": "string", "minLength": 1},
                         },
                     },
@@ -921,9 +960,21 @@ class TestMalformedToolGuardrail(unittest.TestCase):
                         "type": "object",
                         "required": ["cron", "pattern", "subject"],
                         "properties": {
-                            "cron": {"type": "string", "minLength": 1},
-                            "pattern": {"type": "string", "minLength": 1},
-                            "subject": {"type": "string", "minLength": 1},
+                            "cron": {
+                                "type": "string",
+                                "minLength": 1,
+                                "default": "* * * * *",
+                            },
+                            "pattern": {
+                                "type": "string",
+                                "minLength": 1,
+                                "default": "*",
+                            },
+                            "subject": {
+                                "type": "string",
+                                "minLength": 1,
+                                "default": "task",
+                            },
                         },
                     },
                 }
@@ -973,9 +1024,21 @@ class TestMalformedToolGuardrail(unittest.TestCase):
                             "type": "object",
                             "required": ["cron", "pattern", "subject"],
                             "properties": {
-                                "cron": {"type": "string", "minLength": 1},
-                                "pattern": {"type": "string", "minLength": 1},
-                                "subject": {"type": "string", "minLength": 1},
+                                "cron": {
+                                    "type": "string",
+                                    "minLength": 1,
+                                    "default": "* * * * *",
+                                },
+                                "pattern": {
+                                    "type": "string",
+                                    "minLength": 1,
+                                    "default": "*",
+                                },
+                                "subject": {
+                                    "type": "string",
+                                    "minLength": 1,
+                                    "default": "task",
+                                },
                             },
                         },
                     }
@@ -1099,10 +1162,7 @@ class TestMalformedToolGuardrail(unittest.TestCase):
             )
             self.assertTrue(args["cron"].strip())
             self.assertTrue(args["command"].strip())
-            self.assertTrue(
-                monitor.arg_preflight_repairs >= 1
-                or monitor.arg_preflight_rejections >= 1
-            )
+            self.assertGreaterEqual(len(fake_client.requests), 1)
             if fake_client.requests:
                 retry_payload = fake_client.requests[0]["kwargs"]["json"]
                 repair_message = retry_payload["messages"][-1]["content"]
@@ -1269,6 +1329,81 @@ class TestToolTurnControls(unittest.TestCase):
             setattr(proxy, "PROXY_FORCED_TOOL_DAMPENER_REJECTIONS", old_rejections)
             setattr(proxy, "PROXY_FORCED_TOOL_DAMPENER_AUTO_TURNS", old_auto_turns)
 
+    def test_build_request_applies_grammar_when_tool_choice_required(self):
+        old_enabled = getattr(proxy, "PROXY_TOOL_CALL_GRAMMAR")
+        old_required_only = getattr(proxy, "PROXY_TOOL_CALL_GRAMMAR_REQUIRED_ONLY")
+        old_grammar = getattr(proxy, "TOOL_CALL_GBNF")
+        try:
+            setattr(proxy, "PROXY_TOOL_CALL_GRAMMAR", True)
+            setattr(proxy, "PROXY_TOOL_CALL_GRAMMAR_REQUIRED_ONLY", True)
+            setattr(proxy, "TOOL_CALL_GBNF", 'root ::= "<tool_call>"')
+
+            body = {
+                "model": "test",
+                "messages": [
+                    {
+                        "role": "assistant",
+                        "content": [{"type": "text", "text": "I will continue."}],
+                    },
+                    {"role": "user", "content": "continue"},
+                ],
+                "tools": [
+                    {
+                        "name": "Read",
+                        "description": "Read file",
+                        "input_schema": {"type": "object"},
+                    }
+                ],
+            }
+
+            openai = proxy.build_openai_request(
+                body, proxy.SessionMonitor(context_window=262144)
+            )
+            self.assertEqual(openai.get("tool_choice"), "required")
+            self.assertEqual(openai.get("grammar"), 'root ::= "<tool_call>"')
+        finally:
+            setattr(proxy, "PROXY_TOOL_CALL_GRAMMAR", old_enabled)
+            setattr(proxy, "PROXY_TOOL_CALL_GRAMMAR_REQUIRED_ONLY", old_required_only)
+            setattr(proxy, "TOOL_CALL_GBNF", old_grammar)
+
+    def test_build_request_omits_grammar_when_tool_choice_released_to_auto(self):
+        old_enabled = getattr(proxy, "PROXY_TOOL_CALL_GRAMMAR")
+        old_required_only = getattr(proxy, "PROXY_TOOL_CALL_GRAMMAR_REQUIRED_ONLY")
+        old_grammar = getattr(proxy, "TOOL_CALL_GBNF")
+        try:
+            setattr(proxy, "PROXY_TOOL_CALL_GRAMMAR", True)
+            setattr(proxy, "PROXY_TOOL_CALL_GRAMMAR_REQUIRED_ONLY", True)
+            setattr(proxy, "TOOL_CALL_GBNF", 'root ::= "<tool_call>"')
+
+            monitor = proxy.SessionMonitor(context_window=262144)
+            monitor.forced_auto_cooldown_turns = 1
+
+            body = {
+                "model": "test",
+                "messages": [
+                    {
+                        "role": "assistant",
+                        "content": [{"type": "text", "text": "I will continue."}],
+                    },
+                    {"role": "user", "content": "continue"},
+                ],
+                "tools": [
+                    {
+                        "name": "Read",
+                        "description": "Read file",
+                        "input_schema": {"type": "object"},
+                    }
+                ],
+            }
+
+            openai = proxy.build_openai_request(body, monitor)
+            self.assertEqual(openai.get("tool_choice"), "auto")
+            self.assertNotIn("grammar", openai)
+        finally:
+            setattr(proxy, "PROXY_TOOL_CALL_GRAMMAR", old_enabled)
+            setattr(proxy, "PROXY_TOOL_CALL_GRAMMAR_REQUIRED_ONLY", old_required_only)
+            setattr(proxy, "TOOL_CALL_GBNF", old_grammar)
+
     def test_no_tools_does_not_inject_agentic_system_message(self):
         body = {
             "model": "test",
@@ -1378,6 +1513,139 @@ class TestToolTurnControls(unittest.TestCase):
             setattr(proxy, "PROXY_ANALYSIS_ONLY_MAX_MESSAGES", old_max_messages)
 
 
+class TestRequiredArgRepair(unittest.TestCase):
+    def test_repair_required_args_uses_schema_enum_value(self):
+        openai_resp = {
+            "choices": [
+                {
+                    "message": {
+                        "tool_calls": [
+                            {
+                                "id": "call_1",
+                                "function": {
+                                    "name": "omp_task",
+                                    "arguments": '{"prompt":"analyze"}',
+                                },
+                            }
+                        ]
+                    }
+                }
+            ]
+        }
+        anthropic_body = {
+            "tools": [
+                {
+                    "name": "omp_task",
+                    "input_schema": {
+                        "type": "object",
+                        "required": ["agent", "prompt"],
+                        "properties": {
+                            "agent": {
+                                "type": "string",
+                                "enum": ["task", "explore", "plan"],
+                            },
+                            "prompt": {"type": "string"},
+                        },
+                    },
+                }
+            ]
+        }
+
+        repaired, repaired_count = proxy._repair_required_tool_args(
+            openai_resp, anthropic_body
+        )
+
+        self.assertEqual(repaired_count, 1)
+        args = json.loads(
+            repaired["choices"][0]["message"]["tool_calls"][0]["function"]["arguments"]
+        )
+        self.assertEqual(args["agent"], "task")
+
+    def test_repair_required_args_does_not_inject_placeholder_without_schema_defaults(
+        self,
+    ):
+        openai_resp = {
+            "choices": [
+                {
+                    "message": {
+                        "tool_calls": [
+                            {
+                                "id": "call_1",
+                                "function": {
+                                    "name": "omp_task",
+                                    "arguments": '{"prompt":"analyze"}',
+                                },
+                            }
+                        ]
+                    }
+                }
+            ]
+        }
+        anthropic_body = {
+            "tools": [
+                {
+                    "name": "omp_task",
+                    "input_schema": {
+                        "type": "object",
+                        "required": ["agent", "prompt"],
+                        "properties": {
+                            "agent": {"type": "string"},
+                            "prompt": {"type": "string"},
+                        },
+                    },
+                }
+            ]
+        }
+
+        repaired, repaired_count = proxy._repair_required_tool_args(
+            openai_resp, anthropic_body
+        )
+
+        self.assertEqual(repaired_count, 0)
+        args = json.loads(
+            repaired["choices"][0]["message"]["tool_calls"][0]["function"]["arguments"]
+        )
+        self.assertNotIn("agent", args)
+
+    def test_validate_tool_args_rejects_placeholder_values(self):
+        issue = proxy._validate_tool_call_arguments(
+            "omp_task",
+            '{"agent":"__uap_required__","prompt":"analyze"}',
+            {
+                "type": "object",
+                "required": ["agent", "prompt"],
+                "properties": {
+                    "agent": {"type": "string", "enum": ["task", "explore"]},
+                    "prompt": {"type": "string"},
+                },
+            },
+            {"omp_task"},
+        )
+
+        self.assertTrue(issue.has_issue())
+        self.assertEqual(issue.kind, "invalid_tool_args")
+        self.assertIn("placeholder", issue.reason)
+
+    def test_validate_tool_args_rejects_enum_mismatch(self):
+        issue = proxy._validate_tool_call_arguments(
+            "omp_task",
+            '{"agent":"planner","prompt":"analyze"}',
+            {
+                "type": "object",
+                "required": ["agent", "prompt"],
+                "properties": {
+                    "agent": {"type": "string", "enum": ["task", "explore"]},
+                    "prompt": {"type": "string"},
+                },
+            },
+            {"omp_task"},
+        )
+
+        self.assertTrue(issue.has_issue())
+        self.assertEqual(issue.kind, "invalid_tool_args")
+        self.assertIn("enum mismatch", issue.reason)
+
+
 class TestSessionContaminationBreaker(unittest.TestCase):
     def test_contamination_breaker_trims_and_resets_streak(self):
         old_enabled = getattr(proxy, "PROXY_SESSION_CONTAMINATION_BREAKER")