coderouter-cli 2.12.0__py3-none-any.whl → 2.14.0__py3-none-any.whl

coderouter/config/schemas.py

@@ -355,15 +355,134 @@ class AgentCliConfig(BaseModel):
         return self
 
 
-# [Unreleased]/planned v2.12.0: patterns used by ProviderConfig's
+# v2.13.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+=")
+# ``restart_command`` values that rely on shell syntax not honored by the
+# ``shlex.split`` + ``shell=False`` dispatch (see that validator's
+# docstring and the field description below for the full rationale).
+# Public (no leading underscore) because ``coderouter.guards.self_healing``
+# imports ``RESTART_COMMAND_SHELL_META_RE`` to *refuse* to run any
+# restart_command containing shell metacharacters — under shell=False a
+# value like ``touch a; b`` would create a file literally named ``a;`` and
+# exit 0, i.e. report a "successful" restart while only half-executing.
+# 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 CredentialRefresh(BaseModel):
+    """How to make a vendor CLI rotate the token it wrote to disk.
+
+    Deliberately not an OAuth client. Every vendor has its own endpoint,
+    client id, rotation policy and error shape, and all of them change —
+    delegating to the CLI that owns the file is the version that survives
+    contact with a moving vendor.
+
+    ``command`` is an argv **list**, dispatched with ``shell=False``. Same
+    trust decision as v2.13.0's ``restart_command``: a string that goes
+    through a shell turns a config file into arbitrary code execution.
+    There is no string form here to have to refuse.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    command: list[str] = Field(
+        ...,
+        min_length=1,
+        description=(
+            "argv for the vendor CLI, e.g. ['grok', 'models']. Run with "
+            "shell=False; no shell metacharacters are interpreted."
+        ),
+    )
+    early_ratio: float = Field(
+        default=0.5,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "Refresh when the remaining lifetime drops below this fraction "
+            "of itself. Early refresh avoids a token dying mid-request."
+        ),
+    )
+    min_lead_s: float = Field(
+        default=300.0,
+        ge=0.0,
+        description="Always refresh at least this many seconds before expiry.",
+    )
+    timeout_s: float = Field(
+        default=30.0,
+        gt=0.0,
+        le=600.0,
+        description="Hard timeout for the refresh command.",
+    )
+
+
+class ProviderCredential(BaseModel):
+    """Where this provider's credential comes from (v2.14.0).
+
+    ``source: env`` is the historical behaviour, spelled out. ``source:
+    cli_session`` borrows the token a vendor CLI already wrote to disk, so
+    a subscription-authenticated provider can be an ordinary
+    ``openai_compat`` entry instead of a ``kind: agent_cli`` island — and
+    therefore takes part in fallback chains, auto-routing, the budget
+    tracker and every other routing feature.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    source: Literal["env", "cli_session"] = Field(
+        default="env",
+        description="'env' reads an environment variable; 'cli_session' reads a JSON file.",
+    )
+    env: str | None = Field(
+        default=None, description="source=env: the environment variable name."
+    )
+    path: str | None = Field(
+        default=None,
+        description=(
+            "source=cli_session: the JSON file the vendor CLI writes, e.g. "
+            "~/.kimi-code/credentials/kimi-code.json. Must live under $HOME."
+        ),
+    )
+    field: str = Field(
+        default="access_token",
+        description="Dotted path to the token inside that JSON (e.g. 'tokens.access').",
+    )
+    expiry_field: str = Field(
+        default="expires_at",
+        description=(
+            "Dotted path to the expiry. Epoch seconds or milliseconds; both "
+            "are accepted. Absent means 'no expiry info' — the upstream 401 "
+            "becomes the signal instead."
+        ),
+    )
+    refresh: CredentialRefresh | None = Field(
+        default=None,
+        description="Omit to never refresh (a long-lived token, or one you rotate yourself).",
+    )
+
+    @model_validator(mode="after")
+    def _check_source_requirements(self) -> Self:
+        """Each source needs its own field, and only its own field."""
+        if self.source == "env":
+            if not self.env:
+                raise ValueError("credential.source='env' requires credential.env")
+            if self.path:
+                raise ValueError("credential.path is meaningless for source='env'")
+        if self.source == "cli_session":
+            if not self.path:
+                raise ValueError(
+                    "credential.source='cli_session' requires credential.path"
+                )
+            if self.env:
+                raise ValueError("credential.env is meaningless for source='cli_session'")
+            from coderouter.credentials import session_path_is_sane
+
+            if not session_path_is_sane(self.path):
+                raise ValueError(
+                    f"credential.path must live under your home directory: {self.path}"
+                )
+        return self
 
 
 class ProviderConfig(BaseModel):
@@ -411,6 +530,19 @@ class ProviderConfig(BaseModel):
         default=None,
         description="Env var name holding the API key. None = no auth (e.g. local).",
     )
+    # v2.14.0: the general form of the above. Mutually exclusive with
+    # api_key_env — a resolver that silently fell back between sources would
+    # make "which credential is this request actually using?" unanswerable,
+    # which is the question an operator asks at exactly the wrong moment.
+    credential: ProviderCredential | None = Field(
+        default=None,
+        description=(
+            "Where the credential comes from. Omit to use api_key_env. "
+            "source='cli_session' reads the token a vendor CLI already wrote "
+            "to disk, so a subscription provider can be a plain "
+            "openai_compat entry that takes part in fallback chains."
+        ),
+    )
 
     # Routing-relevant flags
     paid: bool = Field(
@@ -520,54 +652,56 @@ class ProviderConfig(BaseModel):
             "transitions to UNHEALTHY. Unset = no automatic 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``."
+            "v2.13.0: run as ``subprocess.run(shlex.split(command), "
+            "shell=False)`` (coderouter/guards/self_healing.py) — argv "
+            "dispatch, no shell in between. Pipelines "
+            "(``pkill ollama && ollama serve``), redirects, ``~`` "
+            "expansion, and leading env-var assignments "
+            "(``OLLAMA_HOST=0.0.0.0 ollama serve``) are NOT supported: "
+            "``~/...`` paths are not expanded and ``FOO=bar cmd`` fails to "
+            "exec. A value containing shell metacharacters (``&&``, ``||``, "
+            "``|``, ``;``, ``>``, ``<``, ``$(...)``, ```...```) is refused "
+            "outright (not run) rather than half-executed. If your command "
+            "needs shell features, wrap it in a small script and point "
+            "restart_command at that script (e.g. "
+            "``restart_command: /path/to/restart-ollama.sh``), or write it "
+            "as ``/bin/sh -c '...'`` explicitly."
         ),
     )
 
     @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).
+        """v2.13.0: warn that this ``restart_command`` will not run as written.
+
+        ``coderouter/guards/self_healing.py`` runs ``restart_command`` via
+        ``subprocess.run(shlex.split(command), shell=False)`` — argv
+        dispatch, no shell. A shell-syntax ``restart_command`` therefore
+        does NOT do what the shell would do:
+
+          * shell metacharacters (``&&`` / ``||`` / ``|`` / ``;`` /
+            redirects / ``$(...)`` / backticks) → the value is *refused*
+            (not run) by self_healing, because under shell=False they would
+            otherwise become literal argv tokens and half-execute a
+            provider "restart" that quietly does the wrong thing;
+          * a leading ``~/...`` path or an ``ENV=val cmd`` prefix →
+            ``exec`` fails (``FileNotFoundError``) because there is no shell
+            to expand ``~`` or apply the assignment.
 
         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.
+        anything, it only warns so an existing providers.yaml still loads
+        (rather than becoming un-startable). Migrate ``restart_command`` to
+        a plain argv, a wrapper script, or an explicit ``/bin/sh -c '...'``.
         """
         cmd = self.restart_command
         if not cmd:
             return self
         stripped = cmd.strip()
         reasons: list[str] = []
-        if _RESTART_COMMAND_SHELL_META_RE.search(cmd):
+        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):
+        if RESTART_COMMAND_ENV_PREFIX_RE.match(stripped):
             reasons.append("leading environment-variable assignment (FOO=bar ...)")
         if reasons:
             logger.warning(
@@ -577,13 +711,13 @@ class ProviderConfig(BaseModel):
                     "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."
+                        "restart_command runs via "
+                        "subprocess.run(shlex.split(...), shell=False) as of "
+                        "v2.13.0, which does not support this command's "
+                        "shell syntax: values with shell metacharacters are "
+                        "refused (not run), and '~/' / 'FOO=bar' prefixes "
+                        "fail to exec. Rewrite it as plain argv, wrap it in "
+                        "a script, or use /bin/sh -c '...'."
                     ),
                 },
             )
@@ -604,6 +738,23 @@ class ProviderConfig(BaseModel):
         validate_output_filters(self.output_filters)
         return self
 
+    @model_validator(mode="after")
+    def _check_credential_exclusive(self) -> Self:
+        """``api_key_env`` and ``credential`` cannot both be set.
+
+        Failing at load time is the whole point: two credential sources on
+        one provider is a question ("which one won?") that should never
+        reach a request, let alone a log line an operator has to reverse
+        engineer at 2am.
+        """
+        if self.credential is not None and self.api_key_env:
+            raise ValueError(
+                f"provider {self.name!r}: set either api_key_env or credential, "
+                "not both (credential.source='env' with credential.env=... is "
+                "the spelled-out form of api_key_env)"
+            )
+        return self
+
     @model_validator(mode="after")
     def _check_kind_requirements(self) -> ProviderConfig:
         """Enforce per-``kind`` field requirements (external-agents design §5.2.2).
@@ -1573,6 +1724,28 @@ class LauncherOptionProfile(BaseModel):
     )
 
 
+class LauncherBenchPreset(BaseModel):
+    """launcher.bench.presets[<key>] の1エントリ。H-2: スイープAPIが受け付けるのはキー名だけ。"""
+
+    model_config = ConfigDict(extra="forbid")
+    name: str = Field(..., min_length=1, description="Launcher UI に出す表示名。")
+    command_template: str = Field(
+        ...,
+        min_length=1,
+        description="外部ベンチコマンドのテンプレ。{port} {config} {base_url} {results_dir} {runs} を単純置換で展開。",
+    )
+    runs: int | None = Field(
+        default=None,
+        ge=1,
+        le=1000,
+        description="このプリセット固有の実行回数。None なら launcher.bench.runs。",
+    )
+    results_dir: str | None = Field(
+        default=None,
+        description="このプリセット固有の results ディレクトリ。None なら launcher.bench.results_dir。リクエストからは指定できない。",
+    )
+
+
 class LauncherBenchConfig(BaseModel):
     """The ``launcher.bench:`` block — defaults for the bench sweep feature.
 
@@ -1614,6 +1787,23 @@ class LauncherBenchConfig(BaseModel):
             "大きな GGUF ロードを考慮した既定 5 分。"
         ),
     )
+    presets: dict[str, LauncherBenchPreset] = Field(
+        default_factory=dict,
+        description="名前付きベンチコマンド。キーが POST /api/launcher/sweep/start の bench_preset が取りうる唯一の値。",
+    )
+    default_preset: str | None = Field(
+        default=None,
+        description="bench_preset 未指定時に使うプリセットキー。None なら command_template 由来の暗黙 default。",
+    )
+
+    @model_validator(mode="after")
+    def _check_default_preset(self) -> Self:
+        if self.default_preset is not None and self.default_preset not in self.presets:
+            raise ValueError(
+                f"launcher.bench.default_preset={self.default_preset!r} is not a key of "
+                f"launcher.bench.presets (known: {sorted(self.presets) or 'none'})"
+            )
+        return self
 
 
 class SwapModelSpec(BaseModel):