coderouter-cli 2.11.0__py3-none-any.whl → 2.11.2__py3-none-any.whl

coderouter/adapters/anthropic_native.py

@@ -53,11 +53,16 @@ from coderouter.translation.anthropic import (
     AnthropicResponse,
     AnthropicStreamEvent,
 )
-from coderouter.translation.convert import (
-    stream_anthropic_to_chat_chunks,
-    to_anthropic_request,
-    to_chat_response,
-)
+
+# NOTE: `coderouter.translation.convert` is intentionally NOT imported here
+# at module scope (see H-7). The import chain is:
+#   translation/__init__.py -> convert.py -> adapters/__init__.py
+#     -> registry.py -> anthropic_native.py -> translation.convert (again)
+# A top-level import here closes that cycle and makes standalone imports of
+# `coderouter.translation.*` fail with a partial-initialization ImportError
+# unless `coderouter.adapters` happened to be imported first. The three
+# symbols used from `convert` are imported lazily inside `generate()` /
+# `stream()` instead, which breaks the cycle without changing behavior.
 
 logger = get_logger(__name__)
 
@@ -210,6 +215,12 @@ class AnthropicAdapter(BaseAdapter):
         ``to_chat_response``. The ``coderouter_provider`` tag is preserved
         on both sides.
         """
+        # Local import to avoid a circular import at module load time (H-7):
+        # convert.py transitively imports coderouter.adapters, which imports
+        # this module. Importing convert.py here (call time, not load time)
+        # keeps `coderouter.translation.*` importable standalone.
+        from coderouter.translation.convert import to_anthropic_request, to_chat_response
+
         anth_req = to_anthropic_request(request)
         anth_resp = await self.generate_anthropic(anth_req, overrides=overrides)
         chat_resp = to_chat_response(anth_resp)
@@ -241,6 +252,13 @@ class AnthropicAdapter(BaseAdapter):
             - Anthropic ``event: error`` → translator raises
               AdapterError(retryable=False), same treatment as above.
         """
+        # Local import to avoid a circular import at module load time (H-7);
+        # see the matching comment in generate() above.
+        from coderouter.translation.convert import (
+            stream_anthropic_to_chat_chunks,
+            to_anthropic_request,
+        )
+
         anth_req = to_anthropic_request(request)
         events = self.stream_anthropic(anth_req, overrides=overrides)
         async for chunk in stream_anthropic_to_chat_chunks(events, provider_name=self.name):

coderouter/cli.py

@@ -624,6 +624,24 @@ def _resolve_config_path(explicit: str | None) -> Path:
     return candidates[-1]
 
 
+def _write_verdict_line(*, write: bool, files_written: int) -> None:
+    """Print the one-line "did we touch the disk?" verdict.
+
+    Called on **every** exit path of :func:`_run_apply_or_dry_run`.
+    The v1.x regression this guards against: an ``--apply`` run that
+    silently rewrote providers.yaml while the summary said "already
+    applied" and printed neither a diff nor a ``Backup:`` line. Making
+    the statement unconditional means no future early-return can go
+    quiet about a write again.
+    """
+    if not write:
+        print("  0 files written (dry-run).")
+    elif files_written == 0:
+        print("  0 files written — no file contents changed.")
+    else:
+        print(f"  {files_written} file(s) written.")
+
+
 def _run_apply_or_dry_run(
     *,
     report: object,
@@ -655,9 +673,13 @@ def _run_apply_or_dry_run(
         )
     except MissingDependencyError as exc:
         print(f"doctor --apply: {exc}", file=sys.stderr)
+        _write_verdict_line(write=write, files_written=0)
         return 1
     except DoctorApplyError as exc:
+        # Every merge happens before the first byte is written, so an
+        # abort here always leaves the disk untouched.
         print(f"doctor --apply: {exc}", file=sys.stderr)
+        _write_verdict_line(write=write, files_written=0)
         return 1
 
     label = "Apply" if write else "Dry-run"
@@ -680,6 +702,8 @@ def _run_apply_or_dry_run(
                 f"  All {result.no_op_patches} patch(es) already applied "
                 f"— providers.yaml is up to date."
             )
+        _write_verdict_line(write=write, files_written=len(result.written_paths))
+        _print_reformat_notice(result, write=write)
         return 0
 
     print(
@@ -694,16 +718,41 @@ def _run_apply_or_dry_run(
         print()
         print(diff, end="" if diff.endswith("\n") else "\n")
 
+    _write_verdict_line(write=write, files_written=len(result.written_paths))
     if write:
         for orig, bak in result.backups.items():
             print(f"  Backup: {orig} → {bak}")
     else:
+        _print_reformat_notice(result, write=write)
         print()
         print("  (dry-run — no files were modified. Re-run with --apply to write.)")
 
     return 0
 
 
+def _print_reformat_notice(result: object, *, write: bool) -> None:
+    """Dry-run-only heads-up about cosmetic re-serialization deltas.
+
+    ``reformat_only`` holds targets whose re-dump differs from disk
+    without any patch having changed a value — today that is explicit
+    ``key: null`` scalars, which ruamel re-emits as empty scalars.
+    These bytes are never written, so the note is purely so an operator
+    comparing "the diff I expected" with "the file I have" is not
+    surprised. Suppressed under ``--apply``, where nothing about them
+    is actionable.
+    """
+    reformat = getattr(result, "reformat_only", None) or {}
+    if write or not reformat:
+        return
+    print(
+        f"  note: {len(reformat)} file(s) would re-serialize with cosmetic "
+        "differences (e.g. explicit `null` → empty scalar). These are NOT "
+        "written — --apply only rewrites files whose values actually changed."
+    )
+    for path in sorted(reformat):
+        print(f"    - {path}")
+
+
 
 
 def _run_audit(args: argparse.Namespace) -> int:

coderouter/config/loader.py

@@ -7,6 +7,17 @@ Search order (first hit wins):
     4. ~/.coderouter/providers.yaml
 
 Secrets are resolved by reading the env var named by `api_key_env`.
+
+.. note::
+    **[Unreleased] deprecation notice (planned v2.12.0):** step 3 above
+    (implicit CWD discovery) is slated to become opt-in, gated behind
+    ``CODEROUTER_ALLOW_CWD_CONFIG``. Landing that change without warning
+    first would silently break anyone currently relying on "run from the
+    directory with providers.yaml in it" with no diagnostic. Until that
+    lands, :func:`load_config` emits a one-time ``cwd-config-loaded``
+    warning whenever step 3 is the one that actually resolved — never
+    when an explicit ``--config`` / ``CODEROUTER_CONFIG`` path was used,
+    even if it happens to point at the same file.
 """
 
 from __future__ import annotations
@@ -17,6 +28,14 @@ from pathlib import Path
 import yaml
 
 from coderouter.config.schemas import CodeRouterConfig
+from coderouter.logging import get_logger
+
+logger = get_logger(__name__)
+
+# Guards the one-time [Unreleased]/v2.12.0 CWD-config deprecation warning
+# (see module docstring) so a process that calls load_config() repeatedly
+# (tests, hot-reload, multiple create_app() calls) only logs it once.
+_cwd_config_warning_emitted = False
 
 
 def _candidate_paths(explicit: str | os.PathLike[str] | None) -> list[Path]:
@@ -30,6 +49,51 @@ def _candidate_paths(explicit: str | os.PathLike[str] | None) -> list[Path]:
     return paths
 
 
+def _warn_if_cwd_config(
+    chosen: Path, *, explicit: str | os.PathLike[str] | None
+) -> None:
+    """Emit the one-time [Unreleased]/v2.12.0 CWD-config deprecation warning.
+
+    Only fires when ``chosen`` was resolved via the *implicit* CWD-search
+    step. Compares ``chosen`` against the *literal* explicit / env
+    candidate paths (not merely whether those inputs were set) so that:
+
+      * an explicit ``--config`` (or ``CODEROUTER_CONFIG``) path that
+        happens to coincide with ``./providers.yaml`` stays quiet — an
+        explicit choice, however coincidental, is not the thing being
+        deprecated; but
+      * an explicit path/env var that was set but did NOT resolve (file
+        missing, so the search fell through to CWD) still warns, because
+        the CWD step is what actually served the config in that case.
+    """
+    global _cwd_config_warning_emitted
+    if _cwd_config_warning_emitted:
+        return
+    cwd_path = Path.cwd() / "providers.yaml"
+    if chosen != cwd_path:
+        return
+    if explicit and Path(explicit) == chosen:
+        return
+    if (env_path := os.environ.get("CODEROUTER_CONFIG")) and Path(env_path) == chosen:
+        return
+
+    _cwd_config_warning_emitted = True
+    logger.warning(
+        "cwd-config-loaded",
+        extra={
+            "path": str(chosen),
+            "hint": (
+                f"loaded providers.yaml from the current working "
+                f"directory ({chosen}). Starting in v2.12.0, this "
+                "implicit CWD discovery becomes opt-in (gated behind "
+                "CODEROUTER_ALLOW_CWD_CONFIG) — pass --config or set "
+                "CODEROUTER_CONFIG to pin the file explicitly and avoid "
+                "a startup break when that lands."
+            ),
+        },
+    )
+
+
 def load_config(path: str | os.PathLike[str] | None = None) -> CodeRouterConfig:
     """Load providers.yaml + apply ALLOW_PAID env override."""
     candidates = _candidate_paths(path)
@@ -40,6 +104,7 @@ def load_config(path: str | os.PathLike[str] | None = None) -> CodeRouterConfig:
             f"providers.yaml not found. Searched:\n  {searched}\n"
             f"Hint: copy examples/providers.yaml to ~/.coderouter/providers.yaml"
         )
+    _warn_if_cwd_config(chosen, explicit=path)
 
     with chosen.open("r", encoding="utf-8") as f:
         raw = yaml.safe_load(f) or {}

coderouter/config/schemas.py

@@ -26,6 +26,10 @@ from pydantic import (
     model_validator,
 )
 
+from coderouter.logging import get_logger
+
+logger = get_logger(__name__)
+
 
 class Capabilities(BaseModel):
     """Capability flags per provider (plan.md §2.5)."""
@@ -350,6 +354,17 @@ class AgentCliConfig(BaseModel):
         return self
 
 
+# [Unreleased]/planned v2.12.0: patterns used by ProviderConfig's
+# ``_warn_restart_command_shell_syntax`` validator to flag
+# ``restart_command`` values that rely on shell syntax not honored by
+# the planned ``shlex.split`` + ``shell=False`` dispatch (see that
+# validator's docstring and the field description below for the full
+# rationale). Compiled once at module scope since every ProviderConfig
+# validation reuses them.
+_RESTART_COMMAND_SHELL_META_RE = re.compile(r"(&&|\|\||\||;|>|<|\$\(|`)")
+_RESTART_COMMAND_ENV_PREFIX_RE = re.compile(r"^\w+=")
+
+
 class ProviderConfig(BaseModel):
     """A single provider entry from providers.yaml.
 
@@ -497,15 +512,82 @@ class ProviderConfig(BaseModel):
     restart_command: str | None = Field(
         default=None,
         description=(
-            "v2.0-J (Self-healing): shell command to restart this "
-            "provider's backend process. Examples: 'ollama serve', "
+            "v2.0-J (Self-healing): command to restart this provider's "
+            "backend process. Examples: 'ollama serve', "
             "'open -a LM\\ Studio'. Only executed when the profile's "
             "backend_health_action is 'exclude' and the provider "
             "transitions to UNHEALTHY. Unset = no automatic restart "
-            "(recovery probe still runs, waiting for manual restart)."
+            "(recovery probe still runs, waiting for manual restart). "
+            "\n\n"
+            "[Unreleased]/planned v2.12.0: currently run as "
+            "``subprocess.run(command, shell=True)`` (coderouter/guards/"
+            "self_healing.py), so shell syntax works today — pipelines "
+            "(``pkill ollama && ollama serve``), ``~`` expansion, and "
+            "leading env-var assignments (``OLLAMA_HOST=0.0.0.0 ollama "
+            "serve``) are all honored. A future minor switches this to "
+            "``shlex.split(command)`` + ``shell=False`` (argv dispatch, "
+            "no shell in between), which does NOT support any of the "
+            "above — ``&&`` becomes a literal argument to the first "
+            "command instead of a separator, ``~/...`` paths are not "
+            "expanded, and ``FOO=bar cmd`` fails to exec. If your "
+            "command needs shell features, wrap it in a small script "
+            "and point restart_command at that script instead, e.g. "
+            "``restart_command: /path/to/restart-ollama.sh``."
         ),
     )
 
+    @model_validator(mode="after")
+    def _warn_restart_command_shell_syntax(self) -> ProviderConfig:
+        """[Unreleased]/planned v2.12.0 breaking-change heads-up (warning only).
+
+        ``coderouter/guards/self_healing.py`` currently runs
+        ``restart_command`` via ``subprocess.run(command, shell=True)``.
+        The planned v2.12.0 change switches that to
+        ``shlex.split(command)`` + ``shell=False`` — a shell-syntax
+        ``restart_command`` that works fine today would then either
+        crash (``FileNotFoundError`` for ``~/...`` paths or an
+        ``ENV=val cmd`` prefix) or, worse, silently misbehave (``&&`` /
+        ``||`` / ``|`` / ``;`` / redirects becoming literal argv tokens
+        instead of shell operators — a provider "restart" that quietly
+        does the wrong thing is worse than one that errors loudly).
+
+        Deliberately never raises: this validator does not enforce
+        anything, it only warns ahead of the wire change so operators
+        can migrate ``restart_command`` to a plain argv (or a wrapper
+        script) before v2.12.0 lands, instead of discovering the break
+        the next time a provider actually goes UNHEALTHY.
+        """
+        cmd = self.restart_command
+        if not cmd:
+            return self
+        stripped = cmd.strip()
+        reasons: list[str] = []
+        if _RESTART_COMMAND_SHELL_META_RE.search(cmd):
+            reasons.append("shell metacharacter (&&, ||, |, ;, >, <, $(...), or `...`)")
+        if stripped.startswith("~/"):
+            reasons.append("leading '~/' path (no shell expansion under shell=False)")
+        if _RESTART_COMMAND_ENV_PREFIX_RE.match(stripped):
+            reasons.append("leading environment-variable assignment (FOO=bar ...)")
+        if reasons:
+            logger.warning(
+                "restart-command-shell-syntax",
+                extra={
+                    "provider": self.name,
+                    "restart_command": cmd,
+                    "reasons": reasons,
+                    "hint": (
+                        "restart_command currently runs via "
+                        "subprocess.run(..., shell=True); a planned "
+                        "v2.12.0 change switches to shlex.split(...) + "
+                        "shell=False, which does not support this "
+                        "command's shell syntax. Rewrite it as plain "
+                        "argv, or wrap it in a script and point "
+                        "restart_command at that script."
+                    ),
+                },
+            )
+        return self
+
     @model_validator(mode="after")
     def _check_output_filters_known(self) -> ProviderConfig:
         """v1.0-A: fail at config-load on a typo'd filter name.

coderouter/doctor.py

@@ -321,17 +321,32 @@ def _patch_model_capabilities_yaml(*, match: str, kind: str, key: str, value: bo
 
 
 def _patch_providers_yaml_output_filters(provider_name: str, filters: list[str]) -> str:
-    """v1.0-A: Emit a providers.yaml patch adding/extending ``output_filters``.
-
-    Lists the filters verbatim so copy-paste yields a valid YAML list.
-    The comment block above the stanza hints that this is additive with
-    any existing filter chain — users with a bespoke chain should merge
-    rather than replace.
+    """v1.0-A: Emit a providers.yaml patch setting the full ``output_filters`` chain.
+
+    ``filters`` must already be the **complete** post-fix chain — the
+    provider's existing filters in their existing order, plus whatever
+    the probe found missing appended at the end. Callers build that
+    union; see :func:`_union_output_filters`.
+
+    Why the complete chain and not just the additions: ``--apply``
+    merges this patch with ``deep_merge_dicts``, which replaces lists
+    wholesale (documented contract, pinned by
+    ``test_deep_merge_replaces_lists_wholesale``). Emitting only the
+    missing filters would therefore *delete* every filter the operator
+    already had — including ``strip_tool_call_xml`` /
+    ``repair_byte_fallback``, which this probe never recommends and so
+    could never add back. Keeping "patch YAML == the desired end state"
+    also means the copy-paste path and the ``--apply`` path agree, and
+    the ``--dry-run`` diff reads as the literal final value.
     """
     items = "\n".join(f"      - {f}" for f in filters)
     return (
         "# providers.yaml — update the entry for "
-        f"{provider_name!r} (merge if a chain already exists):\n"
+        f"{provider_name!r}. This is the COMPLETE chain (existing filters "
+        "plus the additions) —\n"
+        "# it replaces `output_filters` wholesale rather than appending "
+        "to it. Order is significant:\n"
+        "# filters run left to right.\n"
         "providers:\n"
         f"  - name: {provider_name}\n"
         "    # ... existing fields ...\n"
@@ -340,6 +355,27 @@ def _patch_providers_yaml_output_filters(provider_name: str, filters: list[str])
     )
 
 
+def _union_output_filters(existing: list[str], additions: list[str]) -> list[str]:
+    """Existing chain + the filters it is missing, order-preserving.
+
+    ``OutputFilterChain.feed()`` applies filters left to right, so the
+    chain is a pipeline, not a set: reordering it changes the output
+    (e.g. ``strip_thinking`` before vs. after ``strip_tool_call_xml``
+    decides whether a tool call nested inside ``<think>`` survives).
+    Never sort this — the operator's existing order is authoritative and
+    the additions go on the end, which is the only placement that cannot
+    change the behavior of the filters already there.
+
+    Duplicates are dropped so a re-run of the probe cannot grow the
+    chain unboundedly.
+    """
+    chain = list(existing)
+    for name in additions:
+        if name not in chain:
+            chain.append(name)
+    return chain
+
+
 def _patch_providers_yaml_num_ctx(provider_name: str, desired_ctx: int = 32768) -> str:
     """v1.0-B: Emit a providers.yaml patch setting ``extra_body.options.num_ctx``.
 
@@ -470,6 +506,23 @@ _STREAMING_PROBE_MAX_TOKENS_THINKING = 1024
 # probes (same _is_reasoning_model gate).
 _TOOL_CALLS_PROBE_MAX_TOKENS_DEFAULT = 256
 _TOOL_CALLS_PROBE_MAX_TOKENS_THINKING = 1024
+# How much assistant text the tool_calls probe feeds to
+# ``repair_tool_calls_in_text``. This has to be sized against the token
+# budgets above, not against a "preview" length: 1024 tokens is roughly
+# 3-4k characters, and a thinking model routinely spends several hundred
+# of them on a preamble before writing its JSON call. Scanning only the
+# first 200 characters (the pre-fix behavior) made the probe conclude
+# "nothing tool-shaped at all" for a model that had in fact emitted a
+# perfectly repairable call — and the remediation for that verdict is a
+# ``capabilities.tools: false`` patch, i.e. ``--apply`` would have
+# permanently disabled tool calling for a provider that supports it.
+# Bounded rather than unlimited so a pathological multi-megabyte
+# response cannot turn the probe into a CPU sink; 16 KiB comfortably
+# covers the largest response either budget can produce.
+_TOOL_PROBE_SCAN_CHARS = 16384
+# Length of the human-facing excerpt embedded in probe ``detail`` text.
+# Display only — never the input to a verdict.
+_TOOL_PROBE_DETAIL_PREVIEW_CHARS = 200
 # Default ``num_predict`` suggested in the emitted patch. -1 would be
 # optimal (uncapped) but "4096" communicates intent more clearly to
 # operators unfamiliar with Ollama's sentinel value, and covers Claude
@@ -1191,7 +1244,12 @@ async def _probe_tool_calls(
 
     native_tool_call = False
     text_json_tool_call = False
-    content_sample = ""
+    # ``scan_text`` is what the verdict is computed from — the assistant
+    # text up to _TOOL_PROBE_SCAN_CHARS. ``content_preview`` is a short
+    # excerpt used only inside human-readable ``detail`` strings. Keeping
+    # these two separate is the whole point: they used to be one 200-char
+    # string, so the preview length silently became the detection window.
+    scan_text = ""
     if provider.kind == "anthropic":
         blocks = parsed.get("content")
         if isinstance(blocks, list):
@@ -1199,11 +1257,11 @@ async def _probe_tool_calls(
                 if isinstance(block, dict) and block.get("type") == "tool_use":
                     native_tool_call = True
                     break
-            content_sample = " ".join(
+            scan_text = " ".join(
                 str(b.get("text", ""))
                 for b in blocks
                 if isinstance(b, dict) and b.get("type") == "text"
-            )[:200]
+            )[:_TOOL_PROBE_SCAN_CHARS]
     else:
         msg = _extract_openai_assistant_choice(parsed)
         if msg is not None:
@@ -1211,10 +1269,13 @@ async def _probe_tool_calls(
                 native_tool_call = True
             content = msg.get("content")
             if isinstance(content, str):
-                content_sample = content[:200]
+                scan_text = content[:_TOOL_PROBE_SCAN_CHARS]
+
+    content_preview = scan_text[:_TOOL_PROBE_DETAIL_PREVIEW_CHARS]
+    scanned_chars = len(scan_text)
 
-    if not native_tool_call and content_sample:
-        _, repaired = repair_tool_calls_in_text(content_sample, ["echo"])
+    if not native_tool_call and scan_text:
+        _, repaired = repair_tool_calls_in_text(scan_text, ["echo"])
         text_json_tool_call = bool(repaired)
 
     # Resolve the declared support:
@@ -1293,14 +1354,24 @@ async def _probe_tool_calls(
                 "the model produced no tool-shaped output at all."
             )
         )
+        # State the detection window explicitly. This verdict's
+        # remediation permanently disables tool calling, so an operator
+        # who disagrees with it needs to be able to tell "the model
+        # really emitted nothing" from "the probe only looked at the
+        # first N characters" without reading the source.
+        scan_note = (
+            f"Scanned {scanned_chars} chars of assistant text "
+            f"(window {_TOOL_PROBE_SCAN_CHARS})"
+            + (f"; begins: {content_preview!r}." if content_preview else "; text was empty.")
+        )
         return ProbeResult(
             name="tool_calls",
             verdict=ProbeVerdict.NEEDS_TUNING,
             detail=(
                 "declaration says tools=true but model produced neither "
                 "native `tool_calls` nor repairable tool JSON. "
-                f"{budget_note} Common for quantized small models "
-                "(plan.md §9.4 symptom #2)."
+                f"{budget_note} {scan_note} Common for quantized small "
+                "models (plan.md §9.4 symptom #2)."
             ),
             target_file="providers.yaml",
             suggested_patch=_patch_providers_yaml_capability(provider.name, "tools", False),
@@ -1526,7 +1597,10 @@ async def _probe_reasoning_leak(
     content_text = content if isinstance(content, str) else ""
     has_think = "<think>" in content_text
     leaked_markers: list[str] = [m for m in DEFAULT_STOP_MARKERS if m in content_text]
-    configured_filters = set(provider.output_filters)
+    # Order matters (the chain is a left-to-right pipeline), so keep the
+    # operator's list as a list — a set here would lose the order we have
+    # to reproduce in the patch.
+    configured_filters: list[str] = list(provider.output_filters)
     needs_strip_thinking = has_think and "strip_thinking" not in configured_filters
     needs_strip_markers = bool(leaked_markers) and "strip_stop_markers" not in configured_filters
 
@@ -1542,6 +1616,11 @@ async def _probe_reasoning_leak(
         if needs_strip_markers:
             recommended.append("strip_stop_markers")
 
+        # The patch must carry the WHOLE chain: --apply replaces the
+        # list wholesale, so emitting only ``recommended`` would drop
+        # every filter the operator already configured.
+        merged_chain = _union_output_filters(configured_filters, recommended)
+
         found_desc: list[str] = []
         if has_think:
             found_desc.append("<think>...</think>")
@@ -1555,11 +1634,11 @@ async def _probe_reasoning_leak(
                 "content-embedded leak detected ("
                 + " + ".join(found_desc)
                 + "). v1.0-A `output_filters` would scrub this; current "
-                f"provider chain = {sorted(configured_filters)}. Recommended: "
-                f"add {recommended}."
+                f"provider chain = {configured_filters}. Recommended: "
+                f"add {recommended} → resulting chain {merged_chain}."
             ),
             target_file="providers.yaml",
-            suggested_patch=_patch_providers_yaml_output_filters(provider.name, recommended),
+            suggested_patch=_patch_providers_yaml_output_filters(provider.name, merged_chain),
         )
 
     passthrough_on = (