rockycode 0.1.0__py3-none-any.whl

rockycode/engine/permission.py

@@ -0,0 +1,198 @@
+"""Pure permission policy — no UI, no I/O, no async. The testable heart of the
+opt-in approval layer.
+
+`decide(mode, risk, args, workdir)` maps a tool's static risk tier
+(safe|moderate|risky — see tools.RISK / Tool.risk) and the session's permission
+mode (yolo|ask|careful) to one of {"allow", "ask"}. The TUI's approver runs this
+first and only pops a modal on "ask"; bench/headless never even calls it (its
+engine keeps the always-allow default).
+
+`sniff_danger(tool, args)` is an advisory heuristic that flags remote-code-
+execution / destructive patterns so the approval modal can highlight them — the
+real defense against a "cheating" skill that tells the model to curl a virus,
+applied at the layer where the actual command is visible.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Optional
+
+from rockycode.engine.safety import classify_command
+
+MODES = ("yolo", "ask", "careful")
+RISKS = ("safe", "moderate", "risky")
+
+
+READ_TOOLS = ("read_file", "grep", "glob")
+
+
+def decide(mode: str, risk: str, args: dict, workdir: Path, tool: str = "", read_grants=()) -> str:
+    """Return "allow" | "ask" | "block". Never prompts; just classifies the call.
+
+    Command-level danger is judged FIRST, and it overrides the mode — this is the
+    same per-command classifier goal mode uses, lifted into the shared permission
+    layer so *chat* bash is judged by what the command DOES, not just that it's
+    "a bash call". So a benign `ls` and a `brew install` are no longer the same
+    decision:
+    - a "block"-tier command (e.g. `sudo rm -rf /`, `curl … | sudo sh`) → "block"
+      in EVERY mode, even yolo — it must never run unattended.
+    - an "ask"-tier command (install / privileged / network: brew/apt/sudo/…) →
+      "ask" in ask & careful — a fresh prompt every time. Paired with
+      session_grantable(), a per-tool "allow for this session" can't wave it
+      through. In yolo it still runs (you opted out of prompts).
+
+    Then the ordinary tier logic:
+    - yolo    : allow everything else
+    - safe    : allow — EXCEPT a read whose target escapes the workdir (secrets)
+    - risky   : ask (bash/web_fetch/mcp__*) in both ask and careful
+    - moderate: `ask` allows an in-workdir write, else ask; `careful` always asks.
+    """
+    if tool == "bash":
+        action = classify_command(str(args.get("command", ""))).action
+        if action == "block":
+            return "block"                     # never runs — even in yolo
+        if action == "ask" and mode != "yolo":
+            return "ask"                        # dangerous cmd → always a prompt
+    if mode == "yolo":
+        return "allow"
+    if risk == "safe":
+        if tool in READ_TOOLS and _read_escapes_workdir(tool, args, workdir, read_grants):
+            return "ask"
+        return "allow"
+    if risk == "risky":
+        return "ask"
+    # moderate (write_file / edit_file / remember)
+    if mode == "careful":
+        return "ask"
+    return "allow" if _writes_inside(args, workdir) else "ask"
+
+
+def session_grantable(tool: str, args: dict) -> bool:
+    """Whether a per-tool "allow for this session" grant may cover THIS call.
+
+    False for a dangerous bash command (install / privileged / network /
+    destructive): approving a benign `ls` for the session must NOT silently
+    green-light a later `brew install` or `sudo …`. Those keep prompting (or
+    stay blocked) every time, no matter the session allowlist. Everything else is
+    grantable as before."""
+    if tool == "bash":
+        return classify_command(str(args.get("command", ""))).action == "allow"
+    return True
+
+
+def command_binary(command: str) -> str:
+    """The program a bash command runs — the unit a session grant is scoped to.
+
+    A bash session grant is NEVER "all bash": approving `lake build` grants the
+    `lake` BINARY (so `lake build`, `lake env lean`, … stop nagging during a
+    proof/test loop) but a later `curl`/`rm`/`sudo` is a different binary and
+    still prompts. Skips leading `VAR=val` assignments; returns the basename
+    (so `/usr/bin/lake` and `lake` are the same grant).
+
+    Returns "" for ANY command that chains, redirects, or substitutes
+    (`; | & > < ( ) { } ` $` or a newline) — a compound like `lake build; curl
+    evil` must not match a `lake` grant, or the chained command would ride in.
+    "" never matches a grant, so those always re-prompt.
+    """
+    import re
+    if any(c in command for c in "|&;<>(){}`$\n"):
+        return ""
+    for tok in command.strip().split():
+        if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*=.*", tok):
+            continue  # env assignment prefix
+        return tok.rsplit("/", 1)[-1]
+    return ""
+
+
+def _read_escapes_workdir(tool: str, args: dict, workdir: Path, read_grants=()) -> bool:
+    """True if a read tool's target lies outside workdir AND isn't already granted
+    (→ gate it). glob has no path arg, so its pattern is judged instead; an
+    absolute/`~`/`..` pattern is treated as escaping. A path inside a granted root
+    doesn't re-prompt (approving a read widens the jail; see tools._jail)."""
+    if tool == "glob":
+        pat = args.get("pattern")
+        if not isinstance(pat, str):
+            return False
+        return pat.startswith(("/", "~")) or ".." in pat
+    p = args.get("path")
+    if tool == "grep" and not p:
+        p = "."  # grep defaults to the workdir root — inside
+    if not isinstance(p, str) or not p:
+        return False
+    try:
+        target = Path(p)
+        if not target.is_absolute():
+            target = workdir / target
+        target = target.resolve()
+        wd = workdir.resolve()
+    except (OSError, ValueError, RuntimeError):
+        return True  # unresolvable → fail-safe → ask
+    roots = (wd, *read_grants)
+    return not any(target == r or r in target.parents for r in roots)
+
+
+def _writes_inside(args: dict, workdir: Path) -> bool:
+    """True only if args['path'] resolves to a location within workdir. Unknown
+    or missing path is treated as outside (fail-safe → ask)."""
+    p = args.get("path")
+    if not isinstance(p, str) or not p:
+        return False
+    try:
+        target = Path(p)
+        if not target.is_absolute():
+            target = workdir / target
+        target = target.resolve()
+        wd = workdir.resolve()
+    except (OSError, ValueError, RuntimeError):
+        return False
+    return target == wd or wd in target.parents
+
+
+# Advisory only — these never block, they just surface a warning in the modal.
+_DANGER = [
+    (re.compile(r"\b(curl|wget|fetch)\b[^|]*\|\s*(sudo\s+)?(ba|z|da)?sh\b", re.I),
+     "pipes a download straight into a shell"),
+    (re.compile(r"\|\s*(sudo\s+)?(ba|z|da)?sh\b(\s|$)", re.I),
+     "pipes output into a shell"),
+    (re.compile(r"base64\s+-+d\w*\b.*\|\s*(ba|z)?sh", re.I | re.S),
+     "decodes base64 and runs it"),
+    (re.compile(r"eval\s+[\"']?\$\(", re.I),
+     "evals a command-substitution result"),
+    (re.compile(r"\brm\s+-[a-z]*r[a-z]*f?\s+(-{1,2}\S+\s+)*[~/]", re.I),
+     "recursive delete of a home/root path"),
+    (re.compile(r">>?\s*~?/?(\.(ssh|bashrc|zshrc|bash_profile|profile)\b|\.ssh/)", re.I),
+     "writes to a shell/ssh dotfile"),
+    (re.compile(r"\bcrontab\b", re.I),
+     "edits cron jobs"),
+    (re.compile(r"chmod\s+\+x\b[^&;|]*/tmp/", re.I),
+     "makes a /tmp file executable"),
+    (re.compile(r"\bnc\b[^|;&]*\s-\w*e\w*\b|/dev/tcp/", re.I),
+     "looks like a reverse shell"),
+    (re.compile(r"\b(?:ba|z|da)?sh\b\s+-[a-z]*c\b[^\n]*\$\(", re.I),
+     "runs a command-substitution result in a shell"),
+    (re.compile(r"<\(\s*(?:sudo\s+)?(?:curl|wget|fetch)\b", re.I),
+     "process-substitutes a network download into a command"),
+    (re.compile(r"\b(?:python[0-9.]*|perl|ruby|node|php)\b\s+-[a-z]*[ceE]\b[^\n]*"
+                r"(?:curl|wget|urllib|urlopen|requests|socket|https?://)", re.I),
+     "inline interpreter script that pulls from the network"),
+]
+
+
+def sniff_danger(tool: str, args: dict) -> Optional[str]:
+    """Return a short reason if the call matches a known dangerous pattern, else
+    None. Checks bash commands, web_fetch URLs, and (defensively) MCP tool args."""
+    if tool == "bash":
+        blob = str(args.get("command", ""))
+    elif tool == "web_fetch":
+        blob = str(args.get("url", ""))
+    elif tool.startswith("mcp__"):
+        blob = str(args)
+    else:
+        return None
+    if not blob:
+        return None
+    for rx, why in _DANGER:
+        if rx.search(blob):
+            return why
+    return None

rockycode/engine/planmode.py

@@ -0,0 +1,249 @@
+"""Plan-mode policy: the read-only gate for interactive planning.
+
+Plan mode is HOST state on the Engine (never a model-invoked tool — an
+out-of-distribution mode tool invokes unreliably on DeepSeek, and schema churn
+breaks the prefix cache; see docs/plan-mode-design.md). While it is on, every
+tool call runs through gate() BEFORE the normal permission/approver flow:
+
+  pass  — hand the call to the normal flow (permission.decide + modal):
+          every 'safe'-tier read, read-only-classified bash (which still ASKS,
+          never auto-allows — a read-only `cat ~/.ssh/id_rsa` must face a
+          human), and web_fetch (a read of the world, SSRF-guarded, still asks).
+  allow — run without asking: a write/edit whose RESOLVED target is exactly
+          the session's plan file. The one writable path in the mode.
+  deny  — everything else that mutates. The message teaches the model where
+          to go instead (keep exploring, write the plan) rather than just
+          refusing, so the turn keeps moving.
+
+This gate decides deny-vs-ask; it is NOT a security boundary (human approval,
+the file-tool jail, and the secret-file refusals are). The bash classifier is
+therefore a conservative whitelist, not a bulletproof shell parser: a sneaky
+"read-only" command that slips through still lands in front of the user.
+"""
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Verdict:
+    action: str   # "pass" | "allow" | "deny"
+    message: str  # model-facing text for deny; "" otherwise
+
+
+PASS = Verdict("pass", "")
+
+# Risky-tier tools that only READ the world — forwarded to the normal ask flow.
+# (web_search/web_research are already 'safe'-tier and pass on risk alone.)
+_WORLD_READS = frozenset({"web_fetch"})
+
+_WRITE_MSG = (
+    "[blocked] plan mode is read-only — no code changes yet. The one writable "
+    "file is the plan: {plan}. Keep exploring with read-only tools and write "
+    "your plan there; the user approves it before any changes are made."
+)
+_BASH_MSG = (
+    "[blocked] plan mode is read-only and this command could change state. "
+    "Read-only commands (git log/diff/show/status/blame, ls, cat, rg, find …) "
+    "may run with approval — no redirects, chaining, or substitution. Write "
+    "your plan to {plan} when ready; the user approves it before any changes."
+)
+_TOOL_MSG = (
+    "[blocked] '{tool}' is not available in plan mode — it can change state. "
+    "Explore with read-only tools, then write your plan to {plan}; the user "
+    "approves it before any changes are made."
+)
+
+
+# The plan-mode instruction rides the USER turn — never the system prompt or
+# the tool list — so toggling the mode leaves the cached prompt prefix
+# byte-identical (DeepSeek prefix caching is full-prefix-match only).
+_MARKER = (
+    "[Plan mode — planning only, no code changes. Explore with read-only tools "
+    "(read-only bash and web fetches still ask for approval). BRAINSTORM first: "
+    "if a decision that is genuinely the user's — scope, a tech choice, an "
+    "ambiguous requirement — would shape the plan, ask the single most "
+    "important question and stop; one question per turn; do NOT create the "
+    "plan file while brainstorming. If the user says to just write the plan, "
+    "draft immediately. DRAFT when answers stop changing the design: write the "
+    "plan to {path} — a few phases, each with concrete, verifiable steps — "
+    "then stop. That file is the only thing you may write; the user approves "
+    "the plan before any changes are made.]"
+)
+
+
+def marker(plan_file: Path) -> str:
+    """The per-turn plan-mode instruction (prepended to each user message)."""
+    return _MARKER.format(path=plan_file)
+
+
+# ── plan-file parsing ─────────────────────────────────────────────────────────
+# The marker stays format-LIGHT on purpose: dictating markdown shape costs
+# tokens every turn and different models write plans differently. Instead the
+# parser is liberal — a phase line is a markdown heading ('## Verify') OR a
+# top-level numbered item ('2. Verify', bold or plain); its bullets / indented
+# numbered lines are the phase's steps. This is what the future plan→goal
+# handoff reads (goal.parse_plan drops heading lines, so it can't be reused).
+
+_PHASE_RX = re.compile(r"^(?:#{1,6}\s+|\*{0,2}\d+[.)]\*{0,2}\s+)\s*(.+?)\s*$")
+_STEP_RX = re.compile(r"^(?:\s+(?:[-*•]|\d+[.)])|[-*•])\s+(.+?)\s*$")
+
+
+def parse_plan_file(text: str) -> list[tuple[str, list[str]]]:
+    """(phase title, [steps]) pairs from a drafted plan, shape-agnostic.
+
+    A document title (an H1 with no steps of its own, like '# Fix add()')
+    is dropped when real phases carry the steps: any step-less phase is
+    pruned as long as at least one phase has steps."""
+    phases: list[tuple[str, list[str]]] = []
+    for line in text.splitlines():
+        s = _STEP_RX.match(line)
+        if s and phases:
+            phases[-1][1].append(s.group(1).strip())
+            continue
+        p = _PHASE_RX.match(line)
+        if p:
+            title = p.group(1).strip().strip("*").rstrip(":：").strip()
+            if title:
+                phases.append((title, []))
+    if any(steps for _, steps in phases):
+        phases = [(t, st) for t, st in phases if st]
+    return phases
+
+
+def create_plan_file(workdir: Path, topic: str = "") -> Path:
+    """Create (and return) a fresh plan file under .rockycode/plans/.
+
+    The directory self-gitignores (a `*` .gitignore inside it) so drafts never
+    pollute the project's git status — delete that file to start committing
+    plans. Name: <date>-<topic-slug>.md, falling back to the time when no
+    topic was given; an existing non-empty file of the same name gets a -N
+    suffix instead of being reused (the turn-end gate watches THIS session's
+    file for changes, so it must start empty)."""
+    plans = workdir / ".rockycode" / "plans"
+    plans.mkdir(parents=True, exist_ok=True)
+    gitignore = plans / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text("*\n")
+    slug = re.sub(r"[^a-z0-9]+", "-", topic.lower()).strip("-")[:40] or time.strftime("%H%M")
+    base = f"{time.strftime('%Y-%m-%d')}-{slug}"
+    path, n = plans / f"{base}.md", 1
+    while path.exists() and path.stat().st_size > 0:
+        n += 1
+        path = plans / f"{base}-{n}.md"
+    path.touch()
+    return path
+
+
+def gate(tool: str, args: dict, risk: str, plan_file: Path, workdir: Path) -> Verdict:
+    """Classify one tool call under plan mode. *risk* is the registry tier
+    ('safe'/'moderate'/'risky' — unknown tools default risky upstream)."""
+    if risk == "safe":
+        return PASS
+    if tool in ("write_file", "edit_file"):
+        if _is_plan_file(args.get("path"), plan_file, workdir):
+            return Verdict("allow", "")
+        return Verdict("deny", _WRITE_MSG.format(plan=plan_file))
+    if tool == "bash":
+        cmd = args.get("command")
+        if isinstance(cmd, str) and is_read_only_command(cmd):
+            return PASS
+        return Verdict("deny", _BASH_MSG.format(plan=plan_file))
+    if tool in _WORLD_READS:
+        return PASS
+    return Verdict("deny", _TOOL_MSG.format(tool=tool, plan=plan_file))
+
+
+def _is_plan_file(path, plan_file: Path, workdir: Path) -> bool:
+    """True iff *path* RESOLVES to exactly the plan file — `..`, symlinks, and
+    absolute aliases all collapse first, so the carve-out can't be retargeted.
+    Any malformed/missing path fails safe (False → deny)."""
+    if not isinstance(path, str) or not path:
+        return False
+    p = Path(path)
+    if not p.is_absolute():
+        p = workdir / p
+    try:
+        return p.resolve() == plan_file.resolve()
+    except OSError:
+        return False
+
+
+# ── read-only bash classification ────────────────────────────────────────────
+# Whitelist, not blacklist: only commands we KNOW don't mutate may pass to the
+# ask flow; everything unrecognized is denied. Rejected outright: redirects,
+# command chaining, substitution, and multi-line — so pipes are the only
+# composition, and every pipe segment must itself be read-only.
+
+_META = re.compile(r">|;|&|\$\(|`|<\(")
+# awk/find can execute subcommands without any shell metacharacter
+_EMBEDDED_EXEC = re.compile(r"\bsystem\s*\(")
+
+_READ_CMDS = frozenset({
+    "ls", "cat", "head", "tail", "wc", "stat", "file", "du", "tree", "pwd",
+    "which", "grep", "rg", "fd", "sort", "uniq", "cut", "diff", "realpath",
+    "basename", "dirname", "date", "nl", "column", "od", "strings",
+    "find", "sed", "awk", "git",
+})
+_GIT_READ_SUBS = frozenset({
+    "log", "diff", "show", "status", "blame", "shortlog", "describe",
+    "ls-files", "rev-parse", "grep", "reflog",
+})
+_FIND_WRITE_FLAGS = frozenset({
+    "-exec", "-execdir", "-ok", "-okdir", "-delete", "-fprint", "-fprintf", "-fls",
+})
+
+
+def is_read_only_command(command: str) -> bool:
+    """True iff *command* is a whitelisted read-only invocation (it still goes
+    through the normal ask flow — this never auto-allows)."""
+    cmd = command.strip()
+    if not cmd or "\n" in cmd or _META.search(cmd) or _EMBEDDED_EXEC.search(cmd):
+        return False
+    return all(_segment_read_only(seg) for seg in cmd.split("|"))
+
+
+def _segment_read_only(segment: str) -> bool:
+    tokens = segment.split()
+    # skip leading VAR=value assignments (FOO=1 git log)
+    while tokens and re.match(r"^\w+=", tokens[0]):
+        tokens = tokens[1:]
+    if not tokens:
+        return False
+    name = tokens[0].rsplit("/", 1)[-1]  # /usr/bin/git → git
+    if name not in _READ_CMDS:
+        return False
+    if name == "git":
+        return _git_read_only(tokens[1:])
+    if name == "find":
+        return not any(t in _FIND_WRITE_FLAGS for t in tokens[1:])
+    if name == "sed":
+        return not any(t.startswith("-i") for t in tokens[1:])
+    return True
+
+
+def _git_read_only(tokens: list[str]) -> bool:
+    """git with a read-only subcommand. `-c` (can define alias/hook-ish config)
+    and `--output`/`--ext-diff` (write a file / run a command) are rejected even
+    on read subcommands."""
+    sub = None
+    i = 0
+    while i < len(tokens):
+        t = tokens[i]
+        if t in ("-c",) or t.startswith("--output") or t == "--ext-diff":
+            return False
+        if t in ("-C", "--git-dir", "--work-tree"):
+            i += 2  # flag takes a value
+            continue
+        if t.startswith("-"):
+            i += 1
+            continue
+        sub = t
+        break
+    if sub is None or sub not in _GIT_READ_SUBS:
+        return False
+    # write-capable flags can appear after the subcommand too (git log --output=x)
+    return not any(t.startswith("--output") or t == "--ext-diff" for t in tokens[i:])

rockycode/engine/providers.py

@@ -0,0 +1,196 @@
+"""Provider profiles: switch which OpenAI-compatible endpoint + model rocky uses.
+
+Anti-glue by design. Every provider here (DeepSeek, MiniMax, GLM, Kimi, …)
+speaks the OpenAI chat-completions protocol, so the OpenAI SDK is the ONLY
+compatibility layer — rocky never writes a per-provider adapter. A provider is
+DATA, not code: a base_url, some model ids, which env var holds its key, and
+which reasoning-param shape it wants. Adding one is a few lines here or in
+`~/.rockycode/providers.toml`; a non-OpenAI-compatible provider is unsupported.
+
+Regions: MiniMax / Kimi / GLM run SEPARATE international and China endpoints —
+different base_url AND different key. That's modeled as multiple `endpoints` on
+one provider (models shared), not duplicated entries. Each endpoint is pickable
+as `<provider>` (the default) or `<provider>-<region>` (e.g. `kimi-cn`).
+
+Keys are rocky-OWNED per endpoint: `ROCKYCODE_<NAME>_API_KEY` (intl) /
+`ROCKYCODE_<NAME>_CN_API_KEY` (cn) — never the ambient `MINIMAX_API_KEY` etc.
+The built-in `deepseek` reads the existing ROCKYCODE_API_KEY, so current setups
+keep working with no new key.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from rockycode.onboarding import BASE_URL_ENV, DEFAULT_BASE_URL, KEY_ENV
+
+_HOME = Path(os.environ.get("ROCKYCODE_HOME") or Path.home() / ".rockycode")
+PROVIDERS_TOML = _HOME / "providers.toml"
+_PLACEHOLDERS = {"", "replace-me", "sk-replace-me", "your-api-key"}
+
+
+@dataclass
+class Endpoint:
+    # `eid` is the EXPLICIT /model token — no magic default. Regional endpoints
+    # are spelled out (kimi-en / kimi-cn / minimax-en / minimax-cn), and where a
+    # provider's international arm is a different brand it gets that name (GLM's
+    # is z.ai → `zai`). `key_env` matches: ROCKYCODE_<EID_UPPER>_API_KEY.
+    eid: str
+    base_url: str
+    key_env: str
+
+    def key(self) -> Optional[str]:
+        v = (os.getenv(self.key_env) or "").strip()
+        return v if v and v.lower() not in _PLACEHOLDERS else None
+
+
+@dataclass
+class Provider:
+    name: str
+    models: list[str]
+    endpoints: list[Endpoint]
+    reasoning: str = "openai"   # deepseek | openai | none
+    tools: str = "native"      # native | off
+    label: str = ""
+    builtin: bool = True
+
+
+@dataclass
+class Choice:
+    """A flat, pickable (provider, endpoint, model). `id` is `<eid>:<model>`
+    (e.g. kimi-cn:kimi-k3 / zai:glm-5.2); `configured` = its key is set, which
+    is how the picker stays short (show only what you've keyed)."""
+    provider: Provider
+    endpoint: Endpoint
+    model: str
+
+    @property
+    def prov_id(self) -> str:
+        return self.endpoint.eid
+
+    @property
+    def id(self) -> str:
+        return f"{self.endpoint.eid}:{self.model}"
+
+    @property
+    def configured(self) -> bool:
+        return self.endpoint.key() is not None
+
+
+def _builtins() -> dict[str, Provider]:
+    # NOTE: regional base_urls are best-effort — verify per provider when you
+    # first test one; correcting a URL is a one-line data edit here or in TOML.
+    return {
+        "deepseek": Provider(
+            name="deepseek", models=["deepseek-v4-pro", "deepseek-v4-flash"],
+            endpoints=[Endpoint("deepseek",
+                                (os.getenv(BASE_URL_ENV) or "").strip() or DEFAULT_BASE_URL,
+                                KEY_ENV)],
+            reasoning="deepseek", label="DeepSeek V4 — rocky's home model"),
+        "minimax": Provider(
+            name="minimax", models=["minimax-m3"],
+            endpoints=[
+                Endpoint("minimax-en", "https://api.minimaxi.chat/v1", "ROCKYCODE_MINIMAX_EN_API_KEY"),
+                Endpoint("minimax-cn", "https://api.minimax.chat/v1", "ROCKYCODE_MINIMAX_CN_API_KEY"),
+            ],
+            reasoning="openai", label="MiniMax M3"),
+        "kimi": Provider(
+            name="kimi", models=["kimi-k3"],
+            endpoints=[
+                Endpoint("kimi-en", "https://api.moonshot.ai/v1", "ROCKYCODE_KIMI_EN_API_KEY"),
+                Endpoint("kimi-cn", "https://api.moonshot.cn/v1", "ROCKYCODE_KIMI_CN_API_KEY"),
+            ],
+            reasoning="none", label="Kimi / Moonshot"),
+        "glm": Provider(
+            name="glm", models=["glm-5.2"],
+            endpoints=[
+                # international arm is a different brand — z.ai, not "glm"
+                Endpoint("zai", "https://api.z.ai/api/paas/v4", "ROCKYCODE_ZAI_EN_API_KEY"),
+                Endpoint("glm-cn", "https://open.bigmodel.cn/api/paas/v4", "ROCKYCODE_GLM_CN_API_KEY"),
+            ],
+            reasoning="none", label="GLM (z.ai intl / bigmodel.cn)"),
+    }
+
+
+def _parse_toml(path: Path) -> dict[str, Provider]:
+    try:
+        import tomllib
+        data = tomllib.loads(path.read_text())
+    except FileNotFoundError:
+        return {}
+    except Exception:  # noqa: BLE001 — a broken file must not crash startup
+        return {}
+    out: dict[str, Provider] = {}
+    for name, cfg in (data.get("providers") or data).items():
+        if not isinstance(cfg, dict):
+            continue
+        models = cfg.get("models") or ([cfg["model"]] if cfg.get("model") else [])
+        # endpoints: explicit list, or a single base_url/key_env pair. Each
+        # endpoint's `id` is its /model token; key_env defaults to
+        # ROCKYCODE_<ID_UPPER>_API_KEY.
+        def _kenv(eid: str) -> str:
+            return f"ROCKYCODE_{eid.upper().replace('-', '_')}_API_KEY"
+        eps_cfg = cfg.get("endpoints")
+        if eps_cfg:
+            eps = [Endpoint(e.get("id", name), e["base_url"],
+                            e.get("key_env", _kenv(e.get("id", name))))
+                   for e in eps_cfg if e.get("base_url")]
+        elif cfg.get("base_url"):
+            eps = [Endpoint(cfg.get("id", name), cfg["base_url"],
+                            cfg.get("key_env", _kenv(cfg.get("id", name))))]
+        else:
+            continue
+        if not models or not eps:
+            continue
+        out[name] = Provider(name=name, models=list(models), endpoints=eps,
+                             reasoning=cfg.get("reasoning", "openai"),
+                             tools=cfg.get("tools", "native"),
+                             label=cfg.get("label", ""), builtin=False)
+    return out
+
+
+def discover() -> dict[str, Provider]:
+    providers = _builtins()
+    providers.update(_parse_toml(PROVIDERS_TOML))
+    return providers
+
+
+def choices() -> list[Choice]:
+    """Every (provider, endpoint, model) as a flat pickable list."""
+    return [Choice(p, e, m) for p in discover().values()
+            for e in p.endpoints for m in p.models]
+
+
+def configured_choices() -> list[Choice]:
+    """Only choices whose key is set — the SHORT list the picker shows by
+    default, so an EN/CN catalog of ~12 doesn't scroll. deepseek is always
+    included (it rides the default ROCKYCODE_API_KEY)."""
+    out = [c for c in choices() if c.configured or c.provider.name == "deepseek"]
+    return out
+
+
+def resolve(spec: str) -> Optional[tuple[Provider, Endpoint, str]]:
+    """Resolve a /model arg to (provider, endpoint, model).
+
+    Forms: an endpoint id (`deepseek`, `kimi-cn`, `zai`), `endpoint:model`
+    (`kimi-cn:k3`, `zai:glm`), or a unique bare model substring. Returns None
+    if the endpoint is unknown or the model substring is ambiguous.
+    """
+    spec = spec.strip()
+    eid_part, _, model_part = spec.replace(":", " ").partition(" ")
+    eid_part, model_part = eid_part.strip(), model_part.strip()
+
+    by_eid = {e.eid: (p, e) for p in discover().values() for e in p.endpoints}
+    if eid_part in by_eid:
+        p, e = by_eid[eid_part]
+        if not model_part:
+            return p, e, p.models[0]
+        hits = [m for m in p.models if model_part.lower() in m.lower()]
+        return (p, e, hits[0]) if len(hits) == 1 else None
+
+    # bare model substring — must be unique across all providers (first endpoint)
+    matches = [(p, p.endpoints[0], m) for p in discover().values() for m in p.models
+               if spec.lower() in m.lower()]
+    return matches[0] if len(matches) == 1 else None