@vascend/talos 0.1.0

package/dist/providers/models-dev.js

@@ -0,0 +1,97 @@
+import { mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { talosConfigDir } from "../core/env-paths.js";
+import { ModelCatalog, parseModelCatalog } from "./model-catalog.js";
+const MAX_BYTES = 24 * 1024 * 1024;
+const TTL = 24 * 60 * 60 * 1000;
+const states = new Map();
+function pathFor(env) { return resolve(talosConfigDir(env), "cache", "models.dev.json"); }
+function stateFor(env) {
+    const path = pathFor(env);
+    let state = states.get(path);
+    if (state)
+        return state;
+    state = { catalog: new ModelCatalog(), fetchedAt: 0, retryAt: 0 };
+    try {
+        if (statSync(path).size <= MAX_BYTES) {
+            const saved = JSON.parse(readFileSync(path, "utf8"));
+            const catalog = parseModelCatalog(saved.data);
+            if (catalog.models.length)
+                state = { catalog, fetchedAt: Number(saved.fetchedAt) || 0, retryAt: 0 };
+        }
+    }
+    catch { /* Missing or corrupt cache: keep the built-in model suggestions. */ }
+    states.set(path, state);
+    return state;
+}
+export function cachedModelCatalog(env = process.env) {
+    return env["TALOS_MODELS_DEV"] === "0" ? new ModelCatalog() : stateFor(env).catalog;
+}
+export function modelCapabilities(model, env = process.env) {
+    return cachedModelCatalog(env).get(model);
+}
+// A single bounded snapshot per user, replaced atomically once a day. Failures
+// preserve the last valid snapshot; no credentials or conversation are sent.
+export async function loadModelsDev(env = process.env, opts = {}) {
+    if (env["TALOS_MODELS_DEV"] === "0")
+        return new ModelCatalog();
+    const state = stateFor(env), now = opts.now ?? Date.now();
+    if (state.pending)
+        return state.pending;
+    if (!opts.force && (now < state.retryAt || (state.fetchedAt > 0 && now - state.fetchedAt < TTL)))
+        return state.catalog;
+    const run = async () => {
+        let temp;
+        try {
+            const response = await (opts.fetch ?? fetch)("https://models.dev/api.json", {
+                signal: AbortSignal.timeout(opts.timeoutMs ?? 5000), headers: { accept: "application/json" },
+            });
+            if (!response.ok || !response.body)
+                throw new Error("catalog unavailable");
+            const reader = response.body.getReader(), chunks = [];
+            let bytes = 0;
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    bytes += value.byteLength;
+                    if (bytes > MAX_BYTES - 1024)
+                        throw new Error("catalog too large");
+                    chunks.push(value);
+                }
+            }
+            finally {
+                await reader.cancel().catch(() => { });
+                reader.releaseLock();
+            }
+            const data = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+            const catalog = parseModelCatalog(data);
+            if (!catalog.models.length)
+                throw new Error("empty catalog");
+            state.catalog = catalog;
+            state.fetchedAt = now;
+            state.retryAt = 0;
+            const path = pathFor(env);
+            mkdirSync(dirname(path), { recursive: true });
+            temp = `${path}.${randomUUID()}.tmp`;
+            writeFileSync(temp, JSON.stringify({ fetchedAt: now, data }), { encoding: "utf8", mode: 0o600 });
+            renameSync(temp, path);
+        }
+        catch {
+            state.retryAt = now + 5 * 60 * 1000;
+        }
+        finally {
+            if (temp)
+                try {
+                    unlinkSync(temp);
+                }
+                catch { /* Already renamed. */ }
+            state.pending = undefined;
+        }
+        return state.catalog;
+    };
+    state.pending = run();
+    return state.pending;
+}

package/dist/providers/oauth-callback-server.d.ts

@@ -0,0 +1,28 @@
+export interface CallbackResult {
+    readonly code?: string;
+    readonly state?: string;
+    readonly error?: string;
+    readonly errorDescription?: string;
+    readonly raw: Readonly<Record<string, string>>;
+}
+export interface StartCallbackServerOptions {
+    readonly host?: string;
+    readonly port?: number;
+    readonly path?: string;
+    readonly successHtml?: string;
+    readonly errorHtml?: string;
+    readonly expectedState?: string;
+}
+export interface WaitForCodeOptions {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface CallbackServer {
+    readonly redirectUri: string;
+    readonly port: number;
+    readonly host: string;
+    readonly path: string;
+    waitForCode(opts?: WaitForCodeOptions): Promise<CallbackResult>;
+    close(): Promise<void>;
+}
+export declare function startCallbackServer(opts?: StartCallbackServerOptions): Promise<CallbackServer>;

package/dist/providers/oauth-callback-server.js

@@ -0,0 +1,184 @@
+import { createServer } from "node:http";
+const DEFAULT_PATH = "/callback";
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+// Pagina minimale di conferma. Niente risorse esterne: tutto inline, cosi'
+// funziona anche offline e senza ulteriori richieste verso il server.
+function page(title, message, ok) {
+    const accent = ok ? "#2e7d32" : "#c62828";
+    return `<!doctype html>
+<html lang="it">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+         display: flex; min-height: 100vh; margin: 0; align-items: center;
+         justify-content: center; background: #f5f5f5; }
+  .card { background: #fff; border-radius: 12px; padding: 2.5rem 3rem;
+          box-shadow: 0 8px 30px rgba(0,0,0,.08); max-width: 26rem; text-align: center; }
+  .badge { width: 3rem; height: 3rem; border-radius: 50%; margin: 0 auto 1rem;
+           display: flex; align-items: center; justify-content: center;
+           font-size: 1.6rem; color: #fff; background: ${accent}; }
+  h1 { font-size: 1.25rem; margin: 0 0 .5rem; color: ${accent}; }
+  p { color: #555; line-height: 1.5; margin: 0; }
+  @media (prefers-color-scheme: dark) {
+    body { background: #1b1b1b; }
+    .card { background: #262626; }
+    p { color: #bbb; }
+  }
+</style>
+</head>
+<body>
+  <div class="card">
+    <div class="badge">${ok ? "&#10003;" : "&#33;"}</div>
+    <h1>${escapeHtml(title)}</h1>
+    <p>${escapeHtml(message)}</p>
+  </div>
+</body>
+</html>`;
+}
+const DEFAULT_SUCCESS_HTML = page("Autorizzazione completata", "Puoi chiudere questa scheda e tornare al terminale.", true);
+const DEFAULT_ERROR_HTML = page("Autorizzazione non riuscita", "Qualcosa e' andato storto. Torna al terminale per i dettagli.", false);
+// ---------------------------------------------------------------------------
+// Avvio del server
+// ---------------------------------------------------------------------------
+// Parsa la query string di una richiesta in una mappa piatta. Usa l'URL nativo
+// con una base loopback fittizia (il path/query e' tutto cio' che ci serve).
+function parseQuery(reqUrl, host, port) {
+    const url = new URL(reqUrl, `http://${host}:${port}`);
+    const params = {};
+    for (const [k, v] of url.searchParams)
+        params[k] = v;
+    return { path: url.pathname, params };
+}
+// Costruisce il CallbackResult dai parametri, applicando il controllo di state.
+function toResult(params, expectedState) {
+    const code = params["code"]?.trim() || undefined;
+    const state = params["state"];
+    const error = params["error"]?.trim() || undefined;
+    const errorDescription = params["error_description"]?.trim() || undefined;
+    if (expectedState !== undefined && state !== expectedState) {
+        return {
+            error: "state_mismatch",
+            errorDescription: "Il parametro state non combacia con quello atteso.",
+            state,
+            raw: params,
+        };
+    }
+    return { code, state, error, errorDescription, raw: params };
+}
+// Avvia il server di callback e attende che sia in ascolto.
+export function startCallbackServer(opts = {}) {
+    const host = opts.host ?? "127.0.0.1";
+    const port = opts.port ?? 0;
+    const cbPath = opts.path ?? DEFAULT_PATH;
+    const successHtml = opts.successHtml ?? DEFAULT_SUCCESS_HTML;
+    const errorHtml = opts.errorHtml ?? DEFAULT_ERROR_HTML;
+    // Stato condiviso tra handler e waitForCode.
+    let settled = false;
+    let captured = null;
+    let onCapture = null;
+    const deliver = (r) => {
+        captured = r;
+        if (onCapture) {
+            const cb = onCapture;
+            onCapture = null;
+            cb(r);
+        }
+    };
+    const handler = (req, res) => {
+        const addr = server.address();
+        const actualPort = addr ? addr.port : port;
+        const { path: reqPath, params } = parseQuery(req.url ?? "/", host, actualPort);
+        // Ignora richieste accessorie del browser senza disturbare il flusso.
+        if (reqPath === "/favicon.ico") {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // Solo il path di callback ci interessa.
+        if (reqPath !== cbPath) {
+            res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+            res.end("Not found");
+            return;
+        }
+        const result = toResult(params, opts.expectedState);
+        const isOk = !result.error && !!result.code;
+        res.writeHead(isOk ? 200 : 400, { "content-type": "text/html; charset=utf-8" });
+        res.end(isOk ? successHtml : errorHtml);
+        // Cattura solo il primo callback "deciso" (con code o con errore). Una
+        // richiesta sul path senza ne' code ne' error (raro) non risolve l'attesa.
+        if (!settled && (result.code || result.error)) {
+            settled = true;
+            deliver(result);
+        }
+    };
+    const server = createServer(handler);
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            server.removeListener("error", reject);
+            const addr = server.address();
+            const actualPort = addr.port;
+            const redirectUri = `http://${host}:${actualPort}${cbPath}`;
+            const close = () => new Promise((res) => {
+                if (!server.listening) {
+                    res();
+                    return;
+                }
+                server.close(() => res());
+                // Chiudi eventuali keep-alive pendenti (Node >= 18.2).
+                server.closeAllConnections?.();
+            });
+            const waitForCode = (waitOpts = {}) => {
+                // Se il callback e' gia' arrivato, risolvi subito.
+                if (captured) {
+                    const c = captured;
+                    return close().then(() => c);
+                }
+                return new Promise((resolveWait, rejectWait) => {
+                    let timer = null;
+                    const cleanup = () => {
+                        if (timer)
+                            clearTimeout(timer);
+                        if (waitOpts.signal)
+                            waitOpts.signal.removeEventListener("abort", onAbort);
+                        return close();
+                    };
+                    const onAbort = () => {
+                        onCapture = null;
+                        void cleanup().then(() => rejectWait(new Error("callback annullato")));
+                    };
+                    if (waitOpts.signal) {
+                        if (waitOpts.signal.aborted) {
+                            onAbort();
+                            return;
+                        }
+                        waitOpts.signal.addEventListener("abort", onAbort, { once: true });
+                    }
+                    if (waitOpts.timeoutMs && waitOpts.timeoutMs > 0) {
+                        timer = setTimeout(() => {
+                            onCapture = null;
+                            void cleanup().then(() => rejectWait(new Error(`timeout in attesa del callback OAuth (${waitOpts.timeoutMs}ms)`)));
+                        }, waitOpts.timeoutMs);
+                        // Non tenere vivo il processo solo per questo timer.
+                        timer.unref?.();
+                    }
+                    onCapture = (r) => {
+                        void cleanup().then(() => resolveWait(r));
+                    };
+                });
+            };
+            resolve({ redirectUri, port: actualPort, host, path: cbPath, waitForCode, close });
+        });
+    });
+}

package/dist/providers/oauth-orchestrator.d.ts

@@ -0,0 +1,58 @@
+import { type PkceChallenge } from "./openrouter-auth.js";
+export interface CallbackResult {
+    readonly code?: string;
+    readonly state?: string;
+    readonly error?: string;
+    readonly errorDescription?: string;
+    readonly raw?: unknown;
+}
+export interface CallbackServer {
+    readonly redirectUri: string;
+    readonly port: number;
+    readonly host: string;
+    readonly path: string;
+    waitForCode(opts?: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<CallbackResult>;
+    close(): Promise<void> | void;
+}
+export type StartCallbackServer = (opts?: {
+    readonly host?: string;
+    readonly port?: number;
+    readonly path?: string;
+    readonly expectedState?: string;
+}) => Promise<CallbackServer>;
+export type OpenBrowser = (url: string) => Promise<{
+    readonly opened: boolean;
+    readonly error?: string;
+}>;
+export type BuildAuthUrl = (redirectUri: string, challenge: PkceChallenge) => string;
+export type OrchestratorPhase = "server_started" | "url_built" | "browser_opened" | "browser_failed" | "awaiting_code" | "code_received" | "server_closed" | "exchanging" | "done" | "error";
+export interface OrchestratorEvent {
+    readonly phase: OrchestratorPhase;
+    readonly detail?: string;
+}
+export interface OrchestrateOptions {
+    readonly startServer: StartCallbackServer;
+    readonly buildAuthUrl: BuildAuthUrl;
+    readonly openBrowser?: OpenBrowser;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly host?: string;
+    readonly port?: number;
+    readonly path?: string;
+    readonly fetchImpl?: typeof fetch;
+    readonly rand?: (n: number) => Buffer;
+    readonly persist?: boolean;
+    readonly onEvent?: (ev: OrchestratorEvent) => void;
+}
+export interface OrchestrateResult {
+    readonly ok: boolean;
+    readonly apiKey?: string;
+    readonly errorKind?: "browser" | "timeout" | "aborted" | "callback" | "exchange" | "server" | "unknown";
+    readonly error?: string;
+    readonly authUrl?: string;
+    readonly browserOpened?: boolean;
+}
+export declare function orchestrateOAuth(env: NodeJS.ProcessEnv, opts: OrchestrateOptions): Promise<OrchestrateResult>;

package/dist/providers/oauth-orchestrator.js

@@ -0,0 +1,159 @@
+// Orchestratore del flusso OAuth PKCE di OpenRouter, end-to-end.
+//
+// Compone i pezzi prodotti dagli altri moduli (vassalli):
+//   - oauth-callback-server.ts  -> startCallbackServer(): server locale che
+//     riceve la redirect e cattura il `code`.
+//   - openrouter-auth.ts        -> buildAuthUrlForPort()/callbackUrlForPort()
+//     (URL di autorizzazione) e startOAuthFlow().complete(code) (scambio +
+//     persistenza credenziali).
+//   - auto-open-browser         -> openBrowser(url): apre il browser di sistema
+//     (iniettato come dipendenza, best-effort).
+//
+// Sequenza orchestrata:
+//   1. start server locale (porta effimera, redirectUri noto).
+//   2. genera PKCE challenge e costruisci l'authUrl col redirectUri del server.
+//   3. apri il browser sull'authUrl (best-effort; se fallisce -> fallback
+//      manuale: l'utente apre l'URL a mano).
+//   4. attendi il `code` dal callback, con timeout e gestione errori
+//      (access_denied, mismatch state, timeout, abort).
+//   5. chiudi SEMPRE il server (anche su errore).
+//   6. scambia il `code` per la API key e persisti.
+//
+// Il modulo e' a zero dipendenze runtime e tutte le collaborazioni esterne
+// sono iniettabili, per restare testabile in isolamento.
+import { startOAuthFlow, } from "./openrouter-auth.js";
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+function emit(opts, phase, detail) {
+    try {
+        opts.onEvent?.({ phase, detail });
+    }
+    catch {
+        // un onEvent difettoso non deve rompere il flusso.
+    }
+}
+// ---------------------------------------------------------------------------
+// Orchestrazione
+// ---------------------------------------------------------------------------
+// Esegue l'intero flusso OAuth PKCE. Garantisce la chiusura del server in ogni
+// percorso (successo, errore, timeout, abort). Non lancia: ritorna sempre un
+// OrchestrateResult con esito e categoria d'errore.
+export async function orchestrateOAuth(env, opts) {
+    // Abort precoce: se gia' annullato, non avviare nulla.
+    if (opts.signal?.aborted) {
+        return { ok: false, errorKind: "aborted", error: "operazione annullata" };
+    }
+    let server = null;
+    let authUrl;
+    let browserOpened = false;
+    try {
+        // 1. Avvio server locale.
+        try {
+            server = await opts.startServer({
+                host: opts.host,
+                port: opts.port,
+                path: opts.path,
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            emit(opts, "error", msg);
+            return { ok: false, errorKind: "server", error: `avvio server callback fallito: ${msg}` };
+        }
+        emit(opts, "server_started", server.redirectUri);
+        // 2. PKCE + authUrl col redirectUri reale del server.
+        const flow = startOAuthFlow(env, server.redirectUri, {
+            rand: opts.rand,
+            persist: opts.persist,
+        });
+        // Usa il builder iniettato (puo' differire da quello interno di startOAuthFlow,
+        // es. buildAuthUrlForPort): prevale il builder esplicito.
+        authUrl = opts.buildAuthUrl(server.redirectUri, flow.challenge);
+        emit(opts, "url_built", authUrl);
+        // 3. Apertura browser best-effort. Il fallimento NON interrompe: l'utente
+        //    puo' aprire l'URL manualmente (lo riportiamo nel risultato).
+        if (opts.openBrowser) {
+            try {
+                const res = await opts.openBrowser(authUrl);
+                browserOpened = res.opened;
+                if (res.opened)
+                    emit(opts, "browser_opened", authUrl);
+                else
+                    emit(opts, "browser_failed", res.error ?? "browser non aperto");
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                emit(opts, "browser_failed", msg);
+            }
+        }
+        else {
+            emit(opts, "browser_failed", "nessun opener: apertura manuale");
+        }
+        // 4. Attesa del code con timeout + abort.
+        emit(opts, "awaiting_code");
+        let cb;
+        try {
+            cb = await server.waitForCode({
+                timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                signal: opts.signal,
+            });
+        }
+        catch (err) {
+            // waitForCode puo' rigettare su timeout/abort a seconda dell'implementazione.
+            const msg = err instanceof Error ? err.message : String(err);
+            const aborted = opts.signal?.aborted || /abort/i.test(msg);
+            const kind = aborted ? "aborted" : /timeout|timed out|scadut/i.test(msg) ? "timeout" : "callback";
+            emit(opts, "error", msg);
+            return { ok: false, errorKind: kind, error: msg, authUrl, browserOpened };
+        }
+        // Errore applicativo riportato dal provider nel callback (es. access_denied).
+        if (cb.error) {
+            const detail = cb.errorDescription ? `${cb.error}: ${cb.errorDescription}` : cb.error;
+            emit(opts, "error", detail);
+            return { ok: false, errorKind: "callback", error: detail, authUrl, browserOpened };
+        }
+        const code = (cb.code ?? "").trim();
+        if (!code) {
+            emit(opts, "error", "callback senza code");
+            return { ok: false, errorKind: "callback", error: "callback senza code", authUrl, browserOpened };
+        }
+        emit(opts, "code_received");
+        // 5. Chiudi il server appena ho il code (lo scambio non ne ha piu' bisogno).
+        await safeClose(server);
+        server = null;
+        emit(opts, "server_closed");
+        // 6. Scambio code -> API key (+ persistenza dentro flow.complete).
+        emit(opts, "exchanging");
+        const exchange = await flow.complete(code, {
+            signal: opts.signal,
+            fetchImpl: opts.fetchImpl,
+        });
+        if (!exchange.ok || !exchange.apiKey) {
+            const msg = exchange.error ?? "scambio token fallito";
+            emit(opts, "error", msg);
+            return { ok: false, errorKind: "exchange", error: msg, authUrl, browserOpened };
+        }
+        emit(opts, "done");
+        return { ok: true, apiKey: exchange.apiKey, authUrl, browserOpened };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        emit(opts, "error", msg);
+        return { ok: false, errorKind: "unknown", error: msg, authUrl, browserOpened };
+    }
+    finally {
+        // Cleanup garantito: se il server e' ancora aperto, chiudilo.
+        if (server) {
+            await safeClose(server);
+            emit(opts, "server_closed");
+        }
+    }
+}
+// Chiusura difensiva: non propaga errori di close (best-effort).
+async function safeClose(server) {
+    try {
+        await server.close();
+    }
+    catch {
+        // ignora: la chiusura e' best-effort.
+    }
+}

package/dist/providers/oauth-store.d.ts

@@ -0,0 +1,12 @@
+export interface OAuthCreds {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    accountId?: string;
+}
+export declare function jwtExpiresAt(token: string): number;
+export declare function readClaudeCreds(env: NodeJS.ProcessEnv): OAuthCreds | null;
+export declare function readCodexCreds(env: NodeJS.ProcessEnv): OAuthCreds | null;
+export declare function writeClaudeCreds(env: NodeJS.ProcessEnv, creds: OAuthCreds): void;
+export declare function writeCodexCreds(env: NodeJS.ProcessEnv, creds: OAuthCreds): void;
+export declare function isExpired(creds: OAuthCreds, now: number): boolean;

package/dist/providers/oauth-store.js

@@ -0,0 +1,139 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function numericEpoch(value) {
+    if (typeof value === "number" && Number.isFinite(value) && value > 0)
+        return value;
+    if (typeof value !== "string" || !value.trim())
+        return 0;
+    const numeric = Number(value);
+    return Number.isFinite(numeric) && numeric > 0 ? numeric : 0;
+}
+// I token Codex sono JWT. `last_refresh` nel file ufficiale e' l'istante del
+// refresh, non la scadenza: usarlo come expiresAt rendeva ogni login
+// immediatamente "scaduto". Leggiamo invece il claim `exp`, senza verificare
+// la firma (la verifica resta responsabilita' del server quando il token viene
+// usato).
+export function jwtExpiresAt(token) {
+    const payload = String(token || "").split(".")[1];
+    if (!payload)
+        return 0;
+    try {
+        const normalized = payload.replace(/-/g, "+").replace(/_/g, "/");
+        const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+        const parsed = JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+        const seconds = numericEpoch(parsed["exp"]);
+        return seconds > 0 ? seconds * 1000 : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function claudeFile(env) {
+    const dir = env["CLAUDE_CONFIG_DIR"] || join(homedir(), ".claude");
+    return join(dir, ".credentials.json");
+}
+function codexFile(env) {
+    const dir = env["CODEX_HOME"] || join(homedir(), ".codex");
+    return join(dir, "auth.json");
+}
+function readJson(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const data = JSON.parse(readFileSync(path, "utf8"));
+        return typeof data === "object" && data !== null
+            ? data
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Credenziali Claude Code. Priorita': token diretto da env (claude setup-token),
+// poi il file .credentials.json (campo claudeAiOauth).
+export function readClaudeCreds(env) {
+    const direct = String(env["CLAUDE_CODE_OAUTH_TOKEN"] ?? "").trim();
+    if (direct)
+        return { accessToken: direct, refreshToken: "", expiresAt: 0 };
+    const json = readJson(claudeFile(env));
+    const o = json?.["claudeAiOauth"];
+    if (!o)
+        return null;
+    const accessToken = String(o["accessToken"] ?? "");
+    if (!accessToken)
+        return null;
+    return {
+        accessToken,
+        refreshToken: String(o["refreshToken"] ?? ""),
+        expiresAt: Number(o["expiresAt"] ?? 0),
+    };
+}
+// Credenziali ChatGPT/Codex (subscription). Il file ha { tokens: {...} } oppure
+// una OPENAI_API_KEY (che NON e' un abbonamento: la ignoriamo qui).
+export function readCodexCreds(env) {
+    const json = readJson(codexFile(env));
+    const authMode = String(json?.["auth_mode"] ?? "").trim().toLowerCase().replace(/[_\s-]+/g, "");
+    // Dopo l'unificazione di Codex con ChatGPT il provider resta OpenAI, mentre
+    // questo campo e' l'autorita' sul tipo di consumo. Token rimasti da un login
+    // precedente non devono trasformare `apiKey` in un falso abbonamento.
+    if (authMode && authMode !== "chatgpt" && authMode !== "chatgptauthtokens")
+        return null;
+    const t = json?.["tokens"];
+    if (!t)
+        return null;
+    const accessToken = String(t["access_token"] ?? "");
+    if (!accessToken)
+        return null;
+    return {
+        accessToken,
+        refreshToken: String(t["refresh_token"] ?? ""),
+        // `expires_at` e' il campo Talos best-effort; per i file creati dal CLI
+        // ufficiale ricaviamo la scadenza dal JWT. `last_refresh` non va usato.
+        expiresAt: numericEpoch(json?.["expires_at"]) || jwtExpiresAt(accessToken),
+        accountId: String(t["account_id"] ?? "") || undefined,
+    };
+}
+// Persiste i token Claude rinnovati nel file (best-effort).
+export function writeClaudeCreds(env, creds) {
+    try {
+        const path = claudeFile(env);
+        const json = readJson(path) ?? {};
+        json["claudeAiOauth"] = {
+            ...json["claudeAiOauth"],
+            accessToken: creds.accessToken,
+            refreshToken: creds.refreshToken,
+            expiresAt: creds.expiresAt,
+        };
+        writeFileSync(path, JSON.stringify(json, null, 2), "utf8");
+    }
+    catch {
+        /* persistenza best-effort: se fallisce, si rifa' refresh al prossimo giro */
+    }
+}
+export function writeCodexCreds(env, creds) {
+    try {
+        const path = codexFile(env);
+        const json = readJson(path) ?? {};
+        const prev = json["tokens"] ?? {};
+        json["auth_mode"] = "chatgpt";
+        json["tokens"] = {
+            ...prev,
+            access_token: creds.accessToken,
+            refresh_token: creds.refreshToken,
+            account_id: creds.accountId ?? prev["account_id"],
+        };
+        // Mantiene il formato usato dal CLI Codex e conserva separatamente la
+        // scadenza calcolata da Talos.
+        json["last_refresh"] = new Date().toISOString();
+        json["expires_at"] = creds.expiresAt;
+        writeFileSync(path, JSON.stringify(json, null, 2), "utf8");
+    }
+    catch {
+        /* best-effort */
+    }
+}
+// True se il token e' scaduto (o lo sara' entro 60s). expiresAt 0 = non lo sappiamo.
+export function isExpired(creds, now) {
+    return creds.expiresAt > 0 && creds.expiresAt - 60_000 <= now;
+}