utim-cli 2.5.3__tar.gz → 2.5.4__tar.gz

{utim_cli-2.5.3/utim_cli.egg-info → utim_cli-2.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: utim-cli
-Version: 2.5.3
+Version: 2.5.4
 Summary: UTIM – Universal Terminal Intelligence Manager. A powerful agentic AI coding assistant for your terminal.
 License: Emend AI Proprietary EULA
 Project-URL: Homepage, https://utim.dev

{utim_cli-2.5.3 → utim_cli-2.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "utim-cli"
-version = "2.5.3"
+version = "2.5.4"
 
 description = "UTIM – Universal Terminal Intelligence Manager. A powerful agentic AI coding assistant for your terminal."
 readme = "README.md"

{utim_cli-2.5.3 → utim_cli-2.5.4}/utim/__init__.py

@@ -14,7 +14,7 @@ Quickstart:
 try:
     from utim_cli._version import VERSION as __version__
 except ImportError:
-    __version__ = "2.5.3"
+    __version__ = "2.5.4"
 
 # Developer-friendly core classes (similar to `import genai` / `import openai`)
 from utim_cli.sdk.session import UtimSession as Session

{utim_cli-2.5.3 → utim_cli-2.5.4}/utim_cli/__init__.py

@@ -5,7 +5,7 @@ try:
     from utim_cli._version import VERSION as __version__
 except ImportError:
     # Fallback during first-install / editable-install edge cases
-    __version__ = "2.5.3"
+    __version__ = "2.5.4"
 
 
 import builtins, os, pathlib, urllib.parse, re

{utim_cli-2.5.3 → utim_cli-2.5.4}/utim_cli/_version.py

@@ -11,6 +11,6 @@
 # from here so every surface stays in sync automatically.
 # ─────────────────────────────────────────────────────────────────────────────
 
-VERSION = "2.5.3"
+VERSION = "2.5.4"
 
 

utim_cli-2.5.4/utim_cli/adaptation_engine.py

@@ -0,0 +1,628 @@
+"""
+UTIM Smart Dynamic Adaptation Engine — provider-agnostic resilience layer.
+
+Goals:
+  1. Auto-detect ANY truncation / breakdown (token-limit, abrupt disconnect,
+     empty-stream, incomplete fence / JSON, unclosed <think>).
+  2. Seamlessly continue the response by stitching chunks — the user sees one
+     coherent answer, never a "Response truncated" banner.
+  3. Stay provider-agnostic: normalises every finish_reason / quirk (Atria
+     omits usage, Anthropic omits finish_reason, upstream 500 empty_stream …)
+     into a single canonical vocabulary.
+  4. Adapt max_tokens dynamically when the same model keeps hitting the cap.
+  5. Work for every model without hardcoded per-model branches.
+
+Usage:
+  engine = AdaptationEngine(console=console, model_id="openai/gpt-4o")
+  signal = engine.analyze(msg, content, tool_calls)
+  if engine.should_continue(signal):
+      bump = engine.adapt_max_tokens(model_id)
+      stitched = engine.stitch(existing_content, new_content)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+# ── Tunables ────────────────────────────────────────────────────────────────
+
+MAX_CONTINUE_ROUNDS = 5          # hard cap to avoid infinite loops
+CONTINUE_COOLDOWN_S = 2.0        # min gap between continue nudges (debounce)
+FENCE_MARKER = "```"
+
+# ── Model health / circuit breaker tunables ────────────────────────────────
+HEALTH_FILE = Path(__file__).resolve().parent.parent / ".utim" / "model_health.json"
+HEALTH_PENALTY_EMPTY_STREAM = 0.35   # transient glitch → moderate penalty
+HEALTH_PENALTY_TRUNCATION = 0.20     # token-limit → light penalty (not the model's fault)
+HEALTH_PENALTY_HARDCAP = 0.50        # 4xx/5xx errors → heavy penalty
+HEALTH_RECOVERY_PER_SUCCESS = 0.15   # success reward
+HEALTH_FLOOR = 0.0
+HEALTH_CEILING = 1.0
+HEALTH_COOLDOWN_S = 120              # circuit-open cooldown before half-open probe
+HEALTH_CIRCUIT_THRESHOLD = 0.25      # below this health → circuit open
+HEALTH_PERSIST_INTERVAL_S = 30.0     # throttle disk writes
+MAX_TOKENS_GROWTH_CAP = 2.0          # never exceed 2× base output budget
+THINK_OPEN_RE = re.compile(r"<think(?:\s[^>]*)?>", re.IGNORECASE)
+THINK_CLOSE_RE = re.compile(r"</think>", re.IGNORECASE)
+
+# Canonical finish reasons — everything maps into this tiny set.
+CANONICAL_STOP = "stop"
+CANONICAL_TOOL = "tool_calls"
+CANONICAL_LENGTH = "length"
+CANONICAL_ABRUPT = "abrupt_disconnect"
+CANONICAL_REPETITION = "repetition_loop"
+
+_ALLOWLIST_FINISH = {CANONICAL_STOP, CANONICAL_TOOL, CANONICAL_LENGTH, CANONICAL_ABRUPT, CANONICAL_REPETITION}
+
+# Matches raw provider finish_reasons and normalises them.
+_FINISH_ALIASES: Dict[str, str] = {
+    "stop": CANONICAL_STOP,
+    "end_turn": CANONICAL_STOP,
+    "stop_sequence": CANONICAL_STOP,
+    "end_of_turn": CANONICAL_STOP,
+    "tool_calls": CANONICAL_TOOL,
+    "function_call": CANONICAL_TOOL,
+    "tool_call": CANONICAL_TOOL,
+    "length": CANONICAL_LENGTH,
+    "max_tokens": CANONICAL_LENGTH,
+    "max_output_tokens": CANONICAL_LENGTH,
+    "repetition_loop": CANONICAL_REPETITION,
+}
+
+
+def _normalize_finish_reason(raw: Optional[str]) -> str:
+    """Map any provider finish_reason string to canonical vocabulary."""
+    if not raw:
+        return ""
+    key = raw.strip().lower()
+    return _FINISH_ALIASES.get(key, key)
+
+
+def _is_transient_empty_stream_error(err_text: str) -> bool:
+    """Return True for transient upstream empty-stream glitches that should be
+    silently retried (never surfaced to the user)."""
+    low = (err_text or "").lower()
+    return any(
+        s in low
+        for s in (
+            "empty_stream",
+            "empty stream",
+            "contentblock",
+            "no content",
+            "upstream returned empty",
+        )
+    ) or any(c in (err_text or "") for c in ("上游", "空流"))
+
+
+def _has_unclosed_fence(text: str) -> bool:
+    if not text:
+        return False
+    # Only count REAL fence markers: lines that (after stripping leading
+    # whitespace) begin with ```. Inline triple-backticks inside prose or
+    # code (e.g. `use ```sql fences``` carefully`) previously inflated the
+    # count and made complete responses look "unclosed", triggering
+    # spurious auto-continue loops.
+    fence_lines = [ln for ln in text.splitlines() if ln.lstrip().startswith(FENCE_MARKER)]
+    # Only odd count implies unclosed.
+    return len(fence_lines) % 2 != 0
+
+
+def _has_unclosed_think(text: str, think_buf: str = "") -> bool:
+    combined = (text or "") + (think_buf or "")
+    opens = len(THINK_OPEN_RE.findall(combined))
+    closes = len(THINK_CLOSE_RE.findall(combined))
+    return opens > closes
+
+
+def _is_truncated_json_args(tool_calls: List[Dict]) -> bool:
+    """Return True if any tool_call has arguments that look like truncated JSON."""
+    for tc in tool_calls or []:
+        fn = tc.get("function") or {}
+        args_s = fn.get("arguments")
+        if not isinstance(args_s, str) or not args_s.strip():
+            continue
+        s = args_s.strip()
+        # Heuristic: starts like JSON but doesn't parse or ends mid-token.
+        if s.startswith("{") or s.startswith("["):
+            try:
+                json.loads(s)
+            except json.JSONDecodeError as exc:
+                # Incomplete JSON — likely truncation.
+                # Unterminated string / unexpected end are strong signals.
+                msg = str(exc).lower()
+                if any(kw in msg for kw in ("unterminated", "expecting", "unexpected end", "invalid")):
+                    return True
+                return True
+    return False
+
+
+def _ends_mid_sentence(text: str) -> bool:
+    """Heuristic: does text end abruptly mid-sentence/word (no terminal punct)?"""
+    if not text or not text.strip():
+        return False
+    stripped = text.rstrip()
+    # If it already ends with terminal punctuation / fence / bracket / markdown
+    # decoration, the response is almost certainly complete.
+    # Extended set: includes *, _, ~, : (list/section endings), / (paths/URLs),
+    # digits (numbered lists, version strings), and emoji-range chars.
+    last_char = stripped[-1]
+    if last_char in ".!?\"'`)}]>\n*_~:/\\":
+        return False
+    # Digit endings (e.g. "step 3", "v2.0", "exit code 0") are complete.
+    if last_char.isdigit():
+        return False
+    # Emoji / non-ASCII endings are almost always intentional.
+    if ord(last_char) > 127:
+        return False
+    last_line = stripped.splitlines()[-1].strip() if stripped.splitlines() else stripped
+    # Short last lines (preambles, labels) are not truncation evidence.
+    if len(last_line) < 12:
+        return False
+    # Text ending inside a properly CLOSED code fence is complete by
+    # definition — code rarely ends with terminal punctuation.
+    if _has_unclosed_fence(stripped):
+        pass  # genuinely unclosed fence → keep mid-sentence check active
+    elif stripped.rstrip().endswith(FENCE_MARKER):
+        return False  # ends with a closing fence line → complete
+    return True
+
+
+# ── Signal ─────────────────────────────────────────────────────────────────
+
+@dataclass
+class TruncationSignal:
+    truncated: bool
+    kind: str = ""               # token_limit | abrupt_disconnect | incomplete_tool_call | incomplete_fence | incomplete_think | empty_stream | none
+    confidence: float = 0.0      # 0–1
+    details: str = ""
+    suggested_action: str = "none"  # continue | retry | fallback | none
+    canonical_finish: str = ""   # normalised finish_reason
+    raw_finish: str = ""
+
+
+# ── Engine ─────────────────────────────────────────────────────────────────
+
+@dataclass
+class AdaptationEngine:
+    """Stateful per-task adaptation engine.  Create one per user turn."""
+
+    console: Any = None
+    max_continue_rounds: int = MAX_CONTINUE_ROUNDS
+    # runtime state
+    continue_rounds: int = 0
+    total_continues_for_task: int = 0
+    last_continue_ts: float = 0.0
+    stitched_content: str = ""
+    stitched_reasoning: str = ""
+    max_tokens_bumps: Dict[str, int] = field(default_factory=dict)
+    history: List[TruncationSignal] = field(default_factory=list)
+    # per-model truncation streak (for adaptive max_tokens)
+    _model_trunc_streak: Dict[str, int] = field(default_factory=dict)
+    # per-model health scores 0..1 (class-level so every engine instance shares)
+    _model_health: Dict[str, float] = field(default_factory=dict)
+    _model_health_lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+    _model_circuit_open_until: Dict[str, float] = field(default_factory=dict)
+    _health_last_persist: float = 0.0
+
+    # ── Model health / circuit breaker ─────────────────────────────────────
+
+    def _load_health(self) -> None:
+        """Load persisted health scores from disk (best-effort)."""
+        with self._model_health_lock:
+            if self._model_health:
+                return
+            try:
+                if HEALTH_FILE.exists():
+                    data = json.loads(HEALTH_FILE.read_text(encoding="utf-8"))
+                    now = time.time()
+                    for mid, entry in (data or {}).items():
+                        try:
+                            score = float(entry.get("score", 1.0))
+                            opened = float(entry.get("circuit_open_until", 0))
+                        except (TypeError, ValueError):
+                            continue
+                        # Clamp into valid range; expired circuits reset
+                        self._model_health[mid] = max(HEALTH_FLOOR, min(HEALTH_CEILING, score))
+                        if opened > now:
+                            self._model_circuit_open_until[mid] = opened
+            except Exception as exc:
+                logger.debug(f"[AdaptationEngine] health load failed: {exc}")
+
+    def _persist_health(self, force: bool = False) -> None:
+        """Throttled disk persistence of health scores (best-effort)."""
+        now = time.time()
+        if not force and (now - self._health_last_persist) < HEALTH_PERSIST_INTERVAL_S:
+            return
+        self._health_last_persist = now
+        try:
+            HEALTH_FILE.parent.mkdir(parents=True, exist_ok=True)
+            with self._model_health_lock:
+                payload = {
+                    mid: {"score": round(score, 3), "circuit_open_until": self._model_circuit_open_until.get(mid, 0)}
+                    for mid, score in self._model_health.items()
+                }
+            HEALTH_FILE.write_text(json.dumps(payload, indent=1), encoding="utf-8")
+        except Exception as exc:
+            logger.debug(f"[AdaptationEngine] health persist failed: {exc}")
+
+    def _adjust_health(self, model_id: str, delta: float) -> None:
+        """Apply a health delta, handle circuit-breaker transitions, persist."""
+        if not model_id:
+            return
+        self._load_health()
+        with self._model_health_lock:
+            cur = self._model_health.get(model_id, 1.0)
+            new = max(HEALTH_FLOOR, min(HEALTH_CEILING, cur + delta))
+            self._model_health[model_id] = new
+            # Open circuit when health degrades past threshold
+            if new < HEALTH_CIRCUIT_THRESHOLD and model_id not in self._model_circuit_open_until:
+                self._model_circuit_open_until[model_id] = time.time() + HEALTH_COOLDOWN_S
+                logger.warning(f"[AdaptationEngine] circuit OPEN for {model_id} (health={new:.2f}) — cooling down {HEALTH_COOLDOWN_S}s")
+        self._persist_health()
+
+    def record_failure(self, model_id: str, kind: str = "error", details: str = "") -> None:
+        """Report a model failure. kind: empty_stream | truncation | error | rate_limit."""
+        penalties = {
+            "empty_stream": HEALTH_PENALTY_EMPTY_STREAM,
+            "truncation": HEALTH_PENALTY_TRUNCATION,
+            "rate_limit": HEALTH_PENALTY_HARDCAP * 0.6,
+            "error": HEALTH_PENALTY_HARDCAP,
+        }
+        self._adjust_health(model_id, -penalties.get(kind, HEALTH_PENALTY_HARDCAP * 0.5))
+        logger.info(f"[AdaptationEngine] failure recorded for {model_id} (kind={kind}) {details}")
+
+    def get_model_health(self, model_id: str) -> float:
+        """Current health score for a model (1.0 = pristine)."""
+        self._load_health()
+        with self._model_health_lock:
+            return self._model_health.get(model_id, 1.0)
+
+    def is_circuit_open(self, model_id: str) -> bool:
+        """True while a model is in circuit-breaker cooldown (skip it in fallback ordering)."""
+        self._load_health()
+        until = self._model_circuit_open_until.get(model_id, 0)
+        if until and time.time() >= until:
+            # Half-open: allow a probe, restore reduced trust
+            with self._model_health_lock:
+                self._model_circuit_open_until.pop(model_id, None)
+                self._model_health[model_id] = max(self._model_health.get(model_id, 0.0), HEALTH_CIRCUIT_THRESHOLD + 0.05)
+            self._persist_health()
+            return False
+        return until > time.time()
+
+    def get_health_ranked_fallbacks(self, candidates: List[str]) -> List[str]:
+        """Order candidate fallback models by health (healthy first), skipping
+        circuit-open models. Stable sort keeps config order as tiebreak."""
+        self._load_health()
+
+        def _key(mid: str) -> Tuple[int, float, int]:
+            open_circuit = 1 if self.is_circuit_open(mid) else 0
+            return (open_circuit, -self.get_model_health(mid), candidates.index(mid))
+
+        return sorted(candidates, key=_key)
+
+    # ── Core analysis (provider-agnostic) ──────────────────────────────────
+
+    def analyze(
+        self,
+        msg: Dict[str, Any],
+        content: str,
+        tool_calls: List[Dict],
+        *,
+        think_buf: str = "",
+    ) -> TruncationSignal:
+        """Inspect a just-received assistant message and decide if it was
+        truncated or broken mid-response.  Provider-agnostic."""
+        raw_fr = msg.get("finish_reason") or ""
+        canon = _normalize_finish_reason(raw_fr)
+        aborted = bool(msg.get("aborted"))
+        was_trunc_flag = bool(msg.get("was_truncated_by_limit"))
+
+        content = content or ""
+        tool_calls = tool_calls or []
+
+        # Snapshot for confidence scoring
+        reasons: List[Tuple[str, float, str]] = []
+
+        # ——— Empty-stream / abrupt disconnect ————————————————
+        if not content.strip() and not tool_calls and not (think_buf or "").strip():
+            if not canon or canon == CANONICAL_LENGTH or canon == CANONICAL_ABRUPT:
+                # Nothing produced at all — provider died mid-flight.
+                reasons.append(("empty_stream", 0.95, f"empty content+tools finish_reason={raw_fr!r}"))
+            elif canon == CANONICAL_STOP:
+                # Clean stop with no content is OK (e.g. immediate tool-call turn
+                # that got parsed elsewhere); don't flag.
+                pass
+
+        # ——— Explicit LENGTH signal (cross-checked vs token budget) ————
+        if canon == CANONICAL_LENGTH or was_trunc_flag:
+            # was_truncated_by_limit already cross-checks completion_tokens vs cap
+            # (including Atria's missing usage). Trust it but keep confidence high.
+            conf = 0.92 if was_trunc_flag else 0.85
+            reasons.append(("token_limit", conf, f"finish_reason={raw_fr!r} was_truncated={was_trunc_flag}"))
+
+        # ——— Incomplete tool-call JSON ————————————————
+        if tool_calls and _is_truncated_json_args(tool_calls):
+            reasons.append(("incomplete_tool_call", 0.90, "tool arguments look like truncated JSON"))
+
+        # ——— Unclosed fence ————————————————
+        # Fire even on CANONICAL_STOP — many providers (OpenRouter, Together,
+        # Groq) send stop even when the model cut off mid-code-block.
+        # We use a slightly lower confidence (0.72) for stop+unclosed vs
+        # non-stop (0.78) to reflect the ambiguity.
+        if content and _has_unclosed_fence(content):
+            conf_fence = 0.72 if canon == CANONICAL_STOP else 0.78
+            reasons.append(("incomplete_fence", conf_fence, f"odd ``` count finish_reason={raw_fr!r}"))
+
+        # ——— Unclosed <think> ————————————————
+        if _has_unclosed_think(content, think_buf):
+            reasons.append(("incomplete_think", 0.80, "unclosed <think> block"))
+
+        # ——— Mid-sentence hard stop ————————————————
+        # Models like Gemini Flash, Llama-3, cheap OpenRouter passthrough
+        # sometimes stop mid-word/sentence and still report finish_reason=stop.
+        # Only flag this on a canonical STOP (not length, not abrupt) because
+        # those are already covered above. Only fire when:
+        #   - finish_reason is a clean stop (not length/abrupt)
+        #   - no tool calls were produced this turn
+        #   - content is substantial (>= 150 chars) — short preambles before
+        #     tool calls look like mid-sentence but are intentionally brief
+        #   - the text genuinely ends mid-word (no terminal punct/markdown)
+        # Confidence raised to 0.75 to avoid false-positive nudges on normal
+        # prose that ends with markdown, emoji, paths, or version strings.
+        if (content and canon == CANONICAL_STOP and not tool_calls
+                and len(content.strip()) >= 150
+                and not aborted
+                and _ends_mid_sentence(content)):
+            reasons.append(("mid_sentence_stop", 0.75, "text ends abruptly mid-sentence with clean stop finish_reason"))
+
+        # ——— Abrupt disconnect (no finish_reason but content present) ———
+        # The transport normalises this: if finish_reason missing and content exists,
+        # it defaults to "stop"; if truly empty it defaults to "length". So a true
+        # abrupt case arrives here as CANONICAL_ABRUPT or empty_stream above.
+        if canon == CANONICAL_ABRUPT:
+            reasons.append(("abrupt_disconnect", 0.88, f"finish_reason={raw_fr!r} normalised to abrupt_disconnect"))
+
+        if not reasons:
+            return TruncationSignal(
+                truncated=False,
+                kind="none",
+                confidence=0.0,
+                details="no truncation signal",
+                suggested_action="none",
+                canonical_finish=canon,
+                raw_finish=raw_fr,
+            )
+
+        # Pick strongest signal
+        reasons.sort(key=lambda x: x[1], reverse=True)
+        kind, conf, det = reasons[0]
+
+        # Decide action
+        if kind in ("empty_stream", "abrupt_disconnect"):
+            action = "retry"  # retry same model once, then fallback
+        elif kind in ("token_limit", "incomplete_tool_call", "incomplete_fence",
+                      "incomplete_think", "mid_sentence_stop"):
+            action = "continue"
+        else:
+            action = "continue"
+
+        sig = TruncationSignal(
+            truncated=True,
+            kind=kind,
+            confidence=conf,
+            details=det,
+            suggested_action=action,
+            canonical_finish=canon,
+            raw_finish=raw_fr,
+        )
+        self.history.append(sig)
+        logger.debug(f"[AdaptationEngine] analyze → {sig}")
+        return sig
+
+    # ── Policy: should we continue? ────────────────────────────────────────
+
+    def should_continue(self, signal: TruncationSignal, *, has_tool_calls: bool = False) -> bool:
+        """Return True if we should auto-continue (inject CONTINUE nudge)."""
+        if not signal.truncated:
+            return False
+        if has_tool_calls:
+            # If the model already emitted real tool calls, the ReAct loop will
+            # handle them; don't inject a spurious CONTINUE that would confuse it.
+            # Except for incomplete_tool_call — there the args are broken so we must continue.
+            if signal.kind != "incomplete_tool_call":
+                return False
+        if self.continue_rounds >= self.max_continue_rounds:
+            logger.warning(f"[AdaptationEngine] max continues ({self.max_continue_rounds}) reached — stopping")
+            return False
+        # Debounce rapid double-continues
+        if time.time() - self.last_continue_ts < CONTINUE_COOLDOWN_S and self.continue_rounds > 0:
+            # Still allow it, just log — provider truncations can be back-to-back
+            pass
+        # Don't continue on empty_stream/abrupt if we already retried fallback path
+        if signal.suggested_action == "retry" and signal.kind == "empty_stream":
+            # Let transport's fallback handle this — orchestrator should NOT inject CONTINUE
+            return False
+        # Per-kind loop protection: heuristic/ambiguous kinds (fence parity,
+        # mid-sentence detection) may fire at most ONCE per task. If the
+        # response still "looks truncated" by the same heuristic after one
+        # nudge, it was almost certainly a false positive — continuing again
+        # just spams the user and can ping-pong the model. Hard-evidence
+        # kinds (token_limit, tool-call JSON, think tags) keep the full
+        # max_continue_rounds budget because genuine long output needs them.
+        _AMBIGUOUS_KINDS = ("incomplete_fence", "mid_sentence_stop")
+        if signal.kind in _AMBIGUOUS_KINDS and self.continue_rounds > 0:
+            logger.info(
+                f"[AdaptationEngine] kind={signal.kind!r} already fired once this task "
+                f"(rounds={self.continue_rounds}) — treating repeat as false positive, not continuing"
+            )
+            return False
+        return signal.suggested_action == "continue"
+
+    def should_retry_or_fallback(self, signal: TruncationSignal) -> bool:
+        return signal.truncated and signal.suggested_action in ("retry", "fallback")
+
+    # ── Continuation helpers ───────────────────────────────────────────────
+
+    def build_continuation_messages(
+        self,
+        content: str,
+        tool_calls: List[Dict],
+        signal: TruncationSignal,
+    ) -> List[Dict]:
+        """Build the two messages to append before re-calling the LLM:
+        [assistant partial] + [user CONTINUE nudge]."""
+        msgs: List[Dict] = []
+        # Preserve the partial assistant turn so the model has exact cutoff context
+        msgs.append({
+            "role": "assistant",
+            "content": content or None,
+            "tool_calls": tool_calls if tool_calls else None,
+        })
+        # Tailored nudge per kind — keeps model from repeating itself
+        if signal.kind == "incomplete_tool_call":
+            nudge = (
+                "Your previous tool-call arguments were cut off mid-JSON (truncated). "
+                "Please re-emit the COMPLETE tool call(s) with full JSON arguments. "
+                "Do not repeat any already-executed calls — just provide the corrected tool calls now."
+            )
+        elif signal.kind == "incomplete_fence":
+            nudge = (
+                "Your previous response ended inside an unclosed code block (``` not closed). "
+                "Please continue EXACTLY where you left off — resume inside the same code block and close it properly. "
+                "Do not restart or repeat the block header."
+            )
+        elif signal.kind == "incomplete_think":
+            nudge = (
+                "Your previous reasoning block (<think>) was not closed. "
+                "Please continue your reasoning and then provide the final answer. Do not repeat earlier reasoning."
+            )
+        else:
+            nudge = (
+                "You were cut off mid-response (output limit reached). "
+                "Please continue EXACTLY where you left off — do not repeat what you already wrote, just resume from the cutoff point and complete the response."
+            )
+        msgs.append({"role": "user", "content": nudge})
+        self.continue_rounds += 1
+        self.total_continues_for_task += 1
+        self.last_continue_ts = time.time()
+        return msgs
+
+    # ── Stitching (multi-chunk merge) ──────────────────────────────────────
+
+    def stitch(self, previous: str, new_chunk: str) -> str:
+        """Merge a continuation chunk onto previous content, fixing common
+        glitches (duplicate headers, double fences, stray CONTINUE echoes)."""
+        if not previous:
+            return new_chunk or ""
+        if not new_chunk:
+            return previous
+        prev = previous.rstrip()
+        chunk = new_chunk.lstrip()
+        # If the model echoed the nudge or repeated the last line, strip dup prefix
+        # Simple heuristic: if first line of chunk == last line of prev, drop it
+        prev_lines = prev.splitlines()
+        chunk_lines = chunk.splitlines()
+        if prev_lines and chunk_lines and prev_lines[-1].strip() == chunk_lines[0].strip() and len(prev_lines[-1].strip()) > 20:
+            chunk = "\n".join(chunk_lines[1:]).lstrip()
+        # Avoid double-closing a fence if prev already closed it and chunk re-opens
+        # (just concatenate with a newline — markdown handles it)
+        return prev + "\n" + chunk
+
+    # ── Adaptive max_tokens ────────────────────────────────────────────────
+
+    def adapt_max_tokens(self, model_id: str, signal: Optional[TruncationSignal] = None) -> Optional[int]:
+        """If this model keeps hitting token_limit, bump its effective
+        max_tokens for the next call. Returns the new cap or None if no bump."""
+        if not model_id:
+            return None
+        if signal and signal.kind != "token_limit":
+            return None
+        try:
+            from .orchestrator_helpers import _get_model_max_output
+
+            base = _get_model_max_output(model_id)
+            # Guard: if registry/config returns bogus 0/negative, use fallback
+            if not base or base <= 0:
+                base = 16_384
+            streak = self._model_trunc_streak.get(model_id, 0) + 1
+            self._model_trunc_streak[model_id] = streak
+
+            # Only bump after 2 consecutive truncations to avoid overshoot
+            if streak < 2:
+                return None
+
+            # Bump by 25% per streak step, capped at 1.5× base and at model's hard max
+            # (the server will clamp anyway, so being generous is safe)
+            bump_factor = min(1.0 + 0.25 * (streak - 1), 1.5)
+            bumped = int(base * bump_factor)
+            # Never exceed MAX_TOKENS_GROWTH_CAP × base (server clamps anyway)
+            bumped = min(bumped, int(base * MAX_TOKENS_GROWTH_CAP), 200_000)
+            if bumped <= base:
+                return None
+            self.max_tokens_bumps[model_id] = bumped
+            logger.info(f"[AdaptationEngine] adaptive max_tokens bump for {model_id}: {base} → {bumped} (streak={streak})")
+            # Subtle console hint — dim so it doesn't alarm the user
+            try:
+                if self.console:
+                    self.console.print(f"[dim]↻ Adapting output budget for this task ({base:,} → {bumped:,} tokens)…[/dim]")
+            except Exception:
+                pass
+            return bumped
+        except Exception as exc:
+            logger.debug(f"[AdaptationEngine] adapt_max_tokens failed: {exc}")
+            return None
+
+    def record_success(self, model_id: str) -> None:
+        """Call after a non-truncated turn to reset the streak and heal health."""
+        self._model_trunc_streak[model_id] = 0
+        # If health is below perfect, recover it a step (positive reinforcement)
+        if self.get_model_health(model_id) < HEALTH_CEILING:
+            self._adjust_health(model_id, HEALTH_RECOVERY_PER_SUCCESS)
+
+    def retry_delay_hint(self, model_id: str, attempt: int, exc: Optional[Exception] = None) -> float:
+        """Exponential backoff hint (seconds) the transport can sleep before
+        retrying the same model. Honours provider Retry-After when present."""
+        # 1) Provider-specified delay wins
+        try:
+            ra_hdr = getattr(getattr(exc, "response", None), "headers", {}).get("Retry-After", "")
+            if ra_hdr:
+                return min(max(float(ra_hdr), 0.5), 120.0)
+        except (TypeError, ValueError, AttributeError):
+            pass
+        # 2) Exponential backoff: 1s, 2s, 4s … capped at 30s, ±20% jitter
+        base = min(2 ** max(attempt, 0), 30.0)
+        import random
+        return base * (0.8 + 0.4 * random.random())
+
+    def on_task_reset(self) -> None:
+        """Call at the start of a new user task."""
+        self.continue_rounds = 0
+        self.stitched_content = ""
+        self.stitched_reasoning = ""
+        self.history.clear()
+
+
+# ── Silent provider-error classifier (for orchestrator_llm_transport) ──────
+
+def is_transient_provider_breakdown(exc: Exception, response_text: str = "") -> bool:
+    """Unified predicate the transport can use to decide 'silently retry next
+    model' vs 'surface to user'."""
+    code = getattr(getattr(exc, "response", None), "status_code", None)
+    text = f"{exc} {response_text}".strip()
+    if code in (500, 502, 520, 521, 522, 523, 524):
+        return True
+    if _is_transient_empty_stream_error(text):
+        return True
+    if "provider returned error" in text.lower():
+        return True
+    return False