niahere 0.4.6 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niahere",
-  "version": "0.4.6",
+  "version": "0.5.1",
   "description": "A personal AI assistant daemon — chat, scheduled jobs, persona system, extensible via skills.",
   "type": "module",
   "scripts": {
@@ -13,7 +13,7 @@
     "typecheck": "tsc --noEmit",
     "check:cycles": "madge --circular --extensions ts src/",
     "seed": "bun run src/db/seed.ts",
-    "release": "npm version patch && npm publish && git push"
+    "release": "npm version patch && npm publish && git push --follow-tags"
   },
   "keywords": [
     "ai",

package/src/agent/backends/claude-normalize.ts

@@ -1,6 +1,6 @@
 import type { AgentEvent, Normalizer } from "../types";
 import { truncate } from "../../utils/format-activity";
-import { isRetryableApiError, isProviderDownError } from "../../utils/retry";
+import { isRetryable, scopeOf, parseFailure } from "../failure";
 
 /**
  * Pure reducer: Claude Agent SDK messages → normalized `AgentEvent`s.
@@ -120,14 +120,13 @@ export class SdkNormalizer implements Normalizer {
       };
     }
     const raw = (msg.errors?.join(", ") as string) || "unknown error";
-    // Two INDEPENDENT predicates from the same raw string:
-    //  - retryable: transient API failure → the session may retry internally.
-    //  - providerDown: blank/"unknown error" → the provider is down → failover.
+    // A transient error carries no scope yet — it only becomes one once the
+    // session has burned its retries.
     return {
       type: "error",
       message: raw,
-      retryable: isRetryableApiError(raw),
-      providerDown: isProviderDownError(raw),
+      retryable: isRetryable(raw),
+      failover: scopeOf(parseFailure(raw), "provider"),
       terminalReason: msg.terminal_reason,
     };
   }

package/src/agent/backends/claude.ts

@@ -1,4 +1,5 @@
 import { query } from "@anthropic-ai/claude-agent-sdk";
+import { asError } from "../../utils/errors";
 import { randomUUID } from "crypto";
 import { existsSync } from "fs";
 import { join } from "path";
@@ -126,7 +127,7 @@ class ClaudeSession implements AgentSession {
           res = await this.iterator!.next();
         } catch (err) {
           if (this.aborted) throw new Error(this.aborted);
-          throw err instanceof Error ? err : new Error(String(err));
+          throw asError(err);
         }
         if (this.aborted) throw new Error(this.aborted);
         if (res.done) {
@@ -151,11 +152,12 @@ class ClaudeSession implements AgentSession {
             retry = true;
             break;
           }
-          // A retryable error that survived all our retries means the provider is
-          // effectively down for us — flag it so the consumer can fail over.
+          // A retryable error that survived every retry is a capacity problem
+          // with THIS model, not proof the provider is gone — scope it to the
+          // model so a second model on the same provider still gets its turn.
           const out =
             ev.type === "error" && ev.retryable && this.retryCount >= MAX_SEND_RETRIES
-              ? { ...ev, providerDown: true }
+              ? { ...ev, failover: ev.failover ?? ("model" as const) }
               : ev;
           yield out;
           if (out.type === "result" || out.type === "error") {

package/src/agent/backends/codex-normalize.ts

@@ -1,5 +1,6 @@
 import type { AgentEvent, Normalizer } from "../types";
 import { truncate } from "../../utils/format-activity";
+import { scopeOf, parseFailure } from "../failure";
 
 /**
  * Pure reducer: Codex `codex exec --json` JSONL events → normalized `AgentEvent`s.
@@ -7,13 +8,15 @@ import { truncate } from "../../utils/format-activity";
  * Codex is batch (no token streaming): the assistant message arrives whole in a
  * single `item.completed`/`agent_message`, and `turn.completed` carries token
  * usage. So `text` is emitted once (full), then `result` on `turn.completed`.
- * No I/O — the session that drives it owns process lifecycle. Real errors are
- * detected from the process exit code by the session, not here (Codex `error`
- * items are often non-fatal warnings).
+ * No I/O — the session that drives it owns process lifecycle. A failed turn
+ * arrives as a top-level `error` and/or `turn.failed` carrying the upstream
+ * message; `error` *items* are non-fatal warnings (service tier, model metadata,
+ * skill budget) and are dropped.
  */
 export class CodexNormalizer implements Normalizer {
   private threadId = "";
   private agentText = "";
+  private failed = false;
 
   get backendSessionId(): string {
     return this.threadId;
@@ -28,6 +31,10 @@ export class CodexNormalizer implements Normalizer {
       case "item.started":
       case "item.completed":
         return this.consumeItem(e.type === "item.completed", e.item);
+      case "error":
+        return this.fail(typeof e.message === "string" ? e.message : "");
+      case "turn.failed":
+        return this.fail(typeof e.error?.message === "string" ? e.error.message : "");
       case "turn.completed":
         return [
           {
@@ -47,6 +54,15 @@ export class CodexNormalizer implements Normalizer {
     }
   }
 
+  /** Codex reports the same failure twice (`error` then `turn.failed`); only the
+   *  first ends the turn. */
+  private fail(raw: string): AgentEvent[] {
+    if (this.failed) return [];
+    this.failed = true;
+    const failure = parseFailure(raw);
+    return [{ type: "error", message: failure.message, retryable: false, failover: scopeOf(failure) }];
+  }
+
   private consumeItem(completed: boolean, item: any): AgentEvent[] {
     if (!item) return [];
     switch (item.type) {

package/src/agent/backends/codex.ts

@@ -6,7 +6,8 @@ import type { Attachment } from "../../types/attachment";
 import type { McpSourceContext } from "../../mcp";
 import { CodexNormalizer } from "./codex-normalize";
 import { mintRun, revokeRun } from "../mcp-endpoint";
-import { isCliProviderDownError } from "../../utils/retry";
+import { scopeOf, parseFailure } from "../failure";
+import { ignore } from "../../utils/errors";
 
 /**
  * Resolve the codex binary's absolute path. The daemon runs under launchd with a
@@ -42,21 +43,30 @@ export interface CliProc {
 }
 export type SpawnFn = (args: string[], opts: { cwd: string; env: Record<string, string> }) => CliProc;
 
-// Nia secrets that must never reach a third-party agent subprocess. Codex
-// authenticates via its own ~/.codex login, not these.
-const SCRUB = new Set([
-  "ANTHROPIC_API_KEY",
-  "SLACK_BOT_TOKEN",
-  "SLACK_APP_TOKEN",
-  "TELEGRAM_BOT_TOKEN",
-  "TWILIO_AUTH_TOKEN",
-  "DATABASE_URL",
+// An allowlist, so a newly-added secret is excluded by default rather than
+// leaking to a third-party subprocess. Codex authenticates via its own
+// ~/.codex login, so it needs no credential of ours.
+const ENV_ALLOW = new Set([
+  "PATH",
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "TERM",
+  "TMPDIR",
+  "TZ",
+  "LANG",
+  "XDG_CONFIG_HOME",
+  "XDG_CACHE_HOME",
+  "XDG_DATA_HOME",
 ]);
+const ENV_ALLOW_PREFIX = ["LC_", "CODEX_"];
 
-function scrubbedEnv(extra: Record<string, string>): Record<string, string> {
+function subprocessEnv(extra: Record<string, string>): Record<string, string> {
   const env: Record<string, string> = {};
   for (const [k, v] of Object.entries(process.env)) {
-    if (!SCRUB.has(k) && v != null) env[k] = v;
+    if (v == null) continue;
+    if (ENV_ALLOW.has(k) || ENV_ALLOW_PREFIX.some((p) => k.startsWith(p))) env[k] = v;
   }
   return { ...env, ...extra };
 }
@@ -76,8 +86,9 @@ function defaultSpawn(args: string[], opts: { cwd: string; env: Record<string, s
   };
 }
 
-async function* readLines(stream: ReadableStream<Uint8Array>): AsyncGenerator<string> {
-  const reader = stream.getReader();
+/** Takes the reader rather than the stream so the caller can cancel a read that
+ *  would otherwise never resolve. */
+async function* readLines(reader: ReadableStreamDefaultReader<Uint8Array>): AsyncGenerator<string> {
   const decoder = new TextDecoder();
   let buf = "";
   while (true) {
@@ -93,28 +104,53 @@ async function* readLines(stream: ReadableStream<Uint8Array>): AsyncGenerator<st
   if (buf.trim()) yield buf;
 }
 
-async function readAll(stream: ReadableStream<Uint8Array>): Promise<string> {
-  let out = "";
-  const decoder = new TextDecoder();
-  const reader = stream.getReader();
-  while (true) {
-    const { value, done } = await reader.read();
-    if (done) break;
-    out += decoder.decode(value, { stream: true });
-  }
-  return out;
+const IDLE = Symbol("idle");
+
+/** A cancellable deadline, used to race a read that may never resolve. */
+function idleAfter(ms: number): { promise: Promise<typeof IDLE>; cancel: () => void } {
+  let timer: ReturnType<typeof setTimeout>;
+  const promise = new Promise<typeof IDLE>((resolve) => {
+    timer = setTimeout(() => resolve(IDLE), ms);
+  });
+  return { promise, cancel: () => clearTimeout(timer) };
+}
+
+const STDERR_CAP = 16_000;
+
+/**
+ * Consume stderr to EOF, keeping only the tail. Must run alongside the process:
+ * an undrained pipe blocks the child once its buffer fills.
+ */
+function drainStderr(stream: ReadableStream<Uint8Array>): Promise<string> {
+  return (async () => {
+    let out = "";
+    const decoder = new TextDecoder();
+    const reader = stream.getReader();
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      out += decoder.decode(value, { stream: true });
+      if (out.length > STDERR_CAP) out = out.slice(-STDERR_CAP);
+    }
+    return out;
+  })().catch(() => "");
 }
 
+/** A codex that emits nothing for this long is wedged, not working. */
+const DEFAULT_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
+
 export class CodexBackend implements AgentBackend {
   readonly name = "codex" as const;
   private spawnFn: SpawnFn;
+  private idleTimeoutMs: number;
 
-  constructor(deps?: { spawnFn?: SpawnFn }) {
+  constructor(deps?: { spawnFn?: SpawnFn; idleTimeoutMs?: number }) {
     this.spawnFn = deps?.spawnFn ?? defaultSpawn;
+    this.idleTimeoutMs = deps?.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
   }
 
   async openSession(ctx: AgentSessionContext): Promise<AgentSession> {
-    return new CodexSession(ctx, this.spawnFn);
+    return new CodexSession(ctx, this.spawnFn, this.idleTimeoutMs);
   }
 
   async canResume(): Promise<boolean> {
@@ -127,10 +163,12 @@ class CodexSession implements AgentSession {
   private _sessionId: string | null = null;
   private aborted: string | null = null;
   private proc: CliProc | null = null;
+  private idledOut = false;
 
   constructor(
     private ctx: AgentSessionContext,
     private spawnFn: SpawnFn,
+    private idleTimeoutMs: number,
   ) {}
 
   get backendSessionId(): string | null {
@@ -157,15 +195,32 @@ class CodexSession implements AgentSession {
     ];
     if (this.ctx.model && this.ctx.model !== "default") args.push("-m", this.ctx.model);
 
-    const proc = this.spawnFn(args, { cwd: this.ctx.cwd, env: scrubbedEnv({ NIA_MCP_TOKEN: token }) });
+    const proc = this.spawnFn(args, { cwd: this.ctx.cwd, env: subprocessEnv({ NIA_MCP_TOKEN: token }) });
     this.proc = proc;
 
+    // Started now, not after exit: an undrained pipe blocks the child.
+    const stderr = drainStderr(proc.stderr);
+
     const normalizer = new CodexNormalizer();
-    let sawResult = false;
+    const stdout = proc.stdout.getReader();
+    const lines = readLines(stdout)[Symbol.asyncIterator]();
+    let sawTerminal = false;
     try {
-      for await (const line of readLines(proc.stdout)) {
+      while (true) {
+        // Race the read rather than trusting kill() to close the pipe — a child
+        // that ignores the signal would otherwise hang the run forever.
+        const idle = idleAfter(this.idleTimeoutMs);
+        const next = await Promise.race([lines.next(), idle.promise]);
+        idle.cancel();
+        if (next === IDLE) {
+          this.idledOut = true;
+          proc.kill();
+          break;
+        }
+        if (next.done) break;
+
         if (this.aborted) throw new Error(this.aborted);
-        const trimmed = line.trim();
+        const trimmed = next.value.trim();
         if (!trimmed) continue;
         let parsed: unknown;
         try {
@@ -177,22 +232,32 @@ class CodexSession implements AgentSession {
           if (ev.type === "session" || ev.type === "result") {
             this._sessionId = ev.backendSessionId || this._sessionId;
           }
-          if (ev.type === "result") sawResult = true;
+          if (ev.type === "result" || ev.type === "error") sawTerminal = true;
           yield ev;
         }
       }
+      if (this.idledOut) {
+        yield {
+          type: "error",
+          message: `codex produced no output for ${Math.round(this.idleTimeoutMs / 1000)}s`,
+          retryable: false,
+          failover: "provider",
+        };
+        return;
+      }
       const exit = await proc.exited;
       if (this.aborted) throw new Error(this.aborted);
-      if (exit !== 0 && !sawResult) {
-        const stderr = await readAll(proc.stderr);
+      if (exit !== 0 && !sawTerminal) {
+        const text = await stderr;
         yield {
           type: "error",
-          message: stderr.trim() || `codex exited ${exit}`,
+          message: text.trim() || `codex exited ${exit}`,
           retryable: false,
-          providerDown: isCliProviderDownError(stderr),
+          failover: scopeOf(parseFailure(text), "provider"),
         };
       }
     } finally {
+      await ignore(stdout.cancel(), "cancel codex stdout reader");
       revokeRun(token);
       this.proc = null;
     }

package/src/agent/chain.ts

@@ -0,0 +1,60 @@
+import type { AgentBackend, FailoverScope } from "./types";
+import { providerHealth, type ProviderHealth } from "./health";
+
+/** One attempt: a backend paired with the model to run it on. */
+export interface ChainEntry {
+  backend: AgentBackend;
+  /** Absent → let the backend pick its own default. */
+  model?: string;
+}
+
+/** `provider:model` for logs. */
+export function describeEntry(entry: ChainEntry): string {
+  return `${entry.backend.name}:${entry.model ?? "default"}`;
+}
+
+/**
+ * Walks the resolved chain. A model-scoped failure advances one entry — possibly
+ * the same provider on another model; a provider-scoped one writes that provider
+ * off for the rest of the run.
+ */
+export class ChainCursor {
+  private index: number;
+  private readonly down = new Set<string>();
+
+  constructor(
+    private readonly chain: ChainEntry[],
+    private readonly health: ProviderHealth = providerHealth,
+  ) {
+    // Skip a provider that recently failed, but never strand the run: if every
+    // provider is cooling down, start at the head and let it try.
+    const usable = chain.findIndex((e) => !health.isDown(e.backend.name));
+    this.index = usable === -1 ? 0 : usable;
+  }
+
+  get current(): ChainEntry | undefined {
+    return this.chain[this.index];
+  }
+
+  get atHead(): boolean {
+    return this.index === 0;
+  }
+
+  /** Position in the chain, for deciding whether a fresh cursor would differ. */
+  get entry(): ChainEntry | undefined {
+    return this.chain[this.index];
+  }
+
+  /** Record the failure and move on. Undefined when nothing usable is left. */
+  advance(scope: FailoverScope): ChainEntry | undefined {
+    if (scope === "provider") {
+      const name = this.chain[this.index]!.backend.name;
+      this.down.add(name);
+      this.health.markDown(name);
+    }
+    const next = this.chain.findIndex((e, i) => i > this.index && !this.down.has(e.backend.name));
+    if (next === -1) return undefined;
+    this.index = next;
+    return this.chain[next];
+  }
+}

package/src/agent/failure.ts

@@ -0,0 +1,90 @@
+import type { FailoverScope } from "./types";
+
+/**
+ * Failure classification shared by every backend adapter.
+ *
+ * Prefer the structured signal. Agents talk about logins, credentials and API
+ * keys all day, and the codex binary bundles an AWS SDK that mentions them too,
+ * so prose is only consulted when there is no HTTP status to go on — and the
+ * patterns that read prose are anchored to failure wording rather than to the
+ * bare nouns.
+ */
+
+const RETRYABLE = [/\b500\b/i, /internal server error/i, /overloaded/i, /529/, /rate limit/i];
+
+const MODEL_SCOPED = [
+  /model .*not (found|supported|available|allowed)/i,
+  /(unknown|invalid|unsupported) model/i,
+  /model .*(does not exist|is not supported)/i,
+  /context ?window ?exceeded/i,
+];
+
+const PROVIDER_SCOPED = [
+  /not logged in/i,
+  /failed to (authenticate|authorize)/i,
+  /(authentication|authorization) (failed|required|error)/i,
+  /\b(authorizationfailed|authorizationrequired|noauthorizationsupport)\b/i,
+  /failed to (load|refresh)\b.{0,40}\b(credential|token|auth)/i,
+  /(session|token|refresh token|credentials) (has |have )?expired/i,
+  /\b(tokenexpired|tokenrefreshfailed|refreshtokenfailed|tokenexchangefailed)\b/i,
+  /invalid (api[ -]?key|credentials|token)/i,
+  /\b(401 unauthorized|403 forbidden)\b/i,
+  /\bstatus:? (401|403)\b/i,
+  /(usage limit reached|quota exceeded)/i,
+  /\b(usagelimitreached|quotaexceeded)\b/i,
+  /\b(econnrefused|enotfound|etimedout|econnreset)\b/i,
+  /connection (refused|reset|timed out)/i,
+  /network (error|unreachable)/i,
+  /failed to refresh available models/i,
+];
+
+export interface Failure {
+  message: string;
+  /** HTTP status, when the backend reported a structured error. */
+  status?: number;
+  /** Provider's own error type, e.g. `invalid_request_error`. */
+  type?: string;
+}
+
+/** Unwrap a JSON error envelope; plain text passes through. */
+export function parseFailure(raw: string | null | undefined): Failure {
+  const text = (raw ?? "").trim();
+  try {
+    const parsed = JSON.parse(text);
+    const inner = parsed?.error?.message ?? parsed?.message;
+    return {
+      message: typeof inner === "string" && inner.trim() ? inner : text,
+      status: typeof parsed?.status === "number" ? parsed.status : undefined,
+      type: typeof parsed?.error?.type === "string" ? parsed.error.type : undefined,
+    };
+  } catch {
+    return { message: text };
+  }
+}
+
+/** Transient enough for the backend to retry in place. */
+export function isRetryable(text: string | null | undefined): boolean {
+  const t = text?.trim();
+  return !!t && RETRYABLE.some((p) => p.test(t));
+}
+
+function scopeOfStatus(status: number, message: string): FailoverScope | undefined {
+  if (status === 404) return "model";
+  if (status === 401 || status === 403 || status === 408 || status === 429 || status >= 500) return "provider";
+  if (MODEL_SCOPED.some((p) => p.test(message))) return "model";
+  return undefined;
+}
+
+/**
+ * How far the chain should skip. `blank` is what an empty or opaque message
+ * implies: a run that reported nothing points at the provider, a structured
+ * error that merely lacks a message does not.
+ */
+export function scopeOf(failure: Failure, blank?: FailoverScope): FailoverScope | undefined {
+  const t = failure.message.trim();
+  if (!t || t.toLowerCase() === "unknown error") return blank;
+  if (failure.status !== undefined) return scopeOfStatus(failure.status, t);
+  if (MODEL_SCOPED.some((p) => p.test(t))) return "model";
+  if (PROVIDER_SCOPED.some((p) => p.test(t))) return "provider";
+  return undefined;
+}

package/src/agent/health.ts

@@ -0,0 +1,41 @@
+/**
+ * Process-wide provider cooldown. Without it every job and every chat turn
+ * re-discovers the same outage from scratch, paying the full retry ladder before
+ * failing over; with it a provider that just failed is skipped until it has had
+ * time to recover, and picked up again once the cooldown lapses.
+ */
+
+const DEFAULT_COOLDOWN_MS = 5 * 60 * 1000;
+
+export interface ProviderHealth {
+  markDown(provider: string): void;
+  isDown(provider: string): boolean;
+  /** Test seam. */
+  clear(): void;
+}
+
+export function createProviderHealth(
+  cooldownMs: number = DEFAULT_COOLDOWN_MS,
+  now: () => number = Date.now,
+): ProviderHealth {
+  const downUntil = new Map<string, number>();
+  return {
+    markDown(provider) {
+      downUntil.set(provider, now() + cooldownMs);
+    },
+    isDown(provider) {
+      const until = downUntil.get(provider);
+      if (until === undefined) return false;
+      if (now() > until) {
+        downUntil.delete(provider);
+        return false;
+      }
+      return true;
+    },
+    clear() {
+      downUntil.clear();
+    },
+  };
+}
+
+export const providerHealth = createProviderHealth();

package/src/agent/index.ts

@@ -8,5 +8,7 @@ export type {
   Normalizer,
 } from "./types";
 export { isResultEvent } from "./types";
-export { getBackend, setBackend, setBackendChain, resolveBackends } from "./registry";
+export type { FailoverScope } from "./types";
+export { getBackend, setBackend, setBackendChain, resolveChain, buildChain } from "./registry";
+export { ChainCursor, describeEntry, type ChainEntry } from "./chain";
 export { resolveSdkModel } from "./backends/claude";

package/src/agent/mcp-endpoint.ts

@@ -4,6 +4,8 @@ import { randomBytes, randomUUID } from "crypto";
 import type { NiaTool } from "../mcp/tools/types";
 import type { McpSourceContext } from "../mcp";
 import { log } from "../utils/log";
+import { ignore } from "../utils/errors";
+import { gateSideEffects } from "../mcp/gate";
 
 /**
  * Loopback MCP endpoint — how out-of-process CLI backends (Codex/Gemini) reach
@@ -33,7 +35,7 @@ let endpointTools: NiaTool[] = [];
 /** Build a per-run MCP server whose tool closures bake in the frozen context. */
 function buildRunServer(ctx: McpSourceContext, tools: NiaTool[]): McpServer {
   const mcp = new McpServer({ name: "nia", version: "0.1.0" });
-  for (const t of tools) {
+  for (const t of gateSideEffects(tools)) {
     mcp.registerTool(t.name, { description: t.description, inputSchema: t.schema }, async (args: unknown) => ({
       content: [{ type: "text" as const, text: await t.handler(args, ctx) }],
     }));
@@ -92,8 +94,8 @@ export function revokeRun(token: string): void {
   const entry = runs.get(token);
   if (!entry) return;
   runs.delete(token);
-  entry.transport.close().catch(() => {});
-  entry.server.close().catch(() => {});
+  void ignore(entry.transport.close(), "close run transport");
+  void ignore(entry.server.close(), "close run server");
 }
 
 /** Test/diagnostic: number of live runs. */

package/src/agent/models.ts

@@ -0,0 +1,59 @@
+import type { BackendName } from "../types/config";
+
+/** Model → provider resolution. Config names models, never backends, so one
+ *  provider's model id can never reach another. */
+
+export type ProviderName = BackendName;
+
+export interface ModelRef {
+  provider: ProviderName;
+  /** Absent → let the provider pick. */
+  model?: string;
+}
+
+/** Order of the implicit cross-provider tail. */
+export const PROVIDER_ORDER: readonly ProviderName[] = ["claude", "codex", "gemini"];
+
+/** Selects a provider without naming a model. */
+const BARE_PROVIDERS: Record<string, ProviderName> = {
+  default: "claude",
+  claude: "claude",
+  codex: "codex",
+  gemini: "gemini",
+};
+
+/** Short names the provider understands directly. */
+const ALIASES: Record<string, ProviderName> = {
+  sonnet: "claude",
+  opus: "claude",
+  opusplan: "claude",
+  haiku: "claude",
+};
+
+const PREFIXES: [RegExp, ProviderName][] = [
+  [/^claude[-.]/, "claude"],
+  [/^(gpt|o[134]|codex)[-.]/, "codex"],
+  [/^gemini[-.]/, "gemini"],
+];
+
+/** Unrecognized names are assumed to be Claude's — a rejected model is a
+ *  model-scoped failure, so a typo degrades to the next entry. */
+export function resolveModel(name: string): ModelRef {
+  const model = name.trim();
+  const key = model.toLowerCase();
+
+  const bare = BARE_PROVIDERS[key];
+  if (bare) return { provider: bare };
+
+  const alias = ALIASES[key];
+  if (alias) return { provider: alias, model };
+
+  for (const [pattern, provider] of PREFIXES) {
+    if (pattern.test(key)) return { provider, model };
+  }
+  return { provider: "claude", model };
+}
+
+export function providerDefault(provider: ProviderName): ModelRef {
+  return { provider };
+}