@caddis/cli 0.2.6 → 0.4.0

package/bundles/antigravity-plugin/scripts/hook_log.py

@@ -0,0 +1,156 @@
+"""Throttled error ledger for caddis hooks — so a broken hook is not a silent one.
+
+The problem
+-----------
+caddis hooks fail open, which is right: a SessionStart hook that raises would break
+the session, and a PreToolUse hook that raises would break the tool call. The way
+they fail open is ``except Exception: pass``, which is wrong: a hook that is broken
+and a hook that had nothing to say produce the identical result — nothing.
+
+There were 20 such swallows across 6 hook files. Each one guards a named feature.
+When the tidy nudge stops printing, nobody learns that it stopped; they
+learn that they have not seen it lately, months later, if at all.
+
+The fix keeps fail-open and adds a record. ``record()`` never raises, never prints,
+and never blocks — if the ledger itself cannot be written, that is swallowed too.
+
+Throttle
+--------
+One line per ``(hook, feature, error type)`` per day. A hook that fails on every
+single tool call writes one line, not thousands. The ledger is a signal, not a trace.
+
+Surfacing
+---------
+``summarise()`` returns a one-line summary of the last N days, or "" when clean.
+``inject_relay.py`` prints it at SessionStart. That is the only place a user is
+told; there is no second channel to ignore.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+
+_ARTIFACT_DIR = ".caddis"
+_LEDGER_NAME = "hook-errors.jsonl"
+_MAX_LINES = 400  # ring-buffer cap; the ledger must never grow without bound
+
+
+def _ledger_path(root: str | None) -> str | None:
+    try:
+        base = root or os.getcwd()
+        d = os.path.join(base, _ARTIFACT_DIR)
+        if not os.path.isdir(d):
+            return None  # not a caddis project — nothing to write into, and that is fine
+        return os.path.join(d, _LEDGER_NAME)
+    except Exception:
+        return None
+
+
+def record(hook: str, feature: str, exc: BaseException, root: str | None = None) -> None:
+    """Note that ``feature`` inside ``hook`` failed. Never raises, never prints.
+
+    ``feature`` is the thing the user loses — "parked-stack surface", "relay read" —
+    not the function name. The ledger is read by a human deciding whether to care.
+    """
+    try:
+        path = _ledger_path(root)
+        if path is None:
+            return
+
+        etype = type(exc).__name__
+        # Truncate: an exception message can carry a path, a command, or a chunk of
+        # file content. One line of context is enough to act on.
+        emsg = str(exc)[:200]
+        today = time.strftime("%Y-%m-%d")
+        key = f"{hook}|{feature}|{etype}"
+
+        lines: list[str] = []
+        if os.path.isfile(path):
+            try:
+                with open(path, "r", encoding="utf-8", errors="replace") as fh:
+                    lines = fh.read().splitlines()
+            except Exception:
+                lines = []
+
+        for line in reversed(lines[-120:]):  # today's entries are at the tail
+            try:
+                rec = json.loads(line)
+            except Exception:
+                continue
+            if rec.get("key") == key and str(rec.get("ts", ""))[:10] == today:
+                return  # already recorded today — throttled
+
+        lines.append(json.dumps({
+            "ts": time.strftime("%Y-%m-%dT%H:%M:%S"),
+            "key": key,
+            "hook": hook,
+            "feature": feature,
+            "error": etype,
+            "message": emsg,
+        }, ensure_ascii=False))
+
+        with open(path, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write("\n".join(lines[-_MAX_LINES:]) + "\n")
+    except Exception:
+        return  # the ledger must never be the thing that breaks a hook
+
+
+def summarise(root: str | None = None, days: int = 7) -> str:
+    """One line naming what has been failing, or "" when there is nothing to say."""
+    try:
+        path = _ledger_path(root)
+        if path is None or not os.path.isfile(path):
+            return ""
+
+        cutoff = time.strftime("%Y-%m-%d", time.localtime(time.time() - days * 86400))
+        counts: dict[str, int] = {}
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    rec = json.loads(line)
+                except Exception:
+                    continue
+                if str(rec.get("ts", ""))[:10] < cutoff:
+                    continue
+                label = f"{rec.get('hook', '?')}/{rec.get('feature', '?')}"
+                counts[label] = counts.get(label, 0) + 1
+
+        if not counts:
+            return ""
+        ranked = sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))
+        shown = ", ".join(f"{k} x{v}" for k, v in ranked[:4])
+        more = f" (+{len(ranked) - 4} more)" if len(ranked) > 4 else ""
+        return (f"[caddis] hook errors in the last {days} days: {shown}{more} — "
+                f"see {_ARTIFACT_DIR}/{_LEDGER_NAME}")
+    except Exception:
+        return ""
+
+
+def main() -> int:
+    """``python hook_log.py [root]`` prints the ledger, newest last. For eyeballing."""
+    import sys
+    root = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
+    path = _ledger_path(root)
+    if path is None or not os.path.isfile(path):
+        print(f"no hook-error ledger at {root}/{_ARTIFACT_DIR}/{_LEDGER_NAME} — nothing has failed")
+        return 0
+    with open(path, "r", encoding="utf-8", errors="replace") as fh:
+        for line in fh:
+            try:
+                rec = json.loads(line)
+            except Exception:
+                continue
+            print(f"{rec.get('ts', '?'):<20} {rec.get('hook', '?')}/{rec.get('feature', '?'):<28} "
+                  f"{rec.get('error', '?')}: {rec.get('message', '')}")
+    summary = summarise(root)
+    if summary:
+        print("\n" + summary)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundles/antigravity-plugin/scripts/new-machine.ps1

@@ -0,0 +1,170 @@
+<#
+.SYNOPSIS
+  Set up a new Windows machine with the caddis toolchain, in the right order.
+
+.DESCRIPTION
+  The ORDER matters, and it is the only thing this script really encodes:
+
+    1. Agents first.  caddis is a META-installer — `caddis init` detects which agents are
+       present and installs into each. An agent installed AFTER it is simply not seen,
+       and you get a silent no-op rather than an error.
+
+       Note the rule is about `caddis init`, NOT about installing the CLI. The npm package
+       has no postinstall step; it only puts binaries on PATH. Installing it early is safe.
+    2. caddis CLI second, which brings the model-lane binaries with it.
+    3. Keys and status line last. Both depend on the CLI being on PATH.
+
+  Fetch this script on a machine that has no caddis yet (the SOURCE repo is private; the
+  public mirror is what a new machine can reach):
+
+    irm https://raw.githubusercontent.com/saajunaid/caddis-plugin/main/plugin/scripts/new-machine.ps1 -OutFile $env:TEMP
+ew-machine.ps1
+
+  Everything is idempotent: re-running skips what is already correct.
+
+  This script NEVER installs an agent for you. Each vendor's installer is theirs, changes
+  without notice, and may need an interactive login. It checks, reports, and tells you the
+  one command to run — then verifies afterwards.
+
+.PARAMETER SkipKeys
+  Do not run `caddis keys` (which prompts). Use on a machine that only needs Claude.
+
+.PARAMETER WhatIf
+  Report what would happen; change nothing.
+
+.EXAMPLE
+  .\new-machine.ps1
+  .\new-machine.ps1 -SkipKeys
+#>
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [switch]$SkipKeys
+)
+
+$ErrorActionPreference = 'Stop'
+$script:Problems = @()
+
+function Step($n, $text) { Write-Host "`n[$n] $text" -ForegroundColor Cyan }
+function Ok($text)       { Write-Host "   OK    $text" -ForegroundColor Green }
+function Missing($text)  { Write-Host "   TODO  $text" -ForegroundColor Yellow }
+function Bad($text)      { Write-Host "   FAIL  $text" -ForegroundColor Red; $script:Problems += $text }
+function Note($text)     { Write-Host "         $text" -ForegroundColor DarkGray }
+
+function Test-Bin($name) { $null -ne (Get-Command $name -ErrorAction SilentlyContinue) }
+
+# ── 0. prerequisites ────────────────────────────────────────────────────────────────────
+Step 0 'Prerequisites'
+
+foreach ($p in @(
+    @{ bin = 'node';   why = 'runs the caddis CLI and every agent installer'; get = 'winget install OpenJS.NodeJS.LTS' },
+    @{ bin = 'python'; why = 'runs the caddis hooks and the status line';     get = 'winget install Python.Python.3.12' },
+    @{ bin = 'git';    why = 'the status line and most commands read git state'; get = 'winget install Git.Git' }
+)) {
+    if (Test-Bin $p.bin) { Ok "$($p.bin) — $($p.why)" }
+    else { Bad "$($p.bin) is missing — $($p.why).  Install: $($p.get)" }
+}
+
+if ($script:Problems.Count -gt 0) {
+    Write-Host "`nStopping: the prerequisites above are required before anything else works." -ForegroundColor Red
+    exit 1
+}
+
+# ── 1. the agents — BEFORE caddis, or caddis cannot see them ────────────────────────────
+Step 1 'Agents (install these BEFORE caddis)'
+Note 'caddis installs INTO an agent. One added later needs a re-run of `caddis init`.'
+
+$agents = @(
+    @{ bin = 'claude'; name = 'Claude Code'; get = 'npm i -g @anthropic-ai/claude-code'; login = 'claude  (log in on first run)' },
+    @{ bin = 'agy';    name = 'Antigravity (agy)'; get = 'download from antigravity.google'; login = 'agy  (log in on first run)' },
+    @{ bin = 'codex';  name = 'Codex';       get = 'npm i -g @openai/codex'; login = 'codex login   (INTERACTIVE — a script cannot do this)' }
+)
+
+$present = @()
+foreach ($a in $agents) {
+    if (Test-Bin $a.bin) {
+        $ver = (& $a.bin --version 2>&1 | Select-Object -First 1)
+        Ok "$($a.name) — $ver"
+        $present += $a.name
+    } else {
+        Missing "$($a.name) not found.  Install: $($a.get)"
+        Note "then: $($a.login)"
+    }
+}
+
+if ($present.Count -eq 0) {
+    Write-Host "`nStopping: no agents found, so caddis would install into nothing." -ForegroundColor Red
+    exit 1
+}
+
+# ── 2. caddis CLI ───────────────────────────────────────────────────────────────────────
+Step 2 'caddis CLI'
+Note 'Brings claude-oss / claude-glm / claude-deepseek onto PATH as well — no profile edit.'
+
+if (Test-Bin 'caddis') {
+    Ok "caddis CLI present — $(caddis --version 2>&1 | Select-Object -First 1)"
+} elseif ($PSCmdlet.ShouldProcess('npm', 'install -g @caddis/cli')) {
+    npm i -g '@caddis/cli'
+    if (Test-Bin 'caddis') { Ok 'caddis CLI installed' } else { Bad 'npm reported success but `caddis` is not on PATH — open a new shell and re-run' ; exit 1 }
+}
+
+# ── 3. drive each agent ─────────────────────────────────────────────────────────────────
+Step 3 'Install caddis into every detected agent'
+if ($PSCmdlet.ShouldProcess('agents', 'caddis init')) {
+    caddis init
+}
+
+# ── 4. provider keys ────────────────────────────────────────────────────────────────────
+Step 4 'Provider API keys (GLM / DeepSeek)'
+if ($SkipKeys) {
+    Note 'Skipped (-SkipKeys). Run `caddis keys` later to enable the OSS model lanes.'
+} elseif ($PSCmdlet.ShouldProcess('~/.caddis/keys.env', 'caddis keys')) {
+    Note 'Prompts per provider, validates against the live endpoint, never prints a key.'
+    caddis keys
+}
+
+# ── 5. status line ──────────────────────────────────────────────────────────────────────
+Step 5 'Status line (Claude Code + agy, user scope, once per machine)'
+$statusline = Join-Path $HOME '.caddis\statusline.py'
+if (Test-Path $statusline) {
+    if ($PSCmdlet.ShouldProcess($statusline, 'install')) { python $statusline --install }
+} else {
+    Missing "statusline.py not found at $statusline"
+    Note 'It ships with the plugin. Run `/caddis:statusline` in a Claude Code session, or'
+    Note 'python PLUGIN_ROOT/scripts/caddis_statusline.py --install'
+}
+
+# ── 6. verify ───────────────────────────────────────────────────────────────────────────
+Step 6 'Verify'
+
+caddis status
+
+if (Test-Path $statusline) {
+    python $statusline --check
+}
+
+if (-not $SkipKeys -and (Test-Bin 'caddis')) {
+    Note 'Validating keys against the live endpoints...'
+    caddis keys --check
+}
+
+Write-Host "`n-- Per repo, not per machine --" -ForegroundColor Cyan
+Note 'In each project, once:   /caddis:setup-project-ai'
+Note 'The status line is deliberately NOT per-repo — one renderer serves every project.'
+
+Write-Host "`n-- Known gotchas on this platform --" -ForegroundColor Cyan
+Note 'codex headless: pass -c model_reasoning_effort=low. The default `high` can exceed 300s'
+Note '                on a trivial call.'
+Note '`codex doctor` is NOT an auth check — it validates the auth FILE, not the token, and'
+Note '                reports healthy against a dead one. Real check:'
+Note '                codex exec --skip-git-repo-check -s read-only "Reply OK"'
+Note 'agy statusLine is NOT parsed through a shell, so its path must be UNQUOTED. --install'
+Note '                handles this; if you wire it by hand, do not add quotes.'
+Note 'Codex has NO status line and cannot have one — no status_line key in config.toml and'
+Note '                nothing in `codex --help` (measured on codex-cli 0.150.1). Upstream limit,'
+Note '                not a caddis gap. Two profiles exist because two hosts can call them.'
+
+if ($script:Problems.Count -gt 0) {
+    Write-Host "`n$($script:Problems.Count) problem(s) above." -ForegroundColor Red
+    exit 1
+}
+Write-Host "`nDone." -ForegroundColor Green

package/bundles/antigravity-plugin/scripts/oss_ask.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""One-shot question to an OSS provider (DeepSeek/GLM/OpenRouter) — plain chat, no tools.
+
+Backs the /ask-glm and /ask-deepseek commands: a fast second-opinion answer from a
+different model family, without spinning up a full Claude Code session. Speaks the
+providers' OpenAI-compatible ``/chat/completions`` dialect (NOT the Anthropic endpoints
+oss_model.py hands to Claude Code), and reuses oss_model's key resolution so one entry
+in ~/.caddis/keys.env lights up every lane.
+
+Usage:
+  python oss_ask.py <provider> <prompt...>  [--model M] [--base-url U] [--system S]
+
+Exit codes: 0 answer printed; 2 endpoint/parse error; 3 config error (message on stderr).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import oss_model  # noqa: E402  (same-directory import: shared key resolution)
+
+# OpenAI-compatible chat endpoints — intentionally different from oss_model.PROVIDERS,
+# which holds the Anthropic-protocol endpoints for Claude Code.
+CHAT_PROVIDERS: dict[str, dict[str, str]] = {
+    "deepseek":   {"base_url": "https://api.deepseek.com",            "model": "deepseek-v4-flash",          "key_env": "DEEPSEEK_API_KEY"},
+    "glm":        {"base_url": "https://api.z.ai/api/coding/paas/v4", "model": "glm-5.3",                    "key_env": "GLM_API_KEY"},
+    "openrouter": {"base_url": "https://openrouter.ai/api/v1",        "model": "deepseek/deepseek-v4-flash", "key_env": "OPENROUTER_API_KEY"},
+}
+
+EXIT_OK = 0
+EXIT_ERROR = 2
+EXIT_CONFIG = 3
+
+
+def resolve_chat_config(provider: str, env: dict[str, str],
+                        model: str | None = None, base_url: str | None = None) -> dict[str, str]:
+    """{base_url, model, api_key} for the chat lane. Flag > preset; key via oss_model."""
+    preset = CHAT_PROVIDERS.get(provider.strip().lower(), {})
+    resolved_base = (base_url or preset.get("base_url") or "").rstrip("/")
+    resolved_model = model or preset.get("model") or ""
+    if not resolved_base or not resolved_model:
+        known = ", ".join(sorted(CHAT_PROVIDERS))
+        raise oss_model.ConfigError(
+            f"unknown provider {provider!r}: pass --base-url and --model, or use one of: {known}."
+        )
+    key_env = preset.get("key_env") or f"{provider.upper()}_API_KEY"
+    api_key = oss_model._resolve_key(provider, key_env, env)
+    return {"base_url": resolved_base, "model": resolved_model, "api_key": api_key}
+
+
+def ask(cfg: dict[str, str], prompt: str, system: str | None = None, timeout: int = 120) -> str:
+    """POST the prompt to {base_url}/chat/completions and return the reply text."""
+    messages = ([{"role": "system", "content": system}] if system else []) + [
+        {"role": "user", "content": prompt}
+    ]
+    body = json.dumps({"model": cfg["model"], "messages": messages}).encode("utf-8")
+    req = urllib.request.Request(
+        f"{cfg['base_url']}/chat/completions",
+        data=body,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {cfg['api_key']}",
+        },
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        payload = json.loads(resp.read().decode("utf-8"))
+    return payload["choices"][0]["message"]["content"]
+
+
+def main(argv: list[str], env: dict[str, str] | None = None) -> int:
+    env = dict(oss_model.os.environ) if env is None else env
+    ap = argparse.ArgumentParser(description="One-shot question to an OSS provider (no tools).")
+    ap.add_argument("provider", help="deepseek | glm | openrouter (or custom with --base-url/--model)")
+    ap.add_argument("prompt", nargs="+", help="the question")
+    ap.add_argument("--model", default=None)
+    ap.add_argument("--base-url", default=None)
+    ap.add_argument("--system", default=None)
+    args = ap.parse_args(argv)
+    try:
+        cfg = resolve_chat_config(args.provider, env, model=args.model, base_url=args.base_url)
+    except oss_model.ConfigError as exc:
+        print(str(exc), file=sys.stderr)
+        return EXIT_CONFIG
+    try:
+        print(ask(cfg, " ".join(args.prompt), system=args.system))
+    except (urllib.error.URLError, KeyError, IndexError, json.JSONDecodeError, TimeoutError) as exc:
+        print(f"oss_ask: endpoint/parse failure: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    return EXIT_OK
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/bundles/antigravity-plugin/scripts/oss_model.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""Shared provider + key resolver for the model-switching launchers (Track A).
+
+`claude-oss` / `claude-glm` point a Claude Code session at an OpenAI-compatible
+endpoint (GLM, DeepSeek, OpenRouter, or any custom base_url) by setting the
+``ANTHROPIC_*`` env vars. This module owns the ONE place that maps a provider name
+to its endpoint + default model, and resolves the API key WITHOUT ever hardcoding a
+path or a secret.
+
+Key resolution precedence (highest wins):
+  1. the provider's explicit env var (GLM_API_KEY / DEEPSEEK_API_KEY / OPENROUTER_API_KEY),
+     or the generic OSS_API_KEY;
+  2. a keys file at CADDIS_KEYS_FILE (default ~/.caddis/keys.env), INI/KEY=VALUE style,
+     comments (#) and blank lines allowed;
+  3. ConfigError with an actionable message.
+
+Endpoint/model precedence: OSS_BASE_URL / OSS_MODEL env override > the provider preset.
+An unknown provider is fine as long as OSS_BASE_URL + OSS_MODEL are supplied.
+
+The PROVIDERS table mirrors oss_review.py so a renamed model id / moved endpoint is a
+one-line edit in each. (oss_review may import this later; not refactored here to keep
+the diff small.)
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# Provider presets — the SINGLE place a renamed model id / moved endpoint is edited.
+# These are the providers' ANTHROPIC-protocol endpoints: this table feeds
+# ANTHROPIC_BASE_URL for Claude Code, which speaks the Anthropic Messages API — NOT the
+# OpenAI /chat/completions dialect that oss_review.py uses (its table differs on purpose).
+# "openrouter" has no Anthropic-protocol endpoint: it only works through an
+# Anthropic-compatible gateway (e.g. LiteLLM — see claude-harness/LOCAL-MODELS.md) whose
+# URL you supply via OSS_BASE_URL.
+# The `[1m]` suffix on a model id is a CLAUDE CODE convention, not part of the model name.
+# Claude Code strips it before calling the API; it only tells the client the real context
+# window. Without it, an id Claude Code does not recognise is assumed to be 200k and
+# auto-compact throws away context the model could still hold. Both providers are 1M
+# (GLM-5.3: docs.z.ai; DeepSeek V4 Flash: 1,048,576 positions) — verified 2026-08-23 by
+# running with and without the suffix and diffing the cap warning.
+# NEVER put this suffix in the OpenAI-dialect tables (oss_review.py / oss_ask.py): those
+# send the id raw to /chat/completions, which would reject it.
+PROVIDERS: dict[str, dict[str, str]] = {
+    "deepseek":   {"base_url": "https://api.deepseek.com/anthropic",  "model": "deepseek-v4-flash[1m]",          "key_env": "DEEPSEEK_API_KEY"},
+    "glm":        {"base_url": "https://api.z.ai/api/anthropic",      "model": "glm-5.3[1m]",                    "key_env": "GLM_API_KEY"},
+    "openrouter": {"base_url": "",                                    "model": "deepseek/deepseek-v4-flash", "key_env": "OPENROUTER_API_KEY"},
+}
+DEFAULT_PROVIDER = "deepseek"
+DEFAULT_KEYS_FILE = "~/.caddis/keys.env"
+
+# Env-var naming derives from the shared prefix constant, so a future rename is one edit there.
+try:
+    from claudster_config import ENV_PREFIX
+except Exception:  # pragma: no cover — standalone copy
+    ENV_PREFIX = "CADDIS"
+KEYS_FILE_ENV = f"{ENV_PREFIX}_KEYS_FILE"
+
+
+class ConfigError(Exception):
+    """Configuration can't be resolved — unknown provider without an override, or no key."""
+
+
+def _parse_keys_file(path: str) -> dict[str, str]:
+    """Parse an INI/``KEY=VALUE`` keys file. Comments (#) and blank lines are ignored;
+    surrounding quotes are stripped. A missing file yields ``{}`` (not an error — the
+    key may still come from the environment)."""
+    p = Path(path).expanduser()
+    if not p.is_file():
+        return {}
+    out: dict[str, str] = {}
+    for raw in p.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, val = line.split("=", 1)
+        out[key.strip()] = val.strip().strip('"').strip("'")
+    return out
+
+
+def _resolve_key(provider: str, key_env: str, env: dict[str, str]) -> str:
+    """Provider key via env, then the keys file, else ConfigError. Never logged/echoed."""
+    # 1. explicit env (provider-specific, then generic)
+    for name in (key_env, "OSS_API_KEY"):
+        val = (env.get(name) or "").strip()
+        if val:
+            return val
+    # 2. keys file (CADDIS_KEYS_FILE if set, else ~/.caddis/keys.env)
+    keys_path = env.get(KEYS_FILE_ENV) or DEFAULT_KEYS_FILE
+    file_keys = _parse_keys_file(keys_path)
+    for name in (key_env, "OSS_API_KEY"):
+        val = (file_keys.get(name) or "").strip()
+        if val:
+            return val
+    # 3. actionable error — name the var and the file, never a value.
+    #
+    # It also names the providers that DO have a key. When DeepSeek is unset but GLM is configured,
+    # the fix is `--provider glm`, not "go and find a key" — and the old message sent the reader
+    # hunting for a credential they already had. This fails at the moment of use, which is the
+    # least convenient moment to be told to go looking (`.caddis/parking-lot/003`).
+    others = [p for p in configured_providers(env) if p != provider]
+    have = (f"\nProviders that DO have a key here: {', '.join(others)}. "
+            f"To use one now: --provider {others[0]}." if others else "")
+    raise ConfigError(
+        f"no API key for provider {provider!r}. Set ${key_env} (or $OSS_API_KEY), or add\n"
+        f"  {key_env}=<your-key>\n"
+        f"to your keys file ({keys_path}). Override the file path with ${KEYS_FILE_ENV}."
+        + have
+    )
+
+
+def configured_providers(env: dict[str, str]) -> list[str]:
+    """Every preset provider that currently has a usable key. Never returns or logs a key value.
+
+    Exists so a caller can find out BEFORE it needs one. `/caddis:cross-review` used to discover a
+    missing key mid-task, with a commit pending — and a command that fails once at an inconvenient
+    moment does not get retried, so the safety check it provides is simply lost and nobody records
+    that it was lost.
+    """
+    keys_path = env.get(KEYS_FILE_ENV) or DEFAULT_KEYS_FILE
+    file_keys = _parse_keys_file(keys_path)
+    generic = (env.get("OSS_API_KEY") or file_keys.get("OSS_API_KEY") or "").strip()
+    out = []
+    for name, preset in sorted(PROVIDERS.items()):
+        key_env = preset.get("key_env") or f"{name.upper()}_API_KEY"
+        if generic or (env.get(key_env) or "").strip() or (file_keys.get(key_env) or "").strip():
+            out.append(name)
+    return out
+
+
+def resolve(provider: str | None, env: dict[str, str]) -> dict[str, str]:
+    """Resolve ``{base_url, model, api_key}`` for ``provider`` using ``env``.
+
+    ``provider`` defaults to $OSS_PROVIDER then DEEPSEEK. An unknown provider is allowed
+    only when OSS_BASE_URL + OSS_MODEL are supplied. Raises ConfigError otherwise, or
+    when no API key can be resolved.
+    """
+    provider = (provider or env.get("OSS_PROVIDER") or DEFAULT_PROVIDER).strip().lower()
+    preset = PROVIDERS.get(provider, {})
+    base_url = (env.get("OSS_BASE_URL") or preset.get("base_url") or "").rstrip("/")
+    model = env.get("OSS_MODEL") or preset.get("model") or ""
+    if not base_url or not model:
+        known = ", ".join(sorted(PROVIDERS))
+        raise ConfigError(
+            f"unknown provider {provider!r}: set $OSS_BASE_URL and $OSS_MODEL, "
+            f"or use one of: {known}."
+        )
+    key_env = preset.get("key_env") or f"{provider.upper()}_API_KEY"
+    api_key = _resolve_key(provider, key_env, env)
+    return {"base_url": base_url, "model": model, "api_key": api_key}
+
+
+def main(argv: list[str], env: dict[str, str] | None = None) -> int:
+    """CLI bridge for the launchers: ``oss_model.py <provider>`` prints the resolved
+    base_url, model, and api_key on three lines (in that order) to stdout — the caller
+    (claude-oss.sh / .ps1) CAPTURES this output into variables and sets ANTHROPIC_*; it
+    is never displayed. A ConfigError prints its message to stderr and exits 3.
+    """
+    env = os.environ if env is None else env
+    provider = argv[0] if argv else None
+    try:
+        cfg = resolve(provider, env)
+    except ConfigError as exc:
+        print(str(exc), file=sys.stderr)
+        return 3
+    print(cfg["base_url"])
+    print(cfg["model"])
+    print(cfg["api_key"])
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))