niahere 0.5.4 → 0.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niahere",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "A personal AI assistant daemon — chat, scheduled jobs, persona system, extensible via skills.",
   "type": "module",
   "scripts": {
@@ -44,8 +44,8 @@
   "license": "MIT",
   "private": false,
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.220",
-    "@anthropic-ai/sdk": "0.115.0",
+    "@anthropic-ai/claude-agent-sdk": "0.3.233",
+    "@anthropic-ai/sdk": "0.117.1",
     "@modelcontextprotocol/sdk": "1.30.0",
     "@slack/bolt": "^4.6.0",
     "cron-parser": "^5.5.0",

package/src/agent/auth.ts

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import type { ProviderName } from "./models";
+
+/**
+ * Provider sign-in state, read from whatever each CLI stores on disk.
+ *
+ * The distinction that matters: an *access* token expiring is routine — it
+ * lives hours and is renewed on demand, so a daemon idle overnight legitimately
+ * holds an expired one. A *refresh* token expiring is terminal: nothing can
+ * renew it and the only fix is signing in again.
+ *
+ * Reporting the first as a failure would cry wolf nightly. Reporting neither is
+ * how Nia spent sixteen days answering as codex on a Claude token that expired
+ * at 22:42 on a Thursday and told nobody.
+ */
+
+export type AuthState = "ok" | "stale" | "expiring" | "expired" | "unknown";
+
+export interface AuthStatus {
+  provider: ProviderName;
+  state: AuthState;
+  detail: string;
+  /** When the short-lived access token lapses, ms epoch. */
+  accessExpiresAt?: number;
+  /** When re-authentication becomes unavoidable, ms epoch. */
+  refreshExpiresAt?: number;
+}
+
+/** Re-auth this close to being forced is worth saying out loud. */
+export const REFRESH_WARN_MS = 3 * 24 * 60 * 60 * 1000;
+
+export interface AuthReader {
+  exists: (path: string) => boolean;
+  read: (path: string) => string;
+  env: (key: string) => string | undefined;
+}
+
+const defaultReader: AuthReader = {
+  exists: existsSync,
+  read: (p) => readFileSync(p, "utf8"),
+  env: (k) => process.env[k],
+};
+
+export function claudeCredentialsPath(): string {
+  return join(homedir(), ".claude", ".credentials.json");
+}
+
+export function codexAuthPath(): string {
+  return join(process.env.CODEX_HOME || join(homedir(), ".codex"), "auth.json");
+}
+
+function ago(ms: number): string {
+  const abs = Math.abs(ms);
+  const hours = abs / 3_600_000;
+  if (hours < 1) return `${Math.round(abs / 60_000)}m`;
+  if (hours < 48) return `${hours.toFixed(1)}h`;
+  return `${Math.round(hours / 24)}d`;
+}
+
+export function claudeAuthStatus(now: number = Date.now(), reader: AuthReader = defaultReader): AuthStatus {
+  const base = { provider: "claude" as const };
+
+  if (reader.env("ANTHROPIC_API_KEY")) {
+    return { ...base, state: "ok", detail: "API key (no expiry)" };
+  }
+
+  const path = claudeCredentialsPath();
+  if (!reader.exists(path)) {
+    // macOS can keep these in the Keychain instead, which a background daemon
+    // must not prompt for. Saying "unknown" beats guessing "broken".
+    return { ...base, state: "unknown", detail: "no credentials file (keychain, or not signed in)" };
+  }
+
+  let oauth: Record<string, unknown>;
+  try {
+    oauth = (JSON.parse(reader.read(path)) as Record<string, Record<string, unknown>>).claudeAiOauth ?? {};
+  } catch {
+    return { ...base, state: "unknown", detail: "credentials file is not readable JSON" };
+  }
+
+  const access = typeof oauth.expiresAt === "number" ? oauth.expiresAt : undefined;
+  const refresh = typeof oauth.refreshTokenExpiresAt === "number" ? oauth.refreshTokenExpiresAt : undefined;
+  const plan = typeof oauth.subscriptionType === "string" ? ` (${oauth.subscriptionType})` : "";
+  const status = { ...base, accessExpiresAt: access, refreshExpiresAt: refresh };
+
+  if (refresh !== undefined && refresh <= now) {
+    return { ...status, state: "expired", detail: `sign-in expired ${ago(now - refresh)} ago — run \`claude\` to sign in again` };
+  }
+  if (refresh !== undefined && refresh - now < REFRESH_WARN_MS) {
+    return { ...status, state: "expiring", detail: `sign-in must be renewed within ${ago(refresh - now)}${plan}` };
+  }
+  if (access !== undefined && access <= now) {
+    // Routine on its own. It only means something alongside a chain that has
+    // stopped using this provider, which the failover check supplies.
+    return { ...status, state: "stale", detail: `access token lapsed ${ago(now - access)} ago, renewable${plan}` };
+  }
+  if (access !== undefined) {
+    return { ...status, state: "ok", detail: `valid for ${ago(access - now)}${plan}` };
+  }
+  return { ...status, state: "unknown", detail: "credentials file carries no expiry" };
+}
+
+export function codexAuthStatus(now: number = Date.now(), reader: AuthReader = defaultReader): AuthStatus {
+  const base = { provider: "codex" as const };
+  const path = codexAuthPath();
+  if (!reader.exists(path)) return { ...base, state: "unknown", detail: "not signed in" };
+
+  let auth: Record<string, unknown>;
+  try {
+    auth = JSON.parse(reader.read(path)) as Record<string, unknown>;
+  } catch {
+    return { ...base, state: "unknown", detail: "auth file is not readable JSON" };
+  }
+
+  if (typeof auth.OPENAI_API_KEY === "string" && auth.OPENAI_API_KEY) {
+    return { ...base, state: "ok", detail: "API key (no expiry)" };
+  }
+
+  const tokens = (auth.tokens ?? {}) as Record<string, unknown>;
+  const exp = jwtExpiry(typeof tokens.id_token === "string" ? tokens.id_token : undefined);
+  const mode = typeof auth.auth_mode === "string" ? auth.auth_mode : "oauth";
+  if (exp === undefined) return { ...base, state: "unknown", detail: `${mode} sign-in, no readable expiry` };
+  if (exp <= now) return { ...base, state: "stale", detail: `${mode} token lapsed ${ago(now - exp)} ago, renewable` };
+  return { ...base, state: "ok", detail: `${mode}, valid for ${ago(exp - now)}` };
+}
+
+/** `exp` out of a JWT payload, in ms. Signature is irrelevant here — we are
+ *  reading our own stored token, not trusting one. */
+export function jwtExpiry(token: string | undefined): number | undefined {
+  const payload = token?.split(".")[1];
+  if (!payload) return undefined;
+  try {
+    const json = JSON.parse(Buffer.from(payload.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8"));
+    return typeof json.exp === "number" ? json.exp * 1000 : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function authStatusFor(provider: ProviderName, now?: number, reader?: AuthReader): AuthStatus {
+  if (provider === "codex") return codexAuthStatus(now, reader);
+  if (provider === "claude") return claudeAuthStatus(now, reader);
+  return { provider, state: "unknown", detail: "no adapter" };
+}

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

@@ -10,13 +10,58 @@ import type { FailoverScope } from "../types";
  */
 const DEAD_TURNS: Record<string, FailoverScope | undefined> = {
   api_error: "provider",
+  // This account is out of capacity, not this model — another provider can
+  // still answer. Left unmapped, an exhausted plan reads as a completed turn.
+  blocking_limit: "provider",
+  rapid_refill_breaker: "provider",
+  // The model is the problem; the next one in the chain may not be.
+  model_error: "model",
+  prompt_too_long: "model",
   budget_exhausted: undefined,
+  // No provider will parse the image differently, so there is nothing to fail
+  // over to — stop and say so.
+  image_error: undefined,
   malformed_tool_use_exhausted: undefined,
   structured_output_retry_exhausted: undefined,
   tool_deferred_unavailable: undefined,
   turn_setup_failed: undefined,
 };
 
+/**
+ * Say as much about a failed turn as the result message allows.
+ *
+ * `errors` is routinely empty on an errored result. Collapsing that to the
+ * string "unknown error" cost sixteen days of Nia answering as Codex with 649
+ * failures that named no cause and so raised no question. Anything the message
+ * still carries beats a word that means nothing.
+ */
+export function describeFailure(msg: {
+  errors?: unknown;
+  subtype?: unknown;
+  stop_reason?: unknown;
+  terminal_reason?: unknown;
+  api_error_status?: unknown;
+  result?: unknown;
+}): string {
+  const errors = Array.isArray(msg.errors) ? msg.errors.filter((e) => typeof e === "string" && e.trim()) : [];
+  if (errors.length > 0) return errors.join(", ");
+
+  const parts: string[] = [];
+  const add = (label: string, value: unknown) => {
+    if (typeof value === "string" && value.trim()) parts.push(`${label}=${value.trim()}`);
+    else if (typeof value === "number") parts.push(`${label}=${value}`);
+  };
+  add("http", msg.api_error_status);
+  add("subtype", msg.subtype);
+  add("stop_reason", msg.stop_reason);
+  add("terminal_reason", msg.terminal_reason);
+  if (typeof msg.result === "string" && msg.result.trim()) parts.push(`result=${truncate(msg.result.trim(), 200)}`);
+
+  return parts.length > 0
+    ? `claude reported an error with no message (${parts.join(" ")})`
+    : "claude reported an error with no message and no detail";
+}
+
 /**
  * Stamp the chain's provider over the SDK's own, which names the deployment
  * target (firstParty/bedrock/vertex) — a different axis from which backend ran
@@ -156,6 +201,7 @@ export class SdkNormalizer implements Normalizer {
         usage: { costUsd: msg.total_cost_usd ?? 0, turns: msg.num_turns ?? 0 },
         backendSessionId: msg.session_id ?? "",
         terminalReason: msg.terminal_reason,
+        ...(msg.structured_output === undefined ? {} : { structured: msg.structured_output }),
         metadata: {
           cost_usd: msg.total_cost_usd,
           turns: msg.num_turns,
@@ -170,7 +216,7 @@ export class SdkNormalizer implements Normalizer {
         },
       };
     }
-    const raw = (msg.errors?.join(", ") as string) || "unknown error";
+    const raw = describeFailure(msg);
     // A transient error carries no scope yet — it only becomes one once the
     // session has burned its retries.
     return {

package/src/agent/backends/claude.ts

@@ -106,6 +106,7 @@ class ClaudeSession implements AgentSession {
       // same cwd; jobs always run with a unique id and never auto-continued.
       if (this.ctx.interactive) options.continue = false;
     }
+    if (this.ctx.outputSchema) options.outputFormat = { type: "json_schema", schema: this.ctx.outputSchema };
     if (this.ctx.mcpServers) options.mcpServers = this.ctx.mcpServers;
     if (this.ctx.subagents && Object.keys(this.ctx.subagents).length > 0) options.agents = this.ctx.subagents;
 

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

@@ -1,6 +1,7 @@
 import type { AgentEvent, Normalizer } from "../types";
 import { truncate } from "../../utils/format-activity";
 import { scopeOf, parseFailure } from "../failure";
+import { estimateCodexCost } from "../pricing";
 
 /**
  * Pure reducer: Codex `codex exec --json` JSONL events → normalized `AgentEvent`s.
@@ -13,10 +14,24 @@ import { scopeOf, parseFailure } from "../failure";
  * message; `error` *items* are non-fatal warnings (service tier, model metadata,
  * skill budget) and are dropped.
  */
+/** codex answers a schema by making its final message the JSON object. */
+export function parseStructured(text: string): unknown {
+  const trimmed = text.trim().replace(/^```(?:json)?\s*|\s*```$/g, "");
+  if (!trimmed) return undefined;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return undefined;
+  }
+}
+
 export class CodexNormalizer implements Normalizer {
   /** The model this run was launched on, for usage attribution — codex's own
    *  events don't name it. */
-  constructor(private readonly model?: string) {}
+  constructor(
+    private readonly model?: string,
+    private readonly expectsSchema = false,
+  ) {}
 
   private threadId = "";
   private agentText = "";
@@ -46,12 +61,21 @@ export class CodexNormalizer implements Normalizer {
         const cacheRead = e.usage?.cached_input_tokens ?? 0;
         const input = Math.max(0, (e.usage?.input_tokens ?? 0) - cacheRead);
         const output = e.usage?.output_tokens ?? 0;
+        const estimated = estimateCodexCost(this.model, {
+          inputTokens: input,
+          outputTokens: output,
+          cacheReadInputTokens: cacheRead,
+          cacheCreationInputTokens: e.usage?.cache_write_input_tokens ?? 0,
+        });
         return [
           {
             type: "result",
             text: this.agentText,
             usage: { tokens: { input, output } },
             backendSessionId: this.threadId,
+            ...(this.expectsSchema && parseStructured(this.agentText) !== undefined
+              ? { structured: parseStructured(this.agentText) }
+              : {}),
             // Same shape the Claude path emits, so one accumulator serves both
             // and a failed-over turn is attributable to the provider that ran it.
             // No cost: codex reports none, and an invented zero would read as a
@@ -64,6 +88,10 @@ export class CodexNormalizer implements Normalizer {
                   outputTokens: output,
                   cacheReadInputTokens: cacheRead,
                   cacheCreationInputTokens: e.usage?.cache_write_input_tokens ?? 0,
+                  // What the API would have charged. Deliberately not `costUSD`:
+                  // the subscription covers these tokens, so this is a
+                  // projection and must never be added to a reported bill.
+                  ...(estimated === null ? {} : { estimatedCostUSD: estimated }),
                 },
               },
             },

package/src/agent/backends/codex.ts

@@ -1,4 +1,5 @@
-import { existsSync, readdirSync } from "fs";
+import { existsSync, readdirSync, mkdtempSync, writeFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
 import { homedir } from "os";
 import { join, dirname } from "path";
 import type { AgentBackend, AgentSession, AgentSessionContext, AgentEvent } from "../types";
@@ -34,6 +35,52 @@ export function resolveCodexBin(): string {
   return cachedCodexBin;
 }
 
+/**
+ * `codex exec -i` takes a path, not bytes. Channels that cache their uploads to
+ * disk (Slack, Telegram) give us one; anything held only in memory cannot be
+ * passed without materializing it, so it is reported rather than dropped.
+ */
+export function attachmentPaths(attachments?: Attachment[]): { paths: string[]; skipped: number } {
+  const paths: string[] = [];
+  let skipped = 0;
+  for (const a of attachments ?? []) {
+    if (a.sourcePath && existsSync(a.sourcePath)) paths.push(a.sourcePath);
+    else skipped++;
+  }
+  return { paths, skipped };
+}
+
+/** codex writes rollouts to `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl`. */
+export function codexHome(): string {
+  return process.env.CODEX_HOME || join(homedir(), ".codex");
+}
+
+/**
+ * Only recent days are searched. Resume exists to continue the conversation in
+ * front of us; anything older replays from Nia's own transcript instead, and
+ * walking every rollout ever written (thousands of files) to prove a negative
+ * would cost more than the resume saves.
+ */
+const RESUME_WINDOW_DAYS = 7;
+
+export function findRollout(sessionId: string, now: Date = new Date()): string | null {
+  if (!/^[0-9a-f-]{32,}$/i.test(sessionId)) return null;
+  const pad = (n: number) => String(n).padStart(2, "0");
+  for (let i = 0; i < RESUME_WINDOW_DAYS; i++) {
+    const d = new Date(now.getTime() - i * 86_400_000);
+    const dir = join(codexHome(), "sessions", String(d.getFullYear()), pad(d.getMonth() + 1), pad(d.getDate()));
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      continue; // no sessions that day
+    }
+    const hit = entries.find((f) => f.startsWith("rollout-") && f.endsWith(`${sessionId}.jsonl`));
+    if (hit) return join(dir, hit);
+  }
+  return null;
+}
+
 /** Minimal spawned-process surface, injectable so the session is unit-testable. */
 export interface CliProc {
   stdout: ReadableStream<Uint8Array>;
@@ -75,6 +122,10 @@ function defaultSpawn(args: string[], opts: { cwd: string; env: Record<string, s
   const proc = Bun.spawn([resolveCodexBin(), ...args], {
     cwd: opts.cwd,
     env: opts.env,
+    // The prompt goes in as an argument. `codex exec` still appends piped stdin
+    // as a <stdin> block, so leaving it to whatever the daemon inherited lets
+    // the parent's descriptor become part of the prompt.
+    stdin: "ignore",
     stdout: "pipe",
     stderr: "pipe",
   });
@@ -117,6 +168,33 @@ function idleAfter(ms: number): { promise: Promise<typeof IDLE>; cancel: () => v
 
 const STDERR_CAP = 16_000;
 
+/** Progress chatter codex writes to stderr on a healthy run. Reporting it as
+ *  the cause of a failure is how "Reading additional input from stdin..." came
+ *  to be the recorded error for every job that ever failed. */
+const STDERR_NOISE = [
+  /^reading additional input from stdin/i,
+  /^\s*$/,
+  /^\[?\d{4}-\d{2}-\d{2}T[\d:.]+Z?\]?\s*$/,
+  /^workdir:/i,
+  /^model:/i,
+  /^provider:/i,
+  /^approval:/i,
+  /^sandbox:/i,
+  /^reasoning (effort|summaries):/i,
+  /^--------$/,
+  /^openai codex v/i,
+];
+
+/** Drop the chatter, keep the diagnosis. Empty means codex said nothing useful. */
+export function meaningfulStderr(text: string): string {
+  return text
+    .split("\n")
+    .map((l) => l.trimEnd())
+    .filter((l) => l.trim() && !STDERR_NOISE.some((p) => p.test(l.trim())))
+    .join("\n")
+    .trim();
+}
+
 /**
  * Consume stderr to EOF, keeping only the tail. Must run alongside the process:
  * an undrained pipe blocks the child once its buffer fills.
@@ -153,14 +231,14 @@ export class CodexBackend implements AgentBackend {
     return new CodexSession(ctx, this.spawnFn, this.idleTimeoutMs);
   }
 
-  async canResume(): Promise<boolean> {
-    // v1: no thread resume; failover/continuity replays history from Nia's DB.
-    return false;
+  /** codex keys rollouts by session id alone — cwd does not narrow the search. */
+  async canResume(backendSessionId: string, _cwd: string): Promise<boolean> {
+    return findRollout(backendSessionId) !== null;
   }
 }
 
 class CodexSession implements AgentSession {
-  private _sessionId: string | null = null;
+  private _sessionId: string | null;
   private aborted: string | null = null;
   private proc: CliProc | null = null;
   private idledOut = false;
@@ -169,20 +247,24 @@ class CodexSession implements AgentSession {
     private ctx: AgentSessionContext,
     private spawnFn: SpawnFn,
     private idleTimeoutMs: number,
-  ) {}
+  ) {
+    this._sessionId = typeof ctx.resume === "string" ? ctx.resume : null;
+  }
 
   get backendSessionId(): string | null {
     return this._sessionId;
   }
 
-  async *send(text: string, _attachments?: Attachment[]): AsyncIterable<AgentEvent> {
+  async *send(text: string, attachments?: Attachment[]): AsyncIterable<AgentEvent> {
     const source: McpSourceContext = this.ctx.source ?? { channel: this.ctx.channel, room: this.ctx.room };
     const { url, token } = await mintRun(source);
 
-    const fullPrompt = `${this.ctx.systemPrompt}\n\n---\n\n${text}`;
-    const args = [
-      "exec",
-      fullPrompt,
+    // Resuming carries the system prompt with the thread, so re-sending it would
+    // stack a second copy on every turn.
+    const resumable = this._sessionId && findRollout(this._sessionId);
+    const prompt = resumable ? text : `${this.ctx.systemPrompt}\n\n---\n\n${text}`;
+    const args = resumable ? ["exec", "resume", this._sessionId!, prompt] : ["exec", prompt];
+    args.push(
       "--json",
       "--skip-git-repo-check",
       "--dangerously-bypass-approvals-and-sandbox",
@@ -192,8 +274,23 @@ class CodexSession implements AgentSession {
       `mcp_servers.nia.url="${url}"`,
       "-c",
       `mcp_servers.nia.bearer_token_env_var="NIA_MCP_TOKEN"`,
-    ];
+    );
+    // codex takes the schema as a file path, so it needs somewhere to live for
+    // the length of the run.
+    let schemaDir: string | null = null;
+    if (this.ctx.outputSchema) {
+      schemaDir = mkdtempSync(join(tmpdir(), "nia-codex-schema-"));
+      const schemaPath = join(schemaDir, "schema.json");
+      writeFileSync(schemaPath, JSON.stringify(this.ctx.outputSchema));
+      args.push("--output-schema", schemaPath);
+    }
+
+    const media = attachmentPaths(attachments);
+    for (const path of media.paths) args.push("-i", path);
     if (this.ctx.model && this.ctx.model !== "default") args.push("-m", this.ctx.model);
+    if (media.skipped > 0) {
+      yield { type: "thinking", delta: `${media.skipped} attachment(s) had no file on disk and were not sent to codex` };
+    }
 
     const proc = this.spawnFn(args, { cwd: this.ctx.cwd, env: subprocessEnv({ NIA_MCP_TOKEN: token }) });
     this.proc = proc;
@@ -201,7 +298,7 @@ class CodexSession implements AgentSession {
     // Started now, not after exit: an undrained pipe blocks the child.
     const stderr = drainStderr(proc.stderr);
 
-    const normalizer = new CodexNormalizer(this.ctx.model);
+    const normalizer = new CodexNormalizer(this.ctx.model, !!this.ctx.outputSchema);
     const stdout = proc.stdout.getReader();
     const lines = readLines(stdout)[Symbol.asyncIterator]();
     let sawTerminal = false;
@@ -248,10 +345,10 @@ class CodexSession implements AgentSession {
       const exit = await proc.exited;
       if (this.aborted) throw new Error(this.aborted);
       if (exit !== 0 && !sawTerminal) {
-        const text = await stderr;
+        const text = meaningfulStderr(await stderr);
         yield {
           type: "error",
-          message: text.trim() || `codex exited ${exit}`,
+          message: text || `codex exited ${exit} without reporting a cause`,
           retryable: false,
           failover: scopeOf(parseFailure(text), "provider"),
         };
@@ -259,6 +356,7 @@ class CodexSession implements AgentSession {
     } finally {
       await ignore(stdout.cancel(), "cancel codex stdout reader");
       revokeRun(token);
+      if (schemaDir) rmSync(schemaDir, { recursive: true, force: true });
       this.proc = null;
     }
   }

package/src/agent/catalog.ts

@@ -0,0 +1,40 @@
+import { existsSync } from "fs";
+import { resolveCodexBin } from "./backends/codex";
+
+/** Whether a codex backend can run on this host at all. */
+export function codexAvailable(): boolean {
+  return existsSync(resolveCodexBin());
+}
+
+/** Minimal spawned-process surface, injectable so the probe is unit-testable. */
+export type CatalogRunner = (args: string[]) => Promise<{ stdout: string; exitCode: number }>;
+
+const defaultRunner: CatalogRunner = async (args) => {
+  const proc = Bun.spawn([resolveCodexBin(), ...args], { stdout: "pipe", stderr: "ignore" });
+  const stdout = await new Response(proc.stdout).text();
+  return { stdout, exitCode: await proc.exited };
+};
+
+export function parseCodexModels(stdout: string): string[] | null {
+  try {
+    const parsed = JSON.parse(stdout) as { models?: { slug?: unknown }[] };
+    const slugs = (parsed.models ?? []).map((m) => m.slug).filter((s): s is string => typeof s === "string" && s !== "");
+    return slugs.length > 0 ? slugs : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Model slugs this codex install will accept. Null when the catalog cannot be
+ * read — callers treat that as "unknown", never as "the model is gone", so a
+ * broken probe can't manufacture a false alarm.
+ */
+export async function codexModelSlugs(run: CatalogRunner = defaultRunner): Promise<string[] | null> {
+  try {
+    const { stdout, exitCode } = await run(["debug", "models"]);
+    return exitCode === 0 ? parseCodexModels(stdout) : null;
+  } catch {
+    return null;
+  }
+}

package/src/agent/failure.ts

@@ -12,6 +12,10 @@ import type { FailoverScope } from "./types";
 
 const RETRYABLE = [/\b500\b/i, /internal server error/i, /overloaded/i, /529/, /rate limit/i];
 
+/** Messages that name no cause. They still have to fail over — a backend that
+ *  cannot say what went wrong has not said it is healthy. */
+const OPAQUE = [/^unknown error$/i, /reported an error with no message/i];
+
 const MODEL_SCOPED = [
   /model .*not (found|supported|available|allowed)/i,
   /(unknown|invalid|unsupported) model/i,
@@ -85,7 +89,7 @@ export function scopeOf(failure: Failure, blank?: FailoverScope): FailoverScope
   // A status is authoritative even when the message is empty — the prose that
   // accompanies a 429 or 529 is routinely unhelpful.
   if (failure.status !== undefined) return scopeOfStatus(failure.status, t);
-  if (!t || t.toLowerCase() === "unknown error") return blank;
+  if (!t || OPAQUE.some((p) => p.test(t))) return blank;
   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

@@ -10,6 +10,13 @@ const DEFAULT_COOLDOWN_MS = 5 * 60 * 1000;
 export interface ProviderHealth {
   markDown(provider: string): void;
   isDown(provider: string): boolean;
+  /** A turn was served. `atHead` means the chain's primary answered it. */
+  markServed(provider: string, atHead: boolean): void;
+  /** How long the chain has been answering exclusively from a fallback, in ms,
+   *  or null when the primary is still serving (or nothing has run yet). */
+  fallbackStreakMs(): number | null;
+  /** Who has been covering, for the alert text. */
+  lastServer(): string | null;
   /** Test seam. */
   clear(): void;
 }
@@ -19,10 +26,26 @@ export function createProviderHealth(
   now: () => number = Date.now,
 ): ProviderHealth {
   const downUntil = new Map<string, number>();
+  // When the primary last answered, and when a fallback first had to cover for
+  // it. Failover is designed to be silent, so nothing else in the system can
+  // tell the difference between a blip and a provider that has been gone a week.
+  let fallbackSince: number | null = null;
+  let server: string | null = null;
   return {
     markDown(provider) {
       downUntil.set(provider, now() + cooldownMs);
     },
+    markServed(provider, atHead) {
+      server = provider;
+      if (atHead) fallbackSince = null;
+      else fallbackSince ??= now();
+    },
+    fallbackStreakMs() {
+      return fallbackSince === null ? null : now() - fallbackSince;
+    },
+    lastServer() {
+      return server;
+    },
     isDown(provider) {
       const until = downUntil.get(provider);
       if (until === undefined) return false;
@@ -34,6 +57,8 @@ export function createProviderHealth(
     },
     clear() {
       downUntil.clear();
+      fallbackSince = null;
+      server = null;
     },
   };
 }

package/src/agent/index.ts

@@ -11,4 +11,5 @@ export { isResultEvent } from "./types";
 export type { FailoverScope } from "./types";
 export { getBackend, setBackend, setBackendChain, resolveChain, buildChain } from "./registry";
 export { ChainCursor, describeEntry, type ChainEntry } from "./chain";
+export { providerHealth, type ProviderHealth } from "./health";
 export { resolveSdkModel } from "./backends/claude";