@askalf/dario 5.5.89 → 6.0.0

package/dist/compare.js

@@ -0,0 +1,210 @@
+/**
+ * Shadow compare (v6.0.0) — run one prompt past a second model family and keep
+ * both answers, without the client ever knowing.
+ *
+ * WHY THIS SHAPE. Once dario can serve either wire shape from either
+ * subscription, the obvious question stops being "can I reach GPT" and becomes
+ * "which of these two is actually better at MY work". Answering that from
+ * benchmarks is close to worthless; answering it from your own real traffic is
+ * not. So a compare is triggered per-request by a header, on prompts you were
+ * sending anyway.
+ *
+ * THE CLIENT IS NEVER AFFECTED. The primary answer streams through untouched
+ * and the comparison runs beside it — the request is not held open for it, and
+ * a compare that fails, times out, or has nowhere to go is dropped silently
+ * with the record still written. A diagnostic that can degrade the thing it is
+ * measuring is worse than no diagnostic.
+ *
+ * BOTH SIDES ARE RECORDED IN THE CLIENT'S OWN WIRE SHAPE. The comparison is
+ * dispatched through the same forwardToCodex translation the real path uses, so
+ * an Anthropic-shape request yields two Anthropic-shape answers. Comparing a
+ * Messages response against a raw Responses payload would mean eyeballing
+ * across two formats and calling the difference a model difference.
+ *
+ * Raw payloads are stored rather than extracted text: extraction is exactly
+ * where a subtle bug would quietly make two answers look more alike than they
+ * are, and this release was written off the back of five failures that read as
+ * successes.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { forwardToCodex, getCodexModelSlugs, isCodexModel } from './codex-backend.js';
+import { hasAnyCodexAccount, selectCodexAccount, getFreshCodexAccount } from './codex-accounts.js';
+/** Request header that arms a comparison: `x-dario-compare: <model>`. */
+export const COMPARE_HEADER = 'x-dario-compare';
+/**
+ * Response header naming the model a comparison was REQUESTED against.
+ *
+ * Deliberately not "compared-with". The header has to be set before the primary
+ * response starts streaming, which is strictly earlier than we can know whether
+ * the comparison ran — it may still be skipped for a missing account, an
+ * unlisted model, or an unparseable body. A header claiming a comparison
+ * happened would therefore sometimes be a lie, which is the exact failure this
+ * release exists to stamp out. The name now states only what is true at the
+ * moment it is written; whether it actually ran is in the record.
+ */
+export const COMPARE_RESULT_HEADER = 'x-dario-compare-requested';
+export const COMPARE_DIR = join(homedir(), '.dario', 'compare');
+/**
+ * Read the compare target from request headers. Returns null when unarmed, and
+ * for the empty value, so `-H 'x-dario-compare:'` reliably means "off" rather
+ * than "compare against a model named empty string".
+ */
+export function readCompareTarget(headers) {
+    const raw = headers[COMPARE_HEADER] ?? headers[COMPARE_HEADER.toUpperCase()];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof value !== 'string')
+        return null;
+    return value.trim() || null;
+}
+/**
+ * Swap the model in a JSON request body. Returns null when the body is not
+ * JSON — the caller then skips the comparison rather than sending something it
+ * could not read.
+ */
+export function withModel(body, model) {
+    try {
+        const parsed = JSON.parse(body.toString());
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        // A comparison is always non-streaming: nobody is watching it arrive, and a
+        // single JSON body is far easier to diff later than two SSE transcripts.
+        return Buffer.from(JSON.stringify({ ...parsed, model, stream: false }));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Tee everything written to a real response into a buffer, leaving delivery
+ * completely unchanged. `captured()` is meaningful once the response finishes.
+ */
+export function teeResponse(res) {
+    const started = Date.now();
+    const chunks = [];
+    const origWrite = res.write.bind(res);
+    const origEnd = res.end.bind(res);
+    res.write = ((chunk, ...rest) => {
+        if (typeof chunk === 'string')
+            chunks.push(chunk);
+        else if (Buffer.isBuffer(chunk))
+            chunks.push(chunk.toString('utf-8'));
+        return origWrite(chunk, ...rest);
+    });
+    res.end = ((chunk, ...rest) => {
+        if (typeof chunk === 'string')
+            chunks.push(chunk);
+        else if (Buffer.isBuffer(chunk))
+            chunks.push(chunk.toString('utf-8'));
+        return origEnd(chunk, ...rest);
+    });
+    return {
+        captured: () => ({
+            status: res.statusCode ?? null,
+            body: chunks.join(''),
+            ms: Date.now() - started,
+        }),
+    };
+}
+/**
+ * A ServerResponse stand-in that keeps what was written instead of sending it.
+ * The comparison has no socket of its own — it is answering nobody.
+ */
+function captureSink() {
+    const started = Date.now();
+    const state = { status: null, chunks: [], headersSent: false };
+    const sink = {
+        statusCode: 0,
+        headersSent: false,
+        writeHead(code) { state.status = code; state.headersSent = true; this.headersSent = true; return this; },
+        setHeader() { return this; },
+        write(s) { if (s !== undefined && s !== null)
+            state.chunks.push(String(s)); return true; },
+        end(s) { if (s !== undefined && s !== null)
+            state.chunks.push(String(s)); return this; },
+        on() { return this; },
+        once() { return this; },
+        emit() { return false; },
+    };
+    return {
+        sink: sink,
+        side: () => ({
+            status: state.status,
+            body: state.chunks.join(''),
+            ms: Date.now() - started,
+        }),
+    };
+}
+/**
+ * Run the comparison against the ChatGPT subscription.
+ *
+ * Resolves to a reason-for-skipping string when it declines, never throwing:
+ * the caller is on the success path of a request it has already answered, and
+ * a diagnostic must not be able to take that down.
+ *
+ * v6.0.0 compares against a Codex account only. Comparing against the Claude
+ * pool would mean occupying a seat for a request nobody is waiting on, which is
+ * a trade worth making deliberately rather than by default.
+ */
+export async function runCompare(opts) {
+    try {
+        if (!(await hasAnyCodexAccount()))
+            return { side: null, skipped: 'no Codex account configured' };
+        const stored = await selectCodexAccount();
+        if (!stored)
+            return { side: null, skipped: 'no Codex account configured' };
+        const creds = await getFreshCodexAccount(stored);
+        const slugs = await getCodexModelSlugs(creds).catch(() => []);
+        if (!isCodexModel(opts.targetModel, slugs)) {
+            return { side: null, skipped: `${opts.targetModel} is not served by Codex account ${creds.alias}` };
+        }
+        const body = withModel(opts.body, opts.targetModel);
+        if (!body)
+            return { side: null, skipped: 'request body is not JSON' };
+        const { sink, side } = captureSink();
+        await forwardToCodex({}, sink, body, creds, opts.corsOrigin, {}, opts.timeoutMs, opts.verbose, opts.shape);
+        return { side: side() };
+    }
+    catch (err) {
+        return { side: null, skipped: `compare failed: ${err.message}` };
+    }
+}
+/**
+ * Persist one record. Returns the path written, or null on failure — a compare
+ * log that cannot be written is not worth failing a served request over.
+ */
+export function writeCompareRecord(record, dir = COMPARE_DIR) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        const stamp = record.ts.replace(/[:.]/g, '-');
+        // Separators out, then dot-runs collapsed. Stripping separators alone
+        // already prevents traversal, but leaving `..` in a filename invites the
+        // next reader to assume it was never considered.
+        const safeModel = record.comparedModel.replace(/[^\w.-]/g, '_').replace(/\.{2,}/g, '.');
+        const base = join(dir, `${stamp}-${safeModel}`);
+        const payload = JSON.stringify(record, null, 2);
+        // `wx` fails when the file already exists, so two comparisons landing in the
+        // same millisecond get distinct files instead of one silently overwriting
+        // the other. Exclusive-create also holds ACROSS PROCESSES, which a
+        // read-then-write existence check would not: two dario instances sharing a
+        // compare directory is an ordinary setup, and losing half a calibration run
+        // to a race would be invisible — the log would simply have fewer records
+        // than requests, with nothing to indicate why.
+        for (let n = 0; n < 50; n++) {
+            const path = n === 0 ? `${base}.json` : `${base}-${n + 1}.json`;
+            try {
+                writeFileSync(path, payload, { encoding: 'utf-8', flag: 'wx' });
+                return path;
+            }
+            catch (err) {
+                if (err.code !== 'EEXIST')
+                    throw err;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/config-file.d.ts

@@ -92,11 +92,12 @@ export interface DarioConfig {
     effort?: string | null;
     maxTokens?: number | 'client' | null;
     /**
-     * Pool-exhausted fallback. When `model` is a non-empty string and an
-     * openai-compat backend is configured, OpenAI-shape requests that the
-     * Claude pool can't serve are forwarded to that backend as `model`
-     * (response marked `x-dario-pool-fallback`) instead of surfacing the
-     * 429/503. Null/absent = off.
+     * Pool-exhausted fallback. When `model` is a non-empty string, a request
+     * the Claude pool can't serve is forwarded as `model` to whichever
+     * provider can serve it — a stored Codex/ChatGPT subscription that lists
+     * it (either wire shape), otherwise a configured openai-compat backend
+     * (OpenAI shape only) — instead of surfacing the 429/503. The response
+     * is marked `x-dario-pool-fallback`. Null/absent = off.
      */
     poolFallback?: {
         model?: string | null;

package/dist/doctor.d.ts

@@ -19,6 +19,31 @@ export interface Check {
     /** Right-column detail — human readable, may include versions, paths, counts. */
     detail: string;
 }
+/**
+ * Decide what `doctor` should say about pool-exhaustion failover, from
+ * configuration alone. Pure and exported so every branch is testable — the
+ * live box can only ever exercise the one that matches its own credentials,
+ * which is how the inert case went unnoticed in the first place.
+ *
+ * This check exists because of a specific outage. The box ran with
+ * --pool-fallback armed, no Codex account and no api-key backend, so failover
+ * was INERT: correctly configured by every check that existed, and incapable of
+ * doing anything. On 2026-08-29 the Claude pool filled twice and the fleet went
+ * dark beside an idle ChatGPT subscription. Nothing reported it, because
+ * nothing asked "armed" and "has somewhere to go" as a single question.
+ *
+ * It reports configuration, never reachability. Claiming a route WORKS needs a
+ * live request, and this release was built on the lesson that a green config is
+ * not a working path.
+ */
+export declare function failoverReadiness(input: {
+    chain: readonly string[];
+    codexAccounts: number;
+    backends: readonly string[];
+}): {
+    status: CheckStatus;
+    detail: string;
+};
 /**
  * Format a epoch timestamp reset time relative to the current time.
  * Returns a human-friendly string like "1h 9m", "45m", "2d 3h".

package/dist/doctor.js

@@ -22,6 +22,57 @@ import { detectCCOAuthConfig } from './cc-oauth-detect.js';
 import { runAuthorizeProbe } from './cc-authorize-probe.js';
 import { MIGRATED_LOGIN_ALIAS } from './accounts.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Decide what `doctor` should say about pool-exhaustion failover, from
+ * configuration alone. Pure and exported so every branch is testable — the
+ * live box can only ever exercise the one that matches its own credentials,
+ * which is how the inert case went unnoticed in the first place.
+ *
+ * This check exists because of a specific outage. The box ran with
+ * --pool-fallback armed, no Codex account and no api-key backend, so failover
+ * was INERT: correctly configured by every check that existed, and incapable of
+ * doing anything. On 2026-08-29 the Claude pool filled twice and the fleet went
+ * dark beside an idle ChatGPT subscription. Nothing reported it, because
+ * nothing asked "armed" and "has somewhere to go" as a single question.
+ *
+ * It reports configuration, never reachability. Claiming a route WORKS needs a
+ * live request, and this release was built on the lesson that a green config is
+ * not a working path.
+ */
+export function failoverReadiness(input) {
+    const { chain, codexAccounts, backends } = input;
+    const hasCodex = codexAccounts > 0;
+    const hasBackend = backends.length > 0;
+    if (chain.length === 0) {
+        return { status: 'info', detail: 'off — a drained Claude pool returns 429/503 (--pool-fallback to arm)' };
+    }
+    if (!hasCodex && !hasBackend) {
+        return {
+            status: 'warn',
+            detail: `armed (${chain.join(' → ')}) but INERT — no Codex account and no backend to fall back to. `
+                + 'Add one: `dario add altman` (subscription) or `dario backend add …` (api key).',
+        };
+    }
+    if (hasCodex && chain.length > 1) {
+        return {
+            status: 'ok',
+            detail: `symmetric: ${chain.join(' → ')}, across ${codexAccounts} Codex account`
+                + `${codexAccounts === 1 ? '' : 's'}${hasBackend ? ` + ${backends.length} backend(s)` : ''}`,
+        };
+    }
+    if (hasCodex) {
+        return {
+            status: 'ok',
+            detail: `claude → codex as ${chain[0]} (both wire shapes). One-way — add a Claude model to `
+                + 'the chain (--pool-fallback=a,b) to cover a rate-limited ChatGPT plan too.',
+        };
+    }
+    return {
+        status: 'ok',
+        detail: `claude → ${backends[0]} as ${chain[0]} — OpenAI path only. A Codex account would `
+            + 'extend it to Anthropic-shape clients (Claude Code, agent runtimes).',
+    };
+}
 /**
  * Format a epoch timestamp reset time relative to the current time.
  * Returns a human-friendly string like "1h 9m", "45m", "2d 3h".
@@ -951,6 +1002,26 @@ export async function runChecks(opts = {}) {
     catch (err) {
         checks.push({ status: 'warn', label: 'Backends', detail: `check failed: ${err.message}` });
     }
+    // ---- Failover readiness (v6.0.0) — see failoverReadiness() for the why.
+    try {
+        const { loadConfig } = await import('./config-file.js');
+        const { listCodexAccountAliases } = await import('./codex-accounts.js');
+        const { listBackends } = await import('./openai-backend.js');
+        const cfg = loadConfig().config;
+        const raw = (process.env.DARIO_POOL_FALLBACK ?? cfg.poolFallback?.model ?? '').trim();
+        const chain = raw.split(',').map((m) => m.trim()).filter(Boolean);
+        const codexAliases = await listCodexAccountAliases().catch(() => []);
+        const backends = await listBackends().catch(() => []);
+        const verdict = failoverReadiness({
+            chain,
+            codexAccounts: codexAliases.length,
+            backends: backends.map((b) => b.name),
+        });
+        checks.push({ status: verdict.status, label: 'Failover', detail: verdict.detail });
+    }
+    catch (err) {
+        checks.push({ status: 'warn', label: 'Failover', detail: `check failed: ${err.message}` });
+    }
     // ---- CC sub-agent (v3.26, direction #2)
     try {
         const { loadSubagentStatus } = await import('./subagent.js');

package/dist/provider-adapter.d.ts

@@ -99,4 +99,35 @@ export declare const DEFAULT_ADAPTERS: readonly ProviderAdapter[];
  * because it's a cross-adapter relationship (a Claude-primary request that
  * spills to openai on pool exhaustion), not a primary claim by either side.
  */
+/**
+ * Who serves a request the Claude pool could not, and on which wire shapes.
+ *
+ * This exists because v6.0.0 shipped the failover dispatcher correctly and the
+ * GATE in front of it wrongly. `selectPoolAccount()` in proxy.ts still required
+ * an api-key backend AND the OpenAI path before it would defer, so a box with a
+ * Codex account and no api-key backend — the deployment this release is FOR —
+ * got a 503 before the dispatcher ran, and Anthropic-shape requests never
+ * reached it at all. Every routing test passed, because not one of them went
+ * through that selector.
+ *
+ * So the matrix lives here, in one place, stated once:
+ *
+ *   codex account lists the model     → 'codex'       (both wire shapes)
+ *   else api-key backend, OpenAI path → 'openai'      (no Messages translation)
+ *   else                              → 'unavailable' (honest 503)
+ *
+ * A caveat worth keeping in view: this is a SPECIFICATION test surface, not a
+ * wiring one. It cannot prove proxy.ts asks it the right question at the right
+ * moment — that is precisely what broke — and only a live request through the
+ * selector can. Treat green here as necessary, never sufficient.
+ */
+export type PoolFallbackOutcome = 'codex' | 'openai' | 'unavailable';
+export declare function poolFallbackOutcome(input: {
+    fallbackModels: readonly string[];
+    poolSize: number;
+    /** A stored Codex account LISTS one of `fallbackModels`. */
+    codexServes: boolean;
+    hasOpenAIBackend: boolean;
+    isOpenAIPath: boolean;
+}): PoolFallbackOutcome;
 export declare function route(ctx: RouteContext, adapters?: readonly ProviderAdapter[]): RouteDecision;

package/dist/provider-adapter.js

@@ -87,25 +87,47 @@ export const claudeAdapter = {
     },
 };
 export const DEFAULT_ADAPTERS = [codexAdapter, openaiAdapter, claudeAdapter];
-/**
- * Resolve the routing decision. Offers the request to adapters in priority
- * order and takes the first primary claim; the Claude adapter always claims, so
- * the result is total. The claude→openai pool fallback is layered on top
- * because it's a cross-adapter relationship (a Claude-primary request that
- * spills to openai on pool exhaustion), not a primary claim by either side.
- */
+export function poolFallbackOutcome(input) {
+    const { fallbackModels, poolSize, codexServes, hasOpenAIBackend, isOpenAIPath } = input;
+    // Unarmed, or an empty pool, is not a failover situation at all: an empty
+    // pool is a setup error the operator must see, not traffic to re-bill.
+    if (fallbackModels.length === 0 || poolSize === 0)
+        return 'unavailable';
+    if (codexServes)
+        return 'codex';
+    if (hasOpenAIBackend && isOpenAIPath)
+        return 'openai';
+    return 'unavailable';
+}
 export function route(ctx, adapters = DEFAULT_ADAPTERS) {
     const ordered = [...adapters].sort((a, b) => b.priority - a.priority);
     const primary = ordered.find((a) => a.claimsPrimary(ctx)) ?? claudeAdapter;
     let fallback = null;
     let reason = `${primary.id} primary`;
-    if (primary.id === 'claude' &&
-        ctx.poolFallbackModel !== null &&
-        ctx.hasOpenAIBackend &&
-        ctx.isOpenAIPath &&
-        ctx.poolSize > 0) {
-        fallback = 'openai';
-        reason = 'claude primary, openai fallback on pool-exhaustion';
+    // NOTE: this reports the CLAUDE-PRIMARY direction. The reverse — a codex
+    // primary declining a 429/5xx so the request lands on the Claude pool — is
+    // dispatched in proxy.ts, because it is a mid-flight decision that depends
+    // on the upstream's answer rather than on anything knowable when routing.
+    //
+    // Pool-exhaustion failover (v6.0.0). The target is whichever provider can
+    // actually serve `poolFallbackModel`, which makes a SECOND SUBSCRIPTION a
+    // first-class failover target rather than requiring an API key.
+    //
+    // codex is preferred when the nominated model is one its account lists: it
+    // is a plan you already pay for, so failover costs nothing per token, and
+    // since v5.5.87 it serves BOTH wire shapes — an Anthropic-shape client
+    // (Claude Code, any Anthropic SDK, a fleet agent) can fail over too. The
+    // api-key backend keeps its OpenAI-path guard: there is still no Messages
+    // translation on that route.
+    if (primary.id === 'claude' && ctx.poolFallbackModel !== null && ctx.poolSize > 0) {
+        if (ctx.hasCodexAccount && isCodexModel(ctx.poolFallbackModel, ctx.codexModels)) {
+            fallback = 'codex';
+            reason = 'claude primary, codex (subscription) fallback on pool-exhaustion';
+        }
+        else if (ctx.hasOpenAIBackend && ctx.isOpenAIPath) {
+            fallback = 'openai';
+            reason = 'claude primary, openai fallback on pool-exhaustion';
+        }
     }
     return { provider: primary.id, fallback, reason };
 }

package/dist/proxy.d.ts

@@ -376,15 +376,21 @@ interface ProxyOptions {
      */
     maxTokens?: number | 'client';
     /**
-     * Pool-exhausted fallback model (strictly opt-in; off when unset/empty).
-     * When the Claude pool can't serve — selection finds every seat drained
-     * or cooling, or a mid-flight 429 has no peer left — OpenAI-shape
-     * requests (/v1/chat/completions) are forwarded to the configured
-     * openai-compat backend with the model swapped to this value, instead
-     * of surfacing the 429/503. Responses carry `x-dario-pool-fallback`.
-     * Anthropic-shape requests keep the error: dario has no OpenAI→Anthropic
-     * response translation. Inert without a configured backend. Sourced from
-     * `--pool-fallback` / `DARIO_POOL_FALLBACK` / config `poolFallback.model`.
+     * Pool-exhausted fallback (strictly opt-in; off when unset/empty). May name
+     * a CHAIN — `gpt-5.6-sol,claude-sonnet-5` — read left to right, each
+     * provider taking the first entry it can actually serve.
+     *
+     * When a provider can't serve — the pool finds every seat drained or
+     * cooling, a mid-flight 429 has no peer left, or a subscription answers
+     * 429/5xx — the request is served as the nominated model by whoever can,
+     * instead of surfacing the error. A Codex/ChatGPT subscription is preferred
+     * and works on BOTH wire shapes; an openai-compat backend is OpenAI-path
+     * only, having no Messages translation. A chain makes failover symmetric in
+     * both directions. Responses carry `x-dario-pool-fallback`.
+     *
+     * Inert with no Codex account and no backend — `dario doctor` says so.
+     * Sourced from `--pool-fallback` / `DARIO_POOL_FALLBACK` / config
+     * `poolFallback.model`.
      */
     poolFallbackModel?: string;
     /**