rovecode 0.4.0-beta.2 → 0.4.0

package/src/providers/profiles.ts

@@ -0,0 +1,156 @@
+/** Model profiles: per-model-family tuning that the provider layer and the prompt assembler share.
+ *
+ *  One profile answers three questions for one model family, in one place:
+ *    1. prompt — a behavioral section appended to the interactive system prompt (cli/runtime.ts
+ *       buildDef). A model that was not tuned for this harness gets the operating contract spelled
+ *       out: the read → edit hash protocol, act by default, parallel calls, verify before "done", …
+ *       The GLM-5.3 profile's section has THREE parts: a Claude Sonnet 5 PERSONA (profile-sonnet5-
+ *       persona.ts — the role Berkay asked for, carrying everything Anthropic publishes about how
+ *       Sonnet 5 behaves and how Claude talks; a closed role that stays Claude Sonnet 5 even when asked
+ *       directly which model it is — /status and /cost still report the real model, so the harness stays
+ *       honest at the system level), then real captured Sonnet 5 VOICE examples (profile-sonnet5-voice.ts),
+ *       then the harness WORKING AGREEMENT (profile-glm53.ts — tool protocol, permissions, reporting;
+ *       names no model or vendor).
+ *    2. wire   — extra request fields the model's endpoint wants. OpenAI-compatible adapters only
+ *       (stream.ts spreads profileWire() into the /chat/completions body); the Anthropic adapter
+ *       has its own dial (anthropicThinking) and no profile today — a GLM behind an Anthropic-protocol
+ *       gateway gets the prompt section and nothing on the wire.
+ *    3. effort — the endpoint's vocabulary for rovecode's ONE effort dial (off|low|medium|high).
+ *
+ *  Two resolvers, on purpose:
+ *    - profileFor (the PROMPT): ROVECODE_PROFILE=off → none for any model; ROVECODE_PROFILE=<id> → that
+ *      profile's section for EVERY model (A/B a contract on a model it was not written for; or pick the
+ *      persona-free `glm-5.3-plain` variant for a GLM); unset → the first profile whose matches() accepts
+ *      the model id.
+ *    - wireProfileFor (the WIRE + effort words): the off-words still switch it off, but a forced id is
+ *      ignored — request fields follow the model id only. An endpoint rejects fields it does not know
+ *      (OpenAI has no `thinking`/`tool_stream`, and "max" is not an OpenAI effort word), so forcing the
+ *      GLM contract onto gpt-5 must not turn every request into a 400.
+ *  Both are provider-agnostic: the same GLM served by kaesra ("zai-org/glm-5.3-flash"), zai ("glm-5.3")
+ *  or openrouter ("z-ai/glm-5.3", "z-ai/glm-5.3:free") gets one profile.
+ *
+ *  Prompt override: <cwd>/.rovecode/profiles/<id>.md, else <ROVECODE_HOME>/profiles/<id>.md, REPLACES
+ *  the whole built-in section (persona + agreement for glm-5.3) — iterate on the text without a rebuild;
+ *  an EMPTY file drops the section and keeps the wire tuning (buildDef appends nothing, not even the
+ *  separator). Read at every buildDef: once per run start, never per turn, so the system prefix stays
+ *  byte-stable within a run (prompt cache).
+ *
+ *  Not a port — rovecode-native. GLM-5.3 facts are Z.ai's model docs (docs.z.ai, glm-5.3 /
+ *  glm-5.3-flash pages, 2026-08): thinking cannot be disabled (`thinking.type` accepts "enabled" only,
+ *  `clear_thinking: false` recommended for agents), `reasoning_effort` low|high|max with max the default
+ *  and the recommendation for coding, temperature 1 / top_p 0.95 suggested, `tool_stream: true` for
+ *  streamed tool-call arguments. The word "medium" is not in GLM's vocabulary (an out-of-enum value
+ *  silently means max), so rovecode's four levels map onto the three it has. */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ModelRef, ThinkingEffort } from "../core/types.ts";
+import { rovecodeHome } from "./auth.ts";
+import { GLM_53_AGENT_CONTRACT } from "./profile-glm53.ts";
+import { SONNET_5_PERSONA } from "./profile-sonnet5-persona.ts";
+import { SONNET_5_VOICE } from "./profile-sonnet5-voice.ts";
+
+export { GLM_53_AGENT_CONTRACT, SONNET_5_PERSONA, SONNET_5_VOICE };
+
+export interface ModelProfile {
+  /** stable id: ROVECODE_PROFILE value, override file name (<id>.md), the live gauntlet's banner */
+  id: string;
+  /** does this model id belong to the family? provider is deliberately not consulted */
+  matches(model: ModelRef): boolean;
+  /** built-in prompt section (markdown, `# ` headers like the base prompt's own sections) */
+  promptSection: string;
+  /** extra OpenAI-compatible request fields; `streaming` = the SSE adapter is asking */
+  wire(ctx: { streaming: boolean }): Record<string, unknown>;
+  /** the endpoint's word for rovecode's level; null = send no reasoning field (endpoint default) */
+  reasoningEffort(effort: ThinkingEffort | undefined): string | null;
+}
+
+/** GLM-5.3 and GLM-5.3-Flash under any vendor prefix, date suffix or `:variant`/`:tag` suffix:
+ *  glm-5.3, glm-5.3-flash, zai-org/glm-5.3-flash, z-ai/glm-5.3-20260816, z-ai/glm-5.3:free,
+ *  glm-5.3:latest — not glm-5.2, not glm-5.32, not glm-5.3x. */
+export const GLM_53_MODEL_RE = /(^|[/:])glm-5\.3(?=[-:]|$)/i;
+
+const glm53Wire = ({ streaming }: { streaming: boolean }): Record<string, unknown> => ({
+  thinking: { type: "enabled", clear_thinking: false },
+  temperature: 1,
+  top_p: 0.95,
+  ...(streaming ? { tool_stream: true } : {}),
+});
+
+// off = leave the endpoint's default alone (max: Z.ai's coding recommendation); low is the fast
+// path; medium has no GLM word and rounds UP (a rovecode "medium" asks for more than "low" —
+// rounding down would hand the two lower levels the same behavior)
+const glm53Effort = (e: ThinkingEffort | undefined): string | null =>
+  e === undefined || e === "auto" || e === "off" ? null : e === "low" ? "low" : e === "medium" ? "high" : "max";
+
+/** The default for the GLM-5.3 family: the Sonnet 5 persona, real Sonnet 5 voice examples, then the
+ *  working agreement. */
+export const GLM_53_PROFILE: ModelProfile = {
+  id: "glm-5.3",
+  matches: (m) => GLM_53_MODEL_RE.test(m.model),
+  promptSection: `${SONNET_5_PERSONA}\n\n${SONNET_5_VOICE}\n\n${GLM_53_AGENT_CONTRACT}`,
+  wire: glm53Wire,
+  reasoningEffort: glm53Effort,
+};
+
+/** The persona-free variant — the working agreement alone, same wire tuning. Opt-in only
+ *  (ROVECODE_PROFILE=glm-5.3-plain): matches no model id by itself. */
+export const GLM_53_PLAIN_PROFILE: ModelProfile = {
+  id: "glm-5.3-plain",
+  matches: () => false,
+  promptSection: GLM_53_AGENT_CONTRACT,
+  wire: glm53Wire,
+  reasoningEffort: glm53Effort,
+};
+
+export const PROFILES: readonly ModelProfile[] = [GLM_53_PROFILE, GLM_53_PLAIN_PROFILE];
+
+const OFF_WORDS = new Set(["off", "0", "false", "none", "no"]);
+
+function forcedId(env: Record<string, string | undefined>): string {
+  return (env["ROVECODE_PROFILE"] ?? "").trim().toLowerCase();
+}
+
+/** The profile whose PROMPT section a model runs under, honoring ROVECODE_PROFILE (off | <id>). An
+ *  unknown id → null, so a typo means "no profile", never a silently different one (profileHint names it). */
+export function profileFor(model: ModelRef, env: Record<string, string | undefined> = process.env): ModelProfile | null {
+  const forced = forcedId(env);
+  if (OFF_WORDS.has(forced)) return null;
+  if (forced.length > 0) return PROFILES.find((p) => p.id === forced) ?? null;
+  return PROFILES.find((p) => p.matches(model)) ?? null;
+}
+
+/** The profile whose WIRE fields and effort words a request carries: by model id only. The off-words
+ *  still disable it; a forced id does not reach the wire (see the header). */
+export function wireProfileFor(model: ModelRef, env: Record<string, string | undefined> = process.env): ModelProfile | null {
+  if (OFF_WORDS.has(forcedId(env))) return null;
+  return PROFILES.find((p) => p.matches(model)) ?? null;
+}
+
+/** ROVECODE_PROFILE names something that is not a profile — the one-line note the live gauntlet prints
+ *  (`rovecode gauntlet --live`); the other surfaces run silently without a profile. */
+export function profileHint(env: Record<string, string | undefined> = process.env): string | null {
+  const forced = forcedId(env);
+  if (forced.length === 0 || OFF_WORDS.has(forced) || PROFILES.some((p) => p.id === forced)) return null;
+  return `ROVECODE_PROFILE=${forced} names no profile (known: ${PROFILES.map((p) => p.id).join(", ")}, off) — running without one`;
+}
+
+/** Override file paths, most specific first (project, then user scope). */
+export function profileOverridePaths(profile: ModelProfile, cwd: string, home: string = rovecodeHome()): string[] {
+  return [join(cwd, ".rovecode", "profiles", `${profile.id}.md`), join(home, "profiles", `${profile.id}.md`)];
+}
+
+/** The section buildDef appends: the first override file that exists (trimmed; "" disables the
+ *  section), else the built-in text. An unreadable file falls back to the built-in text. */
+export function profilePromptSection(profile: ModelProfile, cwd: string, home: string = rovecodeHome()): string {
+  for (const p of profileOverridePaths(profile, cwd, home)) {
+    if (!existsSync(p)) continue;
+    try { return readFileSync(p, "utf8").trim(); } catch { return profile.promptSection; }
+  }
+  return profile.promptSection;
+}
+
+/** The request fields a model's endpoint wants beside the standard body; {} without a wire profile. */
+export function profileWire(model: ModelRef, streaming: boolean, env: Record<string, string | undefined> = process.env): Record<string, unknown> {
+  return wireProfileFor(model, env)?.wire({ streaming }) ?? {};
+}

package/src/providers/provider-config.ts

@@ -0,0 +1,311 @@
+/** Provider configuration — the DATA half of the provider layer (no adapters, no network).
+ *
+ *  Sources, merged per provider id in this order (later wins):
+ *    1. BUILTIN_PROVIDERS (the table below)            scope "builtin"
+ *    2. ~/.rovecode/providers.json (ROVECODE_HOME-aware)   scope "user"
+ *    3. <cwd>/.rovecode/providers.json                  scope "project"
+ *    4. ROVECODE_BASE_URL + ROVECODE_API_KEY                scope "env" — the "custom" provider, always the default
+ *
+ *  File shape (both scopes):
+ *    { "default"?: "provider/model",
+ *      "providers"?: { "<id>": { "baseUrl", "protocol"?, "keyEnv"?, "defaultModel"?, "models"?, "headers"?, "noKey"? } } }
+ *
+ *  Secrets never live in providers.json. A provider's key is the stored credential (auth.ts,
+ *  `rovecode auth set <id>`, masked prompt) else process.env[keyEnv ?? keyNameFor(id)]; `noKey: true`
+ *  marks local servers (ollama, vllm) that need none. The `default` selector is "provider/model"
+ *  split on the FIRST slash (router.ts grammar) — a bare provider id selects its defaultModel.
+ *
+ *  Hot reload: ProviderConfig.snapshot() re-reads when the mtime or size of any source file changed
+ *  (both providers.json + credentials.json), checked at most once per `throttleMs`. A provider added
+ *  from another terminal — or by the agent through provider_edit — is live on the next model call;
+ *  no restart. resolveProvider() (stream.ts) is the one-shot form of the same merge, so the CLI and
+ *  a long-running TUI always agree on what "the default provider" is. */
+
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { credentialsPath, keyNameFor, loadCredentials, rovecodeHome, type StoredCredential } from "./auth.ts";
+
+export type ProviderProtocol = "openai" | "anthropic";
+export type ProviderScope = "builtin" | "user" | "project" | "env";
+/** where a provider's key came from: stored credential, env var, the ROVECODE_API_KEY pair, or nowhere */
+export type KeySource = "stored" | "env" | "inline" | "none";
+
+export interface ProviderSpec {
+  id: string;
+  baseUrl: string;
+  protocol: ProviderProtocol;
+  /** env var consulted when no credential is stored; default keyNameFor(id) (models.dev name or <ID>_API_KEY) */
+  keyEnv?: string;
+  defaultModel?: string;
+  /** static model list for `/models` when the endpoint has no /models route */
+  models?: string[];
+  /** extra request headers (proxies, org ids) — sent on every call to this provider */
+  headers?: Record<string, string>;
+  /** local servers: no key required, the provider counts as configured without one */
+  noKey?: boolean;
+}
+
+export interface ResolvedProvider extends ProviderSpec {
+  keyEnv: string;
+  scope: ProviderScope;
+  apiKey: string | null;
+  keySource: KeySource;
+}
+
+export const BUILTIN_PROVIDERS: readonly ProviderSpec[] = [
+  { id: "kaesra", baseUrl: "https://api.kaesra.tech/v1", protocol: "openai", keyEnv: "KAESRA_API_KEY", defaultModel: "zai-org/glm-5.3-flash" },
+  { id: "openai", baseUrl: "https://api.openai.com/v1", protocol: "openai", keyEnv: "OPENAI_API_KEY" },
+  { id: "anthropic", baseUrl: "https://api.anthropic.com/v1", protocol: "anthropic", keyEnv: "ANTHROPIC_API_KEY", defaultModel: "claude-opus-5" },
+  { id: "deepseek", baseUrl: "https://api.deepseek.com/v1", protocol: "openai", keyEnv: "DEEPSEEK_API_KEY" },
+  { id: "groq", baseUrl: "https://api.groq.com/openai/v1", protocol: "openai", keyEnv: "GROQ_API_KEY" },
+  { id: "openrouter", baseUrl: "https://openrouter.ai/api/v1", protocol: "openai", keyEnv: "OPENROUTER_API_KEY" },
+  { id: "ollama", baseUrl: "http://127.0.0.1:11434/v1", protocol: "openai", keyEnv: "OLLAMA_API_KEY" },
+  { id: "lmstudio", baseUrl: "http://127.0.0.1:1234/v1", protocol: "openai", keyEnv: "LMSTUDIO_API_KEY" },
+  { id: "together", baseUrl: "https://api.together.xyz/v1", protocol: "openai", keyEnv: "TOGETHER_API_KEY" },
+  { id: "mistral", baseUrl: "https://api.mistral.ai/v1", protocol: "openai", keyEnv: "MISTRAL_API_KEY" },
+  { id: "cerebras", baseUrl: "https://api.cerebras.ai/v1", protocol: "openai", keyEnv: "CEREBRAS_API_KEY" },
+  { id: "fireworks", baseUrl: "https://api.fireworks.ai/inference/v1", protocol: "openai", keyEnv: "FIREWORKS_API_KEY" },
+  { id: "perplexity", baseUrl: "https://api.perplexity.ai", protocol: "openai", keyEnv: "PERPLEXITY_API_KEY" },
+  { id: "xai", baseUrl: "https://api.x.ai/v1", protocol: "openai", keyEnv: "XAI_API_KEY" },
+  { id: "moondream", baseUrl: "https://api.moondream.ai/v1", protocol: "openai", keyEnv: "MOONDREAM_API_KEY" },
+  { id: "vllm", baseUrl: "http://127.0.0.1:8000/v1", protocol: "openai", keyEnv: "VLLM_API_KEY" },
+];
+
+// ---------- files ----------
+
+/** one providers.json entry as written: baseUrl required, protocol may be omitted (inferred on read) */
+export interface ProviderEntry extends Partial<Omit<ProviderSpec, "id" | "baseUrl">> { baseUrl: string }
+
+export interface ProvidersFile {
+  default?: string;
+  providers?: Record<string, ProviderEntry>;
+}
+
+export type FileScope = "user" | "project";
+
+export function userProvidersPath(): string { return join(rovecodeHome(), "providers.json"); }
+export function projectProvidersPath(cwd: string): string { return join(cwd, ".rovecode", "providers.json"); }
+export function providersPathFor(scope: FileScope, cwd: string): string {
+  return scope === "project" ? projectProvidersPath(cwd) : userProvidersPath();
+}
+
+/** ids are lowercase slugs — they name env vars (keyNameFor) and appear in "provider/model" selectors */
+export const PROVIDER_ID_RE = /^[a-z0-9][a-z0-9_.-]{0,39}$/;
+const ENV_NAME_RE = /^[A-Z_][A-Z0-9_]*$/;
+
+export function inferProtocol(baseUrl: string): ProviderProtocol {
+  return baseUrl.includes("anthropic.com") ? "anthropic" : "openai";
+}
+
+/** Validate one provider entry (file entry or CLI/tool input) into a spec. Pure; never throws. */
+export function validateSpec(id: string, raw: unknown): { spec: ProviderSpec } | { error: string } {
+  if (!PROVIDER_ID_RE.test(id)) return { error: `provider id "${id}" must be a lowercase slug (a-z 0-9 _ . -), at most 40 chars` };
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return { error: `provider "${id}": entry must be an object` };
+  const r = raw as Record<string, unknown>;
+  const baseUrl = typeof r["baseUrl"] === "string" ? r["baseUrl"].trim().replace(/\/+$/, "") : "";
+  if (!/^https?:\/\/[^\s/]+/.test(baseUrl)) return { error: `provider "${id}": baseUrl must be an http(s) URL` };
+  const protocol = r["protocol"] === undefined ? inferProtocol(baseUrl) : r["protocol"];
+  if (protocol !== "openai" && protocol !== "anthropic") return { error: `provider "${id}": protocol must be "openai" or "anthropic"` };
+  const spec: ProviderSpec = { id, baseUrl, protocol };
+  if (r["keyEnv"] !== undefined) {
+    if (typeof r["keyEnv"] !== "string" || !ENV_NAME_RE.test(r["keyEnv"])) return { error: `provider "${id}": keyEnv must be an ENV_VAR_NAME` };
+    spec.keyEnv = r["keyEnv"];
+  }
+  if (r["defaultModel"] !== undefined) {
+    if (typeof r["defaultModel"] !== "string" || r["defaultModel"].trim().length === 0) return { error: `provider "${id}": defaultModel must be a non-empty string` };
+    spec.defaultModel = r["defaultModel"].trim();
+  }
+  if (r["models"] !== undefined) {
+    if (!Array.isArray(r["models"]) || !r["models"].every((m) => typeof m === "string" && m.trim().length > 0)) return { error: `provider "${id}": models must be a list of model ids` };
+    spec.models = (r["models"] as string[]).map((m) => m.trim());
+  }
+  if (r["headers"] !== undefined) {
+    const h = r["headers"];
+    if (typeof h !== "object" || h === null || Array.isArray(h) || !Object.values(h as Record<string, unknown>).every((v) => typeof v === "string")) return { error: `provider "${id}": headers must be an object of strings` };
+    spec.headers = { ...(h as Record<string, string>) };
+  }
+  if (r["noKey"] !== undefined) {
+    if (typeof r["noKey"] !== "boolean") return { error: `provider "${id}": noKey must be true or false` };
+    if (r["noKey"]) spec.noKey = true;
+  }
+  return { spec };
+}
+
+/** Read one providers.json: a missing file is {} silently; a corrupt file or a malformed entry is
+ *  dropped with a warning, never fatal (auth.ts loadCredentials idiom). */
+export function readProvidersFile(path: string): { data: ProvidersFile; warnings: string[] } {
+  let text: string;
+  try { text = readFileSync(path, "utf8"); } catch { return { data: {}, warnings: [] }; }
+  let parsed: unknown;
+  try { parsed = JSON.parse(text); } catch { return { data: {}, warnings: [`${path}: invalid JSON — ignored`] }; }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return { data: {}, warnings: [`${path}: expected an object — ignored`] };
+  const o = parsed as Record<string, unknown>;
+  const data: ProvidersFile = {};
+  const warnings: string[] = [];
+  if (o["default"] !== undefined) {
+    if (typeof o["default"] === "string" && o["default"].trim().length > 0) data.default = o["default"].trim();
+    else warnings.push(`${path}: "default" must be "provider/model" — ignored`);
+  }
+  if (o["providers"] !== undefined) {
+    const p = o["providers"];
+    if (typeof p !== "object" || p === null || Array.isArray(p)) warnings.push(`${path}: "providers" must be an object — ignored`);
+    else {
+      data.providers = {};
+      for (const [id, raw] of Object.entries(p as Record<string, unknown>)) {
+        const v = validateSpec(id, raw);
+        if ("error" in v) { warnings.push(`${path}: ${v.error} — ignored`); continue; }
+        const { id: _id, ...rest } = v.spec;
+        data.providers[id] = rest;
+      }
+    }
+  }
+  return { data, warnings };
+}
+
+export function writeProvidersFile(path: string, data: ProvidersFile): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
+}
+
+// ---------- merge ----------
+
+export interface ProviderSnapshot {
+  /** builtins in table order, then file-only providers in file order, then the env "custom" provider */
+  providers: ResolvedProvider[];
+  /** the `default` selector — project file beats user file */
+  defaultSelector?: string;
+  defaultScope?: FileScope;
+  warnings: string[];
+}
+
+export function resolveKey(spec: ProviderSpec, scope: ProviderScope, env: NodeJS.ProcessEnv, creds: Record<string, StoredCredential>): ResolvedProvider {
+  const keyEnv = spec.keyEnv ?? keyNameFor(spec.id);
+  const stored = creds[spec.id]?.key;
+  if (stored !== undefined && stored.trim().length > 0) return { ...spec, keyEnv, scope, apiKey: stored, keySource: "stored" };
+  const fromEnv = env[keyEnv];
+  if (fromEnv !== undefined && fromEnv.trim().length > 0) return { ...spec, keyEnv, scope, apiKey: fromEnv, keySource: "env" };
+  return { ...spec, keyEnv, scope, apiKey: null, keySource: "none" };
+}
+
+/** The ROVECODE_BASE_URL/ROVECODE_API_KEY pair (ROVECODE_API_KEY falls back to OPENAI_API_KEY, as before). */
+export function envCustomProvider(env: NodeJS.ProcessEnv): ResolvedProvider | null {
+  const base = env["ROVECODE_BASE_URL"];
+  const key = env["ROVECODE_API_KEY"] ?? env["OPENAI_API_KEY"];
+  if (!base || !key) return null;
+  return {
+    id: "custom", baseUrl: base, protocol: inferProtocol(base), keyEnv: "ROVECODE_API_KEY", scope: "env", apiKey: key, keySource: "inline",
+    ...(env["ROVECODE_MODEL"] ? { defaultModel: env["ROVECODE_MODEL"] } : {}),
+  };
+}
+
+export function isConfigured(p: ResolvedProvider): boolean {
+  return p.apiKey !== null || p.noKey === true;
+}
+
+export function buildSnapshot(cwd: string, env: NodeJS.ProcessEnv = process.env): ProviderSnapshot {
+  const warnings: string[] = [];
+  const order: string[] = [];
+  const specs = new Map<string, { spec: ProviderSpec; scope: ProviderScope }>();
+  for (const b of BUILTIN_PROVIDERS) { specs.set(b.id, { spec: b, scope: "builtin" }); order.push(b.id); }
+  let defaultSelector: string | undefined;
+  let defaultScope: FileScope | undefined;
+  const layer = (path: string, scope: FileScope): void => {
+    const { data, warnings: w } = readProvidersFile(path);
+    warnings.push(...w);
+    for (const [id, rest] of Object.entries(data.providers ?? {})) {
+      const prev = specs.get(id);
+      specs.set(id, { spec: { ...(prev?.spec ?? {}), ...rest, id } as ProviderSpec, scope });
+      if (prev === undefined) order.push(id);
+    }
+    if (data.default !== undefined) { defaultSelector = data.default; defaultScope = scope; }
+  };
+  layer(userProvidersPath(), "user");
+  layer(projectProvidersPath(cwd), "project");
+  const creds = loadCredentials();
+  const providers = order.map((id) => { const e = specs.get(id)!; return resolveKey(e.spec, e.scope, env, creds); });
+  const custom = envCustomProvider(env);
+  if (custom) providers.push(custom);
+  return { providers, ...(defaultSelector !== undefined ? { defaultSelector, defaultScope } : {}), warnings };
+}
+
+// ---------- selection ----------
+
+export interface Selection { provider: string; model?: string }
+
+/** "provider/model" split on the FIRST slash so model ids keep their own slashes; a bare id is a provider. */
+export function parseSelector(selector: string): Selection {
+  const s = selector.trim();
+  const i = s.indexOf("/");
+  if (i <= 0) return { provider: s };
+  const model = s.slice(i + 1).trim();
+  return model.length > 0 ? { provider: s.slice(0, i), model } : { provider: s.slice(0, i) };
+}
+
+export interface DefaultPick { provider: ResolvedProvider; model?: string; via: "env-pair" | "default" | "stored" | "env-key" | "no-key" }
+
+/** The default provider (+ its model, when one is known WITHOUT env ROVECODE_MODEL — callers layer
+ *  that on top): env pair > file `default` (when that provider is configured) > first stored
+ *  credential in order > first env key in order > first keyless file provider > null. The first
+ *  three ranks are resolveProvider()'s historical precedence, pinned by test/unit/auth.test.ts. */
+export function pickDefault(snap: ProviderSnapshot): DefaultPick | null {
+  const custom = snap.providers.find((p) => p.scope === "env");
+  if (custom) return { provider: custom, model: custom.defaultModel, via: "env-pair" };
+  if (snap.defaultSelector !== undefined) {
+    const sel = parseSelector(snap.defaultSelector);
+    const p = snap.providers.find((x) => x.id === sel.provider);
+    if (p && isConfigured(p)) return { provider: p, model: sel.model ?? p.defaultModel, via: "default" };
+  }
+  const stored = snap.providers.find((p) => p.keySource === "stored");
+  if (stored) return { provider: stored, model: stored.defaultModel, via: "stored" };
+  const fromEnv = snap.providers.find((p) => p.keySource === "env");
+  if (fromEnv) return { provider: fromEnv, model: fromEnv.defaultModel, via: "env-key" };
+  const noKey = snap.providers.find((p) => p.noKey === true);
+  if (noKey) return { provider: noKey, model: noKey.defaultModel, via: "no-key" };
+  return null;
+}
+
+// ---------- live view (hot reload) ----------
+
+export class ProviderConfig {
+  private snap: ProviderSnapshot | null = null;
+  private stamp = "";
+  private checkedAt = -Infinity;
+  private readonly listeners = new Set<(snap: ProviderSnapshot) => void>();
+
+  constructor(
+    private readonly cwd: string,
+    private readonly env: NodeJS.ProcessEnv = process.env,
+    private readonly throttleMs = 250,
+  ) {}
+
+  /** the files whose mtime/size drive reloads */
+  sourcePaths(): string[] { return [userProvidersPath(), projectProvidersPath(this.cwd), credentialsPath()]; }
+
+  private stampNow(): string {
+    return this.sourcePaths().map((p) => { try { const s = statSync(p); return `${s.mtimeMs}:${s.size}`; } catch { return "-"; } }).join("|");
+  }
+
+  /** Current merged view. Re-reads when a source file changed (checked at most every throttleMs);
+   *  listeners fire on every rebuild after the first. */
+  snapshot(): ProviderSnapshot {
+    const now = Date.now();
+    if (this.snap !== null && now - this.checkedAt < this.throttleMs) return this.snap;
+    this.checkedAt = now;
+    const stamp = this.stampNow();
+    if (this.snap === null || stamp !== this.stamp) {
+      const first = this.snap === null;
+      this.stamp = stamp;
+      this.snap = buildSnapshot(this.cwd, this.env);
+      if (!first) for (const cb of this.listeners) cb(this.snap);
+    }
+    return this.snap;
+  }
+
+  /** Force a re-read on the next snapshot() (in-process writers call this right after writing). */
+  invalidate(): void { this.checkedAt = -Infinity; this.stamp = ""; }
+
+  onChange(cb: (snap: ProviderSnapshot) => void): () => void {
+    this.listeners.add(cb);
+    return () => { this.listeners.delete(cb); };
+  }
+}