coderio 0.4.0__py3-none-any.whl

coderio/cli/multimodal.py

@@ -0,0 +1,94 @@
+"""Multimodal input helper: detect image paths in user text and encode them.
+
+When the user's REPL input references an image file (e.g. "分析一下 @screen.png"
+or a bare path "./photo.jpg"), this extracts the path, reads it as base64, and
+builds a multimodal content-block list suitable for Anthropic-protocol models
+(智谱 GLM / 阶跃 step-3.7-flash) that natively support image input.
+
+If no image is found, returns the plain text string (zero overhead for the
+common text-only case).
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+from pathlib import Path
+from typing import Union
+
+# Match @path or bare relative/absolute paths ending in an image extension.
+# Supports @-prefixed (mention style) and quoted/unquoted paths.
+_IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"}
+# @image.png  |  ./x.png  |  C:\x.png  |  /tmp/x.png — but not URLs (http/https)
+_IMAGE_PATTERN = re.compile(
+    r"(?:@|\./|/|[A-Za-z]:[\\/])?"  # prefix: @ or ./ or / or drive:\
+    r"[^\s'\"<>|]+?"  # the path body (no spaces/quotes)
+    r"\.(?:png|jpg|jpeg|gif|webp|bmp)",  # image extension
+    re.IGNORECASE,
+)
+
+# MIME types
+_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+}
+
+
+def _is_url(s: str) -> bool:
+    return s.lower().startswith(("http://", "https://"))
+
+
+def extract_images(text: str) -> list[tuple[str, str, str]]:
+    """Find image file references in text. Returns [(path, media_type, b64data)].
+
+    Only paths that exist on disk are included (silently skips nonexistent ones
+    so a stray "@home" doesn't error). URLs are skipped (not fetched here).
+    """
+    found = []
+    seen = set()
+    for m in _IMAGE_PATTERN.finditer(text):
+        raw = m.group(0)
+        # Strip a leading @ (mention syntax) for the actual path.
+        path_str = raw[1:] if raw.startswith("@") else raw
+        if _is_url(path_str):
+            continue
+        p = Path(path_str)
+        if not p.is_file():
+            continue
+        ext = p.suffix.lower()
+        if ext not in _MIME:
+            continue
+        resolved = str(p.resolve())
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        data = p.read_bytes()
+        b64 = base64.b64encode(data).decode("ascii")
+        found.append((path_str, _MIME[ext], b64))
+    return found
+
+
+def build_user_content(text: str) -> Union[str, list[dict]]:
+    """Build the user message content: plain str if no images, or a list of
+    content blocks (text + image) for multimodal models.
+
+    The image blocks use the Anthropic content-block format:
+        {"type": "image", "source": {"type": "base64", "media_type": ..., "data": ...}}
+    which langchain-anthropic's HumanMessage accepts directly.
+    """
+    images = extract_images(text)
+    if not images:
+        return text
+    blocks: list[dict] = [{"type": "text", "text": text}]
+    for path_str, media_type, b64 in images:
+        blocks.append(
+            {
+                "type": "image",
+                "source": {"type": "base64", "media_type": media_type, "data": b64},
+            }
+        )
+    return blocks

coderio/cli/onboarding.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+import tomli_w
+
+from coderio.cli.credentials import write_credentials
+from coderio.cli.providers import PROVIDERS, ProviderInfo
+
+_SKIP = "skip"
+
+
+@dataclass
+class OnboardingResult:
+    provider_id: str
+    model: str
+    base_url: str
+    kind: str
+    api_key: str
+    # Context window size (tokens) probed from the provider's /v1/models/{id}
+    # endpoint at setup time. 0 = probe failed or skipped; the runtime then
+    # falls back to ContextConfig.model_context_limit. Persisted into the
+    # profile's [[profiles]] table so the threshold is accurate on every run
+    # without re-probing.
+    context_limit: int = 0
+
+
+def _menu(prompt_fn) -> ProviderInfo | str:
+    """Display grouped provider menu; return chosen ProviderInfo or 'skip'."""
+    # Group providers for the menu display.
+    plan = [p for p in PROVIDERS if p.plan]
+    cn_direct = [p for p in PROVIDERS if not p.plan and p.id in ("bigmodel_api", "stepfun_api")]
+    intl = [p for p in PROVIDERS if p.id in ("openai", "anthropic")]
+    local = [p for p in PROVIDERS if p.id == "ollama"]
+    custom = [p for p in PROVIDERS if p.id == "openai_custom"]
+    idx = {}
+    n = 1
+    lines = []
+
+    def _add_group(title, providers):
+        nonlocal n
+        lines.append(f"  ── {title} ──")
+        for p in providers:
+            idx[n] = p
+            models_str = f" ({' / '.join(p.models)})" if p.models else ""
+            lines.append(f"  [{n}] {p.label}{models_str}")
+            n += 1
+
+    if plan:
+        _add_group("Coding Plan（订阅制）", plan)
+    if cn_direct:
+        _add_group("国内 API Key 直连", cn_direct)
+    if intl:
+        _add_group("国际", intl)
+    if local:
+        _add_group("本地模型", local)
+    if custom:
+        _add_group("自定义", custom)
+    idx[n] = _SKIP
+    lines.append(f"  [{n}] 跳过（稍后手动配置）")
+    for line in lines:
+        print(line)
+    while True:
+        raw = prompt_fn("选择 provider 编号: ").strip()
+        if raw.isdigit() and int(raw) in idx:
+            return idx[int(raw)]
+        print(f"  无效，请输入 1-{n}")
+
+
+def _choose_model(prompt_fn, p: ProviderInfo) -> str:
+    if not p.models:
+        return prompt_fn("输入模型名: ").strip()
+    for i, m in enumerate(p.models, 1):
+        star = " *" if m == p.default_model else ""
+        print(f"  [{i}] {m}{star}")
+    raw = prompt_fn("选择模型（回车=默认）: ").strip()
+    if raw == "" or not raw.isdigit():
+        return p.default_model
+    i = int(raw) - 1
+    if 0 <= i < len(p.models):
+        return p.models[i]
+    return p.default_model
+
+
+def _save_to_config(result: OnboardingResult, config_path: Path) -> None:
+    """Merge the onboarding result into ~/.coderio/config.toml.
+
+    Updates [model] section with provider_id, default, base_url. Preserves all
+    other sections the user may have configured. Without this, build_chat_model
+    never sees provider_id and falls back to the broken S0 path that ignores the
+    credentials file."""
+    data: dict = {}
+    if config_path.is_file():
+        try:
+            with open(config_path, "rb") as f:
+                data = tomllib.load(f)
+        except Exception:
+            data = {}
+    model_section = data.get("model", {})
+    model_section["provider_id"] = result.provider_id
+    model_section["default"] = result.model
+    if result.base_url:
+        model_section["base_url"] = result.base_url
+    model_section["provider"] = result.kind
+    # Persist the probed context window so compaction uses the real threshold
+    # on every run. Only write when > 0 — a 0 means probe failed/skipped, and
+    # we don't want to overwrite a previously-good value with the fallback.
+    if getattr(result, "context_limit", 0) > 0:
+        model_section["context_limit"] = result.context_limit
+    data["model"] = model_section
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(config_path, "wb") as f:
+        tomli_w.dump(data, f)
+
+
+def _save_profile_to_config(result: OnboardingResult, profile_name: str, config_path: Path) -> None:
+    """Append a named profile to config.toml and mark it active.
+
+    Read-modify-write: preserves all existing sections and any prior profiles.
+    Appends a [[profiles]] table and sets active_profile to the new name so the
+    just-configured profile is immediately usable. If a profile with the same
+    name already exists, it is replaced in place (re-configuring rather than
+    duplicating).
+    """
+    data: dict = {}
+    if config_path.is_file():
+        try:
+            with open(config_path, "rb") as f:
+                data = tomllib.load(f)
+        except Exception:
+            data = {}
+    profiles = data.get("profiles", [])
+    if not isinstance(profiles, list):
+        profiles = []
+    entry = {
+        "name": profile_name,
+        "provider_id": result.provider_id,
+        "model": result.model,
+        "base_url": result.base_url,
+        "kind": result.kind,
+    }
+    # Persist the probed context window so the compaction threshold is accurate
+    # on every subsequent run without re-probing. Only write when > 0 — a 0
+    # means the probe failed or wasn't run, and we don't want to overwrite a
+    # previously-good value with a fallback marker (e.g. when re-configuring
+    # an existing profile off-network).
+    if getattr(result, "context_limit", 0) > 0:
+        entry["context_limit"] = result.context_limit
+    # Replace an existing same-named profile, else append.
+    replaced = False
+    for i, p in enumerate(profiles):
+        if isinstance(p, dict) and p.get("name") == profile_name:
+            profiles[i] = entry
+            replaced = True
+            break
+    if not replaced:
+        profiles.append(entry)
+    data["profiles"] = profiles
+    data["active_profile"] = profile_name
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(config_path, "wb") as f:
+        tomli_w.dump(data, f)
+
+
+def _verify_and_probe(p: ProviderInfo, api_key: str, model: str, base_url: str) -> tuple[bool, str, int]:
+    """Verify the key works AND probe the model's context window size.
+
+    Returns (success, message, context_limit). context_limit is 0 on any
+    failure (verification failed OR probe failed) — callers fall back to the
+    config default in that case, so probe failures never block onboarding.
+
+    The verification uses a 1-token 'hi' request (cheap, fast). On success we
+    additionally query /v1/models/{id} to discover the real context window so
+    the compaction threshold matches the actual model (e.g. step-3.7-flash is
+    256K, not the 200K default). Both calls are best-effort; only the verify
+    result gates the wizard.
+    """
+    try:
+        if p.kind == "anthropic":
+            from langchain_anthropic import ChatAnthropic
+
+            m = ChatAnthropic(model=model, base_url=base_url, api_key=api_key, max_tokens=1)
+        else:
+            from langchain_openai import ChatOpenAI
+
+            m = ChatOpenAI(model=model, base_url=base_url, api_key=api_key, max_tokens=1)
+        m.invoke("hi")
+    except Exception as e:
+        msg = str(e).lower()
+        if any(k in msg for k in ("authentication", "401", "unauthorized", "api key")):
+            return (False, f"API key 无效或已过期: {e}", 0)
+        if any(k in msg for k in ("connect", "timeout", "refused", "unreachable")):
+            return (False, f"无法连接到 {base_url}，请检查网络: {e}", 0)
+        if any(k in msg for k in ("404", "not found", "model")):
+            return (False, f"模型 {model} 不可用: {e}", 0)
+        return (False, f"验证失败: {type(e).__name__}: {e}", 0)
+    # Verify passed — best-effort probe for context window size. Never raises.
+    from coderio.llm.probe import probe_context_limit
+
+    context_limit = probe_context_limit(p.kind, base_url, api_key, model)
+    suffix = f"（检测到 {context_limit // 1000}K 上下文窗口）" if context_limit > 0 else ""
+    return (True, f"验证成功{suffix}", context_limit)
+
+
+# Back-compat shim: older call sites/tests may still import _verify_key.
+def _verify_key(p: ProviderInfo, api_key: str, model: str, base_url: str) -> tuple[bool, str]:
+    ok, msg, _ = _verify_and_probe(p, api_key, model, base_url)
+    return (ok, msg)
+
+
+def run_onboarding(prompt_fn, password_fn, creds_file: Path | None = None) -> OnboardingResult | None:
+    """Run the interactive wizard. Returns None if user skips."""
+    print("检测到尚未配置 API key，启动配置向导：")
+    choice = _menu(prompt_fn)
+    if choice == _SKIP:
+        print("已跳过。稍后可编辑 ~/.coderio/config.toml 手动配置。")
+        return None
+    p = choice
+    base_url = p.base_url
+    if p.id == "openai_custom":
+        base_url = prompt_fn("输入 base_url: ").strip()
+    model = _choose_model(prompt_fn, p)
+    context_limit = 0
+    if p.id != "ollama":
+        print(f"  提示：{p.api_key_hint}")
+        api_key = password_fn().strip()
+        if not api_key:
+            print("  未输入 key，已取消。")
+            return None
+        # Verify the key works before saving — catches typos, wrong endpoints,
+        # expired keys at config time instead of on first message in the TUI.
+        # On success, also probe the model's context window so compaction uses
+        # the real threshold (256K for step-3.7-flash, 200K for claude, etc).
+        print("  正在验证连接...")
+        ok, msg, context_limit = _verify_and_probe(p, api_key, model, base_url)
+        if not ok:
+            print(f"  ❌ {msg}")
+            retry = prompt_fn("  重新输入 key？(回车=重试, n=跳过): ").strip().lower()
+            if retry == "n":
+                return None
+            api_key = password_fn().strip()
+            if not api_key:
+                return None
+            print("  正在验证连接...")
+            ok, msg, context_limit = _verify_and_probe(p, api_key, model, base_url)
+            if not ok:
+                print(f"  ❌ {msg}")
+                print("  仍验证失败。配置已跳过，请稍后检查配置。")
+                return None
+        print(f"  ✅ {msg}")
+    else:
+        api_key = "ollama"  # Ollama doesn't need a key
+    write_credentials({p.id: api_key}, creds_file)
+    result = OnboardingResult(
+        provider_id=p.id,
+        model=model,
+        base_url=base_url,
+        kind=p.kind,
+        api_key=api_key,
+        context_limit=context_limit,
+    )
+    # Persist provider_id/model/base_url to config.toml so build_chat_model
+    # uses the S1 (provider registry) path — not the broken S0 fallback.
+    if creds_file is not None:
+        config_path = creds_file.parent / "config.toml"
+        _save_to_config(result, config_path)
+    print("  配置完成！")
+    return result

coderio/cli/providers.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ProviderInfo:
+    id: str
+    label: str
+    kind: str
+    plan: bool
+    base_url: str
+    models: tuple[str, ...]
+    default_model: str
+    api_key_hint: str = ""
+
+
+_BIGMODEL_MODELS = ("glm-5.2", "glm-5.1", "glm-5-turbo", "glm-4.7")
+_STEPFUN_MODELS = ("step-3.7-flash", "step-3.5-flash", "step-3.5-flash-2603")
+
+PROVIDERS: tuple[ProviderInfo, ...] = (
+    ProviderInfo(
+        id="bigmodel_coding_plan",
+        label="智谱 GLM - Coding Plan",
+        kind="anthropic",
+        plan=True,
+        base_url="https://open.bigmodel.cn/api/anthropic",
+        models=_BIGMODEL_MODELS,
+        default_model="glm-5.2",
+        api_key_hint="智谱开放平台 → 套餐概览 → 新建 API Key",
+    ),
+    ProviderInfo(
+        id="stepfun_coding_plan",
+        label="阶跃 StepFun - Step Plan",
+        kind="anthropic",
+        plan=True,
+        # ChatAnthropic posts to {base_url}/v1/messages. The bare '/step_plan'
+        # base is correct as-is (verified live: returns 200). Do NOT switch
+        # this provider to openai_compatible — ChatOpenAI joins paths
+        # differently ({base_url}/chat/completions) and 404s on this base_url.
+        base_url="https://api.stepfun.com/step_plan",
+        models=_STEPFUN_MODELS,
+        default_model="step-3.7-flash",
+        api_key_hint="阶跃开放平台 → Step Plan 订阅 → 专用 API Key",
+    ),
+    ProviderInfo(
+        id="bigmodel_api",
+        label="智谱 GLM - API Key",
+        kind="anthropic",
+        plan=False,
+        base_url="https://open.bigmodel.cn/api/anthropic",
+        models=_BIGMODEL_MODELS,
+        default_model="glm-5.2",
+        api_key_hint="智谱开放平台 → API Keys",
+    ),
+    ProviderInfo(
+        id="stepfun_api",
+        label="阶跃 StepFun - API Key",
+        kind="openai_compatible",
+        plan=False,
+        base_url="https://api.stepfun.com/v1",
+        models=_STEPFUN_MODELS,
+        default_model="step-3.7-flash",
+        api_key_hint="阶跃开放平台 → API Keys",
+    ),
+    ProviderInfo(
+        id="openai",
+        label="OpenAI",
+        kind="openai_compatible",
+        plan=False,
+        base_url="https://api.openai.com/v1",
+        models=("gpt-4o", "gpt-4o-mini", "gpt-4.1", "gpt-4.1-mini"),
+        default_model="gpt-4o",
+        api_key_hint="platform.openai.com → API Keys",
+    ),
+    ProviderInfo(
+        id="anthropic",
+        label="Anthropic Claude",
+        kind="anthropic",
+        plan=False,
+        base_url="https://api.anthropic.com",
+        models=("claude-sonnet-4-20250514", "claude-haiku-4-20250414"),
+        default_model="claude-sonnet-4-20250514",
+        api_key_hint="console.anthropic.com → API Keys",
+    ),
+    ProviderInfo(
+        id="ollama",
+        label="Ollama（本地）",
+        kind="openai_compatible",
+        plan=False,
+        base_url="http://localhost:11434/v1",
+        models=(),
+        default_model="",
+        api_key_hint="无需 API key（确保 ollama serve 已运行）",
+    ),
+    ProviderInfo(
+        id="openai_custom",
+        label="OpenAI 兼容（自定义）",
+        kind="openai_compatible",
+        plan=False,
+        base_url="",
+        models=(),
+        default_model="",
+        api_key_hint="自定义 provider 的 API key",
+    ),
+)
+
+
+def get_provider(provider_id: str) -> ProviderInfo | None:
+    for p in PROVIDERS:
+        if p.id == provider_id:
+            return p
+    return None

coderio/cli/render.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any
+
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.text import Text
+
+
+def mask_key(key: str) -> str:
+    """Show only the last 4 chars for keys long enough that 4 chars isn't most of it;
+    never leak the full key. Short keys (<=8 chars) are fully masked."""
+    if not key or len(key) <= 8:
+        return "****"
+    return f"****{key[-4:]}"
+
+
+def render_markdown(text: str):
+    return Panel(Markdown(text), title="coderio", border_style="blue")
+
+
+def render_error(message: str):
+    return Panel(Text(message, style="red"), title="error", border_style="red")
+
+
+def render_tool_call(name: str, args: dict[str, Any]):
+    args_str = ", ".join(f"{k}={v!r}" for k, v in args.items())
+    return Text(f"● {name}({args_str})", style="cyan")

coderio/cli/repl.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+
+from coderio.agent.prompts import ActiveSkills
+from coderio.cli.stream import RichStream
+from coderio.config import Config, load_config
+from coderio.llm import build_chat_model
+from coderio.session.store import Session
+from coderio.skills.store import SkillStore, load_skill_store
+from coderio.tools import build_default_tools
+from coderio.tools.permission import (
+    AutoPermissionGate,
+    PermissionGate,
+    PermissionMode,
+    RichPromptPermissionGate,
+)
+
+BUNDLED_SKILLS = Path(__file__).resolve().parents[1] / "skills"
+
+
+class TuiPermissionGate(PermissionGate):
+    """Gate for CONFIRM and AUTO_EDIT modes in the TUI.
+
+    Uses a Textual ModalScreen (via request_confirmation) instead of input(),
+    which would deadlock against Textual's terminal takeover.
+    """
+
+    def __init__(self, mode, tui, auto_allow_execute: bool = False):
+        super().__init__(mode, auto_allow_execute=auto_allow_execute)
+        self._tui = tui
+
+    def _ask(self, tool_name: str, args: dict[str, Any]) -> bool | str:
+        if hasattr(self._tui, "request_confirmation"):
+            return self._tui.request_confirmation(tool_name, args)
+        return True
+
+
+def build_gate(cfg: Config, console=None, tui=None):
+    """Construct the permission gate.
+
+    Four permission tiers (least → most permissive):
+      plan      — read-only, blocks all writes/shell
+      confirm   — prompts before each destructive action
+      auto_edit — auto-allow file edits, shell/web/note still confirm
+      full      — auto-allow everything
+
+    Path isolation is handled by deepagents' backend virtual_mode, not by
+    this gate. This gate only controls WHICH tool types may execute.
+
+    Sandbox联动 (Claude Code "autoAllowBashIfSandboxed" design): when
+    sandbox_mode != "off" AND cfg.tools.auto_allow_if_sandboxed is True, the
+    execute tool auto-approves without prompting (the sandbox provides the real
+    isolation boundary, so per-command prompts become noise). The blacklist
+    still applies via CommandReviewMiddleware. PLAN mode is unaffected.
+    """
+    mode = PermissionMode.normalize(cfg.tools.permission_mode)
+    # auto_allow_execute is meaningful only when a sandbox is active + the
+    # user opted in. FULL mode already allows everything; PLAN stays read-only.
+    sandbox_active = cfg.tools.sandbox_mode != "off"
+    auto_exec = sandbox_active and cfg.tools.auto_allow_if_sandboxed
+    if mode == PermissionMode.FULL:
+        return AutoPermissionGate()
+    if mode == PermissionMode.PLAN:
+        return PermissionGate(PermissionMode.PLAN)
+    if tui is not None:
+        return TuiPermissionGate(mode, tui=tui, auto_allow_execute=auto_exec)
+    if mode == PermissionMode.AUTO_EDIT:
+        return _ReplAutoEditGate(console=console, auto_allow_execute=auto_exec)
+    return RichPromptPermissionGate(console=console, auto_allow_execute=auto_exec)
+
+
+class _ReplAutoEditGate(PermissionGate):
+    """AUTO_EDIT gate for the non-TUI REPL (uses input() for high-risk tools)."""
+
+    def __init__(self, console=None, auto_allow_execute: bool = False):
+        super().__init__(PermissionMode.AUTO_EDIT, auto_allow_execute=auto_allow_execute)
+        self._console = console
+
+    def _ask(self, tool_name: str, args: dict[str, Any]) -> bool:
+        return _default_prompt_repl(tool_name, args)
+
+
+def _default_prompt_repl(tool_name: str, args) -> bool:
+    """Simple input()-based prompt for the REPL (no Textual active)."""
+    confirm = input(f"Allow {tool_name}({args})? [y/N] ").strip().lower()
+    return confirm in {"yes", "y"}
+
+
+def build_runtime(
+    search_from: Path | str = ".",
+    save_dir: Path | str | None = None,
+    session: Session | None = None,
+    console=None,
+    creds_path: Path | str | None = None,
+    mode_override: str | None = None,
+    model_override: str | None = None,
+    provider_override: str | None = None,
+):
+    cfg = load_config(search_from=search_from)
+
+    if mode_override:
+        from dataclasses import replace as _replace
+
+        cfg = _replace(cfg, tools=_replace(cfg.tools, permission_mode=mode_override))
+
+    if model_override:
+        from dataclasses import replace as _replace
+
+        cfg = _replace(cfg, model=_replace(cfg.model, default=model_override))
+
+    if provider_override:
+        from dataclasses import replace as _replace
+
+        cfg = _replace(cfg, model=_replace(cfg.model, provider_id=provider_override))
+
+    if cfg.skills.auto_load:
+        store = load_skill_store(
+            BUNDLED_SKILLS,
+            Path.home() / ".coderio" / "skills",
+            Path(search_from) / ".coderio" / "skills",
+        )
+    else:
+        store = SkillStore()
+
+    model = build_chat_model(cfg, creds_path=creds_path)
+    tools = build_default_tools(cfg.tools.bash_shell)
+    gate = build_gate(cfg, console=console)
+
+    # Load MCP tools from .mcp.json (project + user scope). Connection failures
+    # are logged and skipped — they never block startup. This is a one-time
+    # async operation bridged to sync via asyncio.run.
+    from coderio.mcp_loader import load_mcp_tools_sync
+
+    mcp_tools = load_mcp_tools_sync(search_from=search_from)
+    if mcp_tools:
+        tools = tools + mcp_tools
+
+    if session is None:
+        save = save_dir or Path(cfg.session.save_dir).expanduser()
+        session = Session.create(save, {"model": cfg.model.default, "provider": cfg.model.provider})
+
+    active = ActiveSkills()
+    stream = RichStream(console or Console())
+    return cfg, store, model, tools, gate, session, active, stream
+
+
+def _needs_onboarding(creds_path) -> bool:
+    """Check whether the onboarding wizard should run.
+
+    Returns False (skip onboarding) if ANY key source exists:
+      - credentials file has at least one key
+      - config.toml already has a provider_id
+      - ANTHROPIC_API_KEY / OPENAI_API_KEY / Z_API_KEY env var is set
+    """
+    import os
+
+    from coderio.cli.credentials import read_credentials
+
+    creds = read_credentials(creds_path)
+    if creds:
+        return False
+    config_path = Path(creds_path).parent / "config.toml"
+    if config_path.is_file():
+        try:
+            import tomllib
+
+            with open(config_path, "rb") as f:
+                data = tomllib.load(f)
+            if data.get("model", {}).get("provider_id"):
+                return False
+        except Exception:
+            pass
+    if os.environ.get("ANTHROPIC_API_KEY") or os.environ.get("OPENAI_API_KEY") or os.environ.get("Z_API_KEY"):
+        return False
+    return True
+
+
+def _resolve_resume(cfg: Config, resume: str | None, continue_last: bool) -> Session:
+    save_dir = Path(cfg.session.save_dir).expanduser()
+    if resume:
+        return Session.load_by_id(save_dir, resume)
+    recent = Session.list_recent(save_dir, limit=1)
+    if not recent:
+        raise SystemExit("No previous session to continue.")
+    return Session.load_by_id(save_dir, recent[0])