@oneciel-ai/ciel-runtime 0.2.2 → 0.2.4

package/ciel_runtime_support/tool_schema.py

@@ -61,6 +61,13 @@ TASK_UPDATE_STATUS_ALIASES = {
 _TOOL_SCHEMA_REGISTRY: dict[str, dict[str, Any]] = {}
 
 _BUILTIN_TOOL_SCHEMAS: dict[str, dict[str, Any]] = {
+    "shell_command": {
+        "required": ["command"],
+        "properties": {
+            "command": {"type": "string"},
+            "timeout_ms": {"type": "integer"},
+        },
+    },
     "Bash": {
         "required": ["command"],
         "properties": {
@@ -277,6 +284,18 @@ def _coerce_value(value: Any, expected_type: str | None) -> Any:
     return value
 
 
+def _normalize_integral_numbers(value: Any) -> Any:
+    """Keep JSON-schema integer values integral even when a model emits `1.0`."""
+
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    if isinstance(value, list):
+        return [_normalize_integral_numbers(item) for item in value]
+    if isinstance(value, dict):
+        return {key: _normalize_integral_numbers(item) for key, item in value.items()}
+    return value
+
+
 def normalize_task_update_status(value: Any) -> str | None:
     if value is None:
         return None
@@ -337,6 +356,7 @@ def _validate_and_fix_tool_input(
       - add defaults for missing required fields
       - keep unknown fields (Claude Code may accept extra fields)
     """
+    input_dict = _normalize_integral_numbers(input_dict)
     schema = tool_schema_in_body(source_body, tool_name) if isinstance(source_body, dict) else None
     if schema is None:
         schema = _lookup_tool_schema(tool_name)
@@ -453,10 +473,28 @@ def _validate_and_fix_tool_input(
     if injected:
         (log or _noop_log)("WARN", f"tool_guard: {matched_name}: injected missing required fields: {', '.join(injected)}")
 
-    return fixed
+    # A client-provided schema may describe an integer-valued field as the
+    # broader JSON Schema ``number`` type.  Coercion above then creates a
+    # float even when the value is integral, while native clients such as
+    # Codex deserialize timeout fields as u64.  Normalize once more at the
+    # serialization boundary so a repaired 120000 never leaves as 120000.0.
+    return _normalize_integral_numbers(fixed)
 
 
 def _missing_required_tool_fields(tool_name: str, input_dict: dict[str, Any], source_body: dict[str, Any] | None = None) -> list[str]:
+    """Report required fields the caller never supplied.
+
+    JSON Schema ``required`` constrains key *presence*, not emptiness, and an
+    empty value is meaningful for several Claude Code tools: ``Edit`` deletes
+    text with ``new_string: ""`` and ``Write`` creates an empty file with
+    ``content: ""``.  Treating those as missing discards a valid edit.
+
+    Pass the model's own arguments here, not a repaired copy.
+    ``_validate_and_fix_tool_input`` injects a typed empty value for every
+    absent required field, so an emptiness test applied after repair cannot
+    tell an invented value from one the model actually chose.
+    """
+
     schema = tool_schema_in_body(source_body, tool_name) if isinstance(source_body, dict) else None
     if schema is None:
         schema = _lookup_tool_schema(tool_name)
@@ -469,7 +507,7 @@ def _missing_required_tool_fields(tool_name: str, input_dict: dict[str, Any], so
     for field in required:
         if not isinstance(field, str):
             continue
-        if field not in input_dict or _is_empty_value(input_dict.get(field)):
+        if field not in input_dict:
             missing.append(field)
     return missing
 

package/ciel_runtime_support/tool_side_effect_dedupe.py

@@ -12,6 +12,15 @@ from typing import Any, Callable
 class ToolSideEffectDedupePolicy:
     side_effect_suffixes: frozenset[str]
     ttl_seconds: float = 600.0
+    repeated_execution_suffixes: frozenset[str] = frozenset(
+        {"shell_command", "bash", "exec", "execute", "run_command", "write", "edit", "apply_patch"}
+    )
+    # One completed call can legitimately be retried after a client/process
+    # interruption because the resumed request carries no explicit new user
+    # message.  Only stop the call after the same successful result has already
+    # been observed twice consecutively.  This still bounds genuine model loops
+    # without treating a single historical completion as a permanent lock.
+    completed_repeat_limit: int = 2
 
 
 class ToolSideEffectDedupeRepository:
@@ -60,29 +69,125 @@ class ToolSideEffectDedupeService:
         digest = hashlib.sha256(payload.encode("utf-8", errors="replace")).hexdigest()
         return f"{normalized_name}:{digest}"
 
-    def should_drop(self, tool_name: str, tool_input: dict[str, Any], raw_name: str = "") -> bool:
+    @staticmethod
+    def _normalized_payload(value: Any) -> Any:
+        if isinstance(value, float) and value.is_integer():
+            return int(value)
+        if isinstance(value, list):
+            return [ToolSideEffectDedupeService._normalized_payload(item) for item in value]
+        if isinstance(value, dict):
+            return {
+                key: ToolSideEffectDedupeService._normalized_payload(item)
+                for key, item in value.items()
+            }
+        return value
+
+    @classmethod
+    def _signature(cls, tool_name: str, tool_input: Any) -> str:
+        payload = json.dumps(
+            cls._normalized_payload(tool_input if isinstance(tool_input, dict) else {}),
+            sort_keys=True,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            default=str,
+        )
+        return f"{tool_name}:{payload}"
+
+    def completed_repeat_count(
+        self, source_body: dict[str, Any] | None, tool_name: str, tool_input: dict[str, Any]
+    ) -> int:
+        if not isinstance(source_body, dict):
+            return 0
+        tool_leaf = tool_name.rsplit("__", 1)[-1].strip().lower()
+        if tool_leaf not in self.policy.repeated_execution_suffixes:
+            return 0
+        target = self._signature(tool_name, tool_input)
+        tool_uses: dict[str, str] = {}
+        completed: list[str | None] = []
+        for message in source_body.get("messages") or []:
+            if not isinstance(message, dict):
+                continue
+            content = message.get("content")
+            blocks = content if isinstance(content, list) else []
+            if message.get("role") == "assistant":
+                for block in blocks:
+                    if not isinstance(block, dict) or block.get("type") != "tool_use":
+                        continue
+                    tool_id = str(block.get("id") or "")
+                    if tool_id:
+                        tool_uses[tool_id] = self._signature(
+                            str(block.get("name") or ""), block.get("input")
+                        )
+                continue
+            if message.get("role") != "user":
+                continue
+            results = [
+                block
+                for block in blocks
+                if isinstance(block, dict) and block.get("type") == "tool_result"
+            ]
+            has_new_intent = isinstance(content, str) and bool(content.strip())
+            has_new_intent = has_new_intent or any(
+                not isinstance(block, dict) or block.get("type") != "tool_result"
+                for block in blocks
+            )
+            if has_new_intent:
+                completed.clear()
+            for block in results:
+                signature = tool_uses.get(str(block.get("tool_use_id") or ""))
+                completed.append(None if block.get("is_error") else signature)
+        count = 0
+        for signature in reversed(completed):
+            if signature != target:
+                break
+            count += 1
+        return count
+
+    def should_drop(
+        self,
+        tool_name: str,
+        tool_input: dict[str, Any],
+        raw_name: str = "",
+        source_body: dict[str, Any] | None = None,
+    ) -> bool:
         key = self.key(tool_name, tool_input)
-        if not key:
-            return False
-        now = self.ports.now()
-        previous = self.repository.previous_or_record(key, now, self.policy.ttl_seconds)
-        if previous is None:
+        if key:
+            now = self.ports.now()
+            previous = self.repository.previous_or_record(key, now, self.policy.ttl_seconds)
+            if previous is not None:
+                age = now - previous
+                self.ports.audit(
+                    "dropped_duplicate_side_effect_tool_call",
+                    {
+                        "raw_name": raw_name or tool_name,
+                        "matched_name": tool_name,
+                        "emitted_input": tool_input,
+                        "age_seconds": round(age, 3),
+                        "ttl_seconds": self.policy.ttl_seconds,
+                    },
+                )
+                self.ports.log(
+                    "WARN",
+                    f"dropped duplicate side-effect tool call raw_name={raw_name or tool_name!r} "
+                    f"matched_name={tool_name!r} age={age:.1f}s",
+                )
+                return True
+        repeat_count = self.completed_repeat_count(source_body, tool_name, tool_input)
+        if repeat_count < max(1, self.policy.completed_repeat_limit):
             return False
-        age = now - previous
         self.ports.audit(
-            "dropped_duplicate_side_effect_tool_call",
+            "dropped_repeated_completed_tool_call",
             {
                 "raw_name": raw_name or tool_name,
                 "matched_name": tool_name,
                 "emitted_input": tool_input,
-                "age_seconds": round(age, 3),
-                "ttl_seconds": self.policy.ttl_seconds,
+                "completed_repeats": repeat_count,
             },
         )
         self.ports.log(
             "WARN",
-            f"dropped duplicate side-effect tool call raw_name={raw_name or tool_name!r} "
-            f"matched_name={tool_name!r} age={age:.1f}s",
+            f"dropped repeated completed tool call raw_name={raw_name or tool_name!r} "
+            f"matched_name={tool_name!r} completed_repeats={repeat_count}",
         )
         return True
 

package/ciel_runtime_support/upstream_dump.py

@@ -0,0 +1,68 @@
+"""Opt-in capture of the exact bytes sent to an upstream provider.
+
+Set ``CIEL_RUNTIME_DUMP_UPSTREAM`` to a directory to record every upstream
+request body the router is about to send on its provider-wire paths. Each
+request produces two files sharing one stem:
+
+``upstream-<utc>-<seq>-body.json``
+    The request body exactly as encoded for the wire, byte for byte.
+``upstream-<utc>-<seq>-meta.json``
+    Where it was going: URL, byte count, and capture time.
+
+The variable is read per request, capture failures only log, and nothing is
+written when the variable is unset, so the feature is inert in normal runs.
+This exists to diagnose upstream rejections from evidence instead of from
+reconstructions of what the router "should" have sent.
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+DUMP_ENV_VAR = "CIEL_RUNTIME_DUMP_UPSTREAM"
+
+_sequence = itertools.count(1)
+
+
+def upstream_dump_dir(env: Callable[[str], str | None] = os.environ.get) -> Path | None:
+    configured = (env(DUMP_ENV_VAR) or "").strip()
+    return Path(configured) if configured else None
+
+
+def dump_upstream_request(
+    url: str,
+    data: bytes,
+    log: Callable[[str, str], Any],
+    env: Callable[[str], str | None] = os.environ.get,
+) -> Path | None:
+    """Record ``data`` exactly as it will be sent to ``url``; never raise."""
+
+    target = upstream_dump_dir(env)
+    if target is None:
+        return None
+    try:
+        target.mkdir(parents=True, exist_ok=True)
+        stamp = time.strftime("%Y%m%dT%H%M%S", time.gmtime())
+        stem = f"upstream-{stamp}-{next(_sequence):04d}"
+        body_path = target / f"{stem}-body.json"
+        body_path.write_bytes(data)
+        (target / f"{stem}-meta.json").write_text(
+            json.dumps(
+                {"time": stamp, "url": url, "body_bytes": len(data)},
+                ensure_ascii=False,
+            ),
+            encoding="utf-8",
+        )
+        log("INFO", f"upstream_dump wrote {body_path.name} bytes={len(data)} url={url}")
+        return body_path
+    except Exception as exc:
+        log("WARN", f"upstream_dump_failed error={type(exc).__name__}: {exc}")
+        return None
+
+
+__all__ = ["DUMP_ENV_VAR", "dump_upstream_request", "upstream_dump_dir"]

package/ciel_runtime_support/upstream_retry_context.py

@@ -0,0 +1,259 @@
+"""Upstream retry, credential rotation, and rate-limit bounded context."""
+
+from __future__ import annotations
+
+import urllib.error
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .upstream_retry import (
+    UpstreamRetryHttp,
+    UpstreamRetryKeys,
+    UpstreamRetryPolicy,
+    UpstreamRetryRateLimit,
+    UpstreamRetryServices,
+    open_openai_stream_with_rate_retry,
+    open_provider_request_with_key_retry,
+    post_json_with_rate_retry,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class UpstreamRetryErrorPorts:
+    project_http_error: Callable[..., str]
+    project_retry_message: Callable[..., str]
+    first_header: Callable[..., Any]
+    parse_retry_after: Callable[..., Any]
+    format_duration: Callable[..., str]
+
+
+@dataclass(frozen=True, slots=True)
+class UpstreamRetryPolicyPorts:
+    configured_retries: Callable[[dict[str, Any]], int]
+    retry_after_exceeds_timeout: Callable[..., bool]
+    retryable_exception: Callable[[BaseException], bool]
+    retry_wait_seconds: Callable[..., float]
+    retry_http_codes: frozenset[int]
+    language: Callable[[], str]
+
+
+@dataclass(frozen=True, slots=True)
+class UpstreamRetryCredentialPorts:
+    key_from_headers: Callable[..., Any]
+    api_key_count: Callable[..., int]
+    has_live_api_key: Callable[..., bool]
+    headers: Callable[..., dict[str, str]]
+    register_cooldown: Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class UpstreamRetryRateLimitPorts:
+    learn_headers: Callable[..., Any]
+    log: Callable[..., Any]
+    register_backoff: Callable[..., Any]
+    write_activity: Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class UpstreamRetryTransportPorts:
+    estimate_tokens: Callable[..., int]
+    urlopen: Callable[..., Any]
+    set_stream_read_timeout: Callable[..., Any]
+    stream_idle_timeout_seconds: Callable[..., float]
+
+
+@dataclass(frozen=True, slots=True)
+class UpstreamRetryContext:
+    errors: UpstreamRetryErrorPorts
+    policy: UpstreamRetryPolicyPorts
+    credentials: UpstreamRetryCredentialPorts
+    rate_limit: UpstreamRetryRateLimitPorts
+    transport: UpstreamRetryTransportPorts
+
+    def http_error_message(
+        self,
+        exc: urllib.error.HTTPError,
+        raw: str | None = None,
+    ) -> str:
+        return self.errors.project_http_error(
+            exc,
+            raw,
+            first_header=self.errors.first_header,
+            parse_retry_after=self.errors.parse_retry_after,
+            format_duration=self.errors.format_duration,
+        )
+
+    def retry_message(self, attempt: int, total: int) -> str:
+        return self.errors.project_retry_message(
+            self.policy.language(), attempt, total
+        )
+
+    def rate_limit_retry_message(self, attempt: int, total: int) -> str:
+        return self.errors.project_retry_message(
+            self.policy.language(), attempt, total, rate_limit=True
+        )
+
+    def services(self) -> UpstreamRetryServices:
+        return UpstreamRetryServices(
+            policy=UpstreamRetryPolicy(
+                configured_gateway_retries=self.policy.configured_retries,
+                retry_after_exceeds_request_timeout=(
+                    self.policy.retry_after_exceeds_timeout
+                ),
+                retryable_upstream_exception=self.policy.retryable_exception,
+                upstream_rate_limit_retry_message=self.rate_limit_retry_message,
+                upstream_retry_http_codes=self.policy.retry_http_codes,
+                upstream_retry_message=self.retry_message,
+                upstream_retry_wait_seconds=self.policy.retry_wait_seconds,
+            ),
+            keys=UpstreamRetryKeys(
+                key_from_request_headers=self.credentials.key_from_headers,
+                provider_api_key_count=self.credentials.api_key_count,
+                provider_has_live_api_key=self.credentials.has_live_api_key,
+                provider_headers=self.credentials.headers,
+                register_api_key_cooldown=self.credentials.register_cooldown,
+            ),
+            rate_limit=UpstreamRetryRateLimit(
+                learn_headers=self.rate_limit.learn_headers,
+                log=self.rate_limit.log,
+                register_backoff=self.rate_limit.register_backoff,
+                write_activity=self.rate_limit.write_activity,
+            ),
+            http=UpstreamRetryHttp(
+                estimate_tokens=self.transport.estimate_tokens,
+                provider_urlopen=self.transport.urlopen,
+                set_stream_read_timeout=self.transport.set_stream_read_timeout,
+                stream_idle_timeout_seconds=(
+                    self.transport.stream_idle_timeout_seconds
+                ),
+                upstream_http_error_message=self.http_error_message,
+            ),
+        )
+
+    def post_json(
+        self,
+        url: str,
+        req_body: Any,
+        headers: dict[str, str],
+        timeout: float,
+        provider: str,
+        pcfg: dict[str, Any],
+        model: str,
+        retry_notice: Callable[[str], None] | None = None,
+        *,
+        retry_rate_limits: bool = True,
+    ) -> Any:
+        return post_json_with_rate_retry(
+            url,
+            req_body,
+            headers,
+            timeout,
+            provider,
+            pcfg,
+            model,
+            retry_notice,
+            retry_rate_limits=retry_rate_limits,
+            services=self.services(),
+        )
+
+    def open_provider_request(
+        self,
+        url: str,
+        req_body: Any,
+        headers: dict[str, str],
+        timeout: float,
+        provider: str,
+        pcfg: dict[str, Any],
+        model: str,
+        *,
+        stream: bool = False,
+        retry_rate_limits: bool = True,
+    ) -> Any:
+        return open_provider_request_with_key_retry(
+            url,
+            req_body,
+            headers,
+            timeout,
+            provider,
+            pcfg,
+            model,
+            stream=stream,
+            retry_rate_limits=retry_rate_limits,
+            services=self.services(),
+        )
+
+    def open_openai_stream(
+        self,
+        url: str,
+        req_body: Any,
+        headers: dict[str, str],
+        timeout: float,
+        provider: str,
+        pcfg: dict[str, Any],
+        model: str,
+        retry_notice: Callable[[str], None] | None = None,
+        *,
+        retry_rate_limits: bool = True,
+    ) -> Any:
+        return open_openai_stream_with_rate_retry(
+            url,
+            req_body,
+            headers,
+            timeout,
+            provider,
+            pcfg,
+            model,
+            retry_notice,
+            retry_rate_limits=retry_rate_limits,
+            services=self.services(),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class UpstreamRetryCompatibilityApi:
+    context: Callable[[], UpstreamRetryContext]
+
+    def http_error_message(
+        self,
+        exc: urllib.error.HTTPError,
+        raw: str | None = None,
+    ) -> str:
+        return self.context().http_error_message(exc, raw)
+
+    def retry_message(self, attempt: int, total: int) -> str:
+        return self.context().retry_message(attempt, total)
+
+    def rate_limit_retry_message(self, attempt: int, total: int) -> str:
+        return self.context().rate_limit_retry_message(attempt, total)
+
+    def retry_wait_seconds(self, *args: Any, **kwargs: Any) -> float:
+        return self.context().policy.retry_wait_seconds(*args, **kwargs)
+
+    def retryable_exception(self, exc: BaseException) -> bool:
+        return self.context().policy.retryable_exception(exc)
+
+    def configured_retries(self, pcfg: dict[str, Any]) -> int:
+        return self.context().policy.configured_retries(pcfg)
+
+    def services(self) -> UpstreamRetryServices:
+        return self.context().services()
+
+    def post_json(self, *args: Any, **kwargs: Any) -> Any:
+        return self.context().post_json(*args, **kwargs)
+
+    def open_provider_request(self, *args: Any, **kwargs: Any) -> Any:
+        return self.context().open_provider_request(*args, **kwargs)
+
+    def open_openai_stream(self, *args: Any, **kwargs: Any) -> Any:
+        return self.context().open_openai_stream(*args, **kwargs)
+
+
+__all__ = [
+    "UpstreamRetryCompatibilityApi",
+    "UpstreamRetryContext",
+    "UpstreamRetryCredentialPorts",
+    "UpstreamRetryErrorPorts",
+    "UpstreamRetryPolicyPorts",
+    "UpstreamRetryRateLimitPorts",
+    "UpstreamRetryTransportPorts",
+]