@vascend/talos 0.1.0

package/dist/providers/openrouter-auth.js

@@ -0,0 +1,321 @@
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { loadCredentials } from "../core/credentials.js";
+import { talosConfigDir } from "../core/env-paths.js";
+// Modulo di autenticazione OpenRouter. Supporta due percorsi:
+//   1. API key manuale (l'utente incolla la chiave generata sul sito).
+//   2. OAuth PKCE: l'utente autorizza nel browser, OpenRouter rimanda un
+//      `code`, lo scambiamo per una user-controlled API key.
+// Le credenziali sono salvate in ~/.talos/openrouter.json (override via env),
+// separate dal config globale per non mescolarle con i settings dell'utente.
+//
+// Riferimento: https://openrouter.ai/docs/use-cases/oauth-pkce
+const AUTH_BASE = "https://openrouter.ai/auth";
+const KEYS_EXCHANGE_URL = "https://openrouter.ai/api/v1/auth/keys";
+const KEY_INFO_URL = "https://openrouter.ai/api/v1/key";
+// ---------------------------------------------------------------------------
+// Storage sicuro
+// ---------------------------------------------------------------------------
+// Posizione del file credenziali. null se lo storage e' disattivato.
+export function credsPath(env) {
+    if (env["TALOS_NO_GLOBAL_CONFIG"] === "1")
+        return null;
+    const override = String(env["TALOS_OPENROUTER_CREDS_FILE"] ?? "").trim();
+    if (override)
+        return override;
+    return join(talosConfigDir(env), "openrouter.json");
+}
+function readJson(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const data = JSON.parse(readFileSync(path, "utf8"));
+        return typeof data === "object" && data !== null && !Array.isArray(data)
+            ? data
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Legge le credenziali OpenRouter. Priorita': chiave da env (a consumo, gestita
+// fuori da Talos) poi il file su disco. La chiave da env non viene persistita.
+export function readOpenRouterCreds(env) {
+    const fromEnv = String(env["TALOS_OPENROUTER_API_KEY"] ?? env["OPENROUTER_API_KEY"] ?? "").trim();
+    if (fromEnv)
+        return { apiKey: fromEnv, source: "manual", obtainedAt: 0 };
+    const path = credsPath(env);
+    if (!path)
+        return null;
+    const json = readJson(path);
+    if (!json)
+        return null;
+    const apiKey = String(json["apiKey"] ?? "").trim();
+    if (!apiKey)
+        return null;
+    const source = json["source"] === "oauth" ? "oauth" : "manual";
+    return { apiKey, source, obtainedAt: Number(json["obtainedAt"] ?? 0) };
+}
+// Persiste le credenziali su disco con permessi restrittivi (0600). Best-effort:
+// ritorna false se la scrittura fallisce, true altrimenti.
+export function writeOpenRouterCreds(env, creds) {
+    const path = credsPath(env);
+    if (!path)
+        return false;
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        const body = JSON.stringify({ apiKey: creds.apiKey, source: creds.source, obtainedAt: creds.obtainedAt || Date.now() }, null, 2);
+        // mode 0600: leggibile/scrivibile solo dal proprietario.
+        writeFileSync(path, body + "\n", { encoding: "utf8", mode: 0o600 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Cancella le credenziali salvate (logout). True se rimosse o gia' assenti.
+export function clearOpenRouterCreds(env) {
+    const path = credsPath(env);
+    if (!path)
+        return false;
+    try {
+        if (existsSync(path))
+            writeFileSync(path, JSON.stringify({}, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// base64url senza padding (RFC 7636).
+function base64Url(buf) {
+    return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+// Genera un code_verifier random (43-128 char) e il code_challenge S256.
+export function createPkceChallenge(rand = randomBytes) {
+    // 32 byte -> 43 char base64url: dentro i limiti RFC 7636.
+    const codeVerifier = base64Url(rand(32));
+    const codeChallenge = base64Url(createHash("sha256").update(codeVerifier).digest());
+    return { codeVerifier, codeChallenge, method: "S256" };
+}
+// Costruisce l'URL a cui mandare l'utente per autorizzare. `callbackUrl` deve
+// combaciare con quello usato allo scambio (per i CLI: spesso un localhost o un
+// URL pubblico del progetto per l'app attribution).
+export function buildAuthUrl(callbackUrl, challenge) {
+    const params = new URLSearchParams({
+        callback_url: callbackUrl,
+        code_challenge: challenge.codeChallenge,
+        code_challenge_method: challenge.method,
+    });
+    return `${AUTH_BASE}?${params.toString()}`;
+}
+// Path del callback su cui il server locale ascolta il redirect di OpenRouter.
+export const CALLBACK_PATH = "/callback";
+// Porta di default del server di callback locale (concordata con i peer).
+export const DEFAULT_CALLBACK_PORT = 8976;
+// Compone l'URL di callback che punta al server locale: per i CLI il redirect
+// di OpenRouter torna su un loopback (http://localhost:porta/callback) invece
+// che su un dominio pubblico (es. vascend.dev). `host` resta configurabile per
+// chi preferisce 127.0.0.1; lo schema e' http perche' e' loopback.
+export function callbackUrlForPort(port = DEFAULT_CALLBACK_PORT, host = "localhost") {
+    const p = Number(port);
+    if (!Number.isInteger(p) || p < 1 || p > 65535) {
+        throw new RangeError(`porta callback non valida: ${port}`);
+    }
+    // new URL normalizza host/porta; pathname garantisce il /callback esatto.
+    const url = new URL(`http://${host}:${p}`);
+    url.pathname = CALLBACK_PATH;
+    return url.toString().replace(/\/$/, "");
+}
+// Scorciatoia: costruisce l'URL di autorizzazione usando come callback_url il
+// server locale sulla porta data. Unisce callbackUrlForPort + buildAuthUrl, con
+// l'encoding dei parametri gestito da URLSearchParams.
+export function buildAuthUrlForPort(port, challenge, host = "localhost") {
+    return buildAuthUrl(callbackUrlForPort(port, host), challenge);
+}
+// Scambia il `code` ricevuto nel callback per una user-controlled API key.
+// Usa il code_verifier generato in createPkceChallenge.
+export async function exchangeCodeForKey(code, codeVerifier, opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const trimmed = code.trim();
+    if (!trimmed)
+        return { ok: false, error: "code mancante" };
+    try {
+        const res = await doFetch(KEYS_EXCHANGE_URL, {
+            method: "POST",
+            signal: opts.signal,
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({
+                code: trimmed,
+                code_verifier: codeVerifier,
+                code_challenge_method: "S256",
+            }),
+        });
+        if (!res.ok) {
+            const detail = await res.text().catch(() => res.statusText);
+            return { ok: false, error: `scambio fallito (${res.status}): ${detail}` };
+        }
+        const json = (await res.json());
+        const key = String(json["key"] ?? "").trim();
+        if (!key)
+            return { ok: false, error: "risposta priva di key" };
+        return { ok: true, apiKey: key };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+export function startOAuthFlow(env, callbackUrl, opts = {}) {
+    const challenge = createPkceChallenge(opts.rand);
+    const authUrl = buildAuthUrl(callbackUrl, challenge);
+    const persist = opts.persist !== false;
+    return {
+        authUrl,
+        challenge,
+        async complete(code, callOpts = {}) {
+            const result = await exchangeCodeForKey(code, challenge.codeVerifier, callOpts);
+            if (result.ok && result.apiKey && persist) {
+                writeOpenRouterCreds(env, { apiKey: result.apiKey, source: "oauth", obtainedAt: Date.now() });
+            }
+            return result;
+        },
+    };
+}
+// Valida una API key interrogando l'endpoint /key di OpenRouter, che ritorna i
+// metadati della chiave autenticata. 401/403 => chiave non valida.
+export async function validateApiKey(apiKey, opts = {}) {
+    const key = apiKey.trim();
+    if (!key)
+        return { ok: false, error: "API key mancante" };
+    const doFetch = opts.fetchImpl ?? fetch;
+    const signal = opts.signal ?? AbortSignal.timeout(opts.timeoutMs ?? 8000);
+    try {
+        const res = await doFetch(KEY_INFO_URL, {
+            method: "GET",
+            signal,
+            headers: { authorization: `Bearer ${key}`, accept: "application/json" },
+        });
+        if (res.status === 401 || res.status === 403) {
+            return { ok: false, error: "API key non valida o non autorizzata" };
+        }
+        if (!res.ok) {
+            const detail = await res.text().catch(() => res.statusText);
+            return { ok: false, error: `validazione fallita (${res.status}): ${detail}` };
+        }
+        const json = (await res.json());
+        const data = json["data"] ?? json;
+        const limitRaw = data["limit_remaining"];
+        return {
+            ok: true,
+            label: typeof data["label"] === "string" ? data["label"] : undefined,
+            limitRemaining: limitRaw === null || limitRaw === undefined ? null : Number(limitRaw),
+            usage: data["usage"] !== undefined ? Number(data["usage"]) : undefined,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: msg };
+    }
+}
+// Controllo di forma di una API key OpenRouter (sk-or-...). Non garantisce la
+// validita' (per quella serve validateApiKey), ma intercetta refusi evidenti.
+export function looksLikeApiKey(value) {
+    const v = value.trim();
+    return /^sk-or-[A-Za-z0-9._-]{8,}$/.test(v);
+}
+// Salva una API key inserita manualmente, dopo averla (opzionalmente) validata.
+// Se `validate` e' true (default) e la chiave non e' valida, NON la persiste.
+export async function saveManualApiKey(env, apiKey, opts = {}) {
+    const key = apiKey.trim();
+    if (!key)
+        return { saved: false, error: "API key mancante" };
+    if (opts.validate !== false) {
+        const validation = await validateApiKey(key, { signal: opts.signal, fetchImpl: opts.fetchImpl });
+        if (!validation.ok)
+            return { saved: false, validation, error: validation.error };
+        const saved = writeOpenRouterCreds(env, { apiKey: key, source: "manual", obtainedAt: Date.now() });
+        return { saved, validation };
+    }
+    const saved = writeOpenRouterCreds(env, { apiKey: key, source: "manual", obtainedAt: Date.now() });
+    return { saved };
+}
+// ---------------------------------------------------------------------------
+// Coesistenza dei metodi di accesso (env API key + OAuth/file + config salvato)
+// ---------------------------------------------------------------------------
+//
+// Per OpenRouter possono coesistere PIU' fonti di credenziale, tutte valide:
+//   1. variabile d'ambiente esportata dall'utente
+//      (OPENROUTER_API_KEY o la scoped TALOS_OPENROUTER_API_KEY) - a consumo;
+//   2. credenziale salvata nel config globale (~/.talos/config.json[providers]);
+//   3. file dedicato ~/.talos/openrouter.json scritto da OAuth o inserimento
+//      manuale (readOpenRouterCreds).
+// La presenza simultanea NON deve produrre un conflitto ne' lo stato "nessun
+// metodo configurato": basta che UNA fonte abbia una chiave perche' l'accesso
+// sia considerato configurato. La scelta del metodo e' deterministica e segue
+// la precedenza sopra (1 > 2 > 3). Le fonti scartate vengono solo ignorate.
+// Identificatore del provider OpenRouter nel catalogo/config.
+const OPENROUTER_PROVIDER_ID = "openrouter";
+// Nome della env var scoped, allineato a registry.ts/credentials.ts.
+const OPENROUTER_SCOPED_ENV = "TALOS_OPENROUTER_API_KEY";
+// Risolve in modo PURO e DETERMINISTICO quale metodo di accesso OpenRouter usare
+// quando piu' fonti coesistono. Non esegue rete ne' scrive nulla. Garanzie:
+//   - se almeno una fonte ha una chiave => configured=true (mai stato vuoto);
+//   - la precedenza env > saved > oauth/manual evita ambiguita'/conflitti;
+//   - `available` elenca TUTTE le fonti presenti, per trasparenza nella UI.
+export function resolveOpenRouterAccess(env) {
+    const available = [];
+    // 1. Env esportata dall'utente (nuda o scoped). Massima precedenza: e' una
+    //    scelta esplicita e a consumo, gestita fuori da Talos.
+    const envKey = String(env["OPENROUTER_API_KEY"] ?? env[OPENROUTER_SCOPED_ENV] ?? "").trim();
+    if (envKey)
+        available.push("env");
+    // 2. Credenziale salvata nel config globale (config.json[providers]).
+    const savedKey = String(loadCredentials(env)[OPENROUTER_PROVIDER_ID]?.apiKey ?? "").trim();
+    if (savedKey)
+        available.push("saved");
+    // 3. File dedicato (OAuth o inserimento manuale). Leggiamo il file SENZA
+    //    passare per l'override env di readOpenRouterCreds: qui valutiamo la fonte
+    //    su disco in modo indipendente, cosi' "available" riflette davvero la
+    //    coesistenza. Per farlo usiamo readFileCredsOnly che ignora le env.
+    const fileCreds = readFileCredsOnly(env);
+    if (fileCreds?.apiKey)
+        available.push(fileCreds.source === "oauth" ? "oauth" : "manual");
+    if (available.length === 0) {
+        return {
+            configured: false,
+            available,
+            reason: "nessuna fonte di credenziale OpenRouter (env, config salvato o login OAuth)",
+        };
+    }
+    const method = available[0];
+    const apiKey = method === "env" ? envKey : method === "saved" ? savedKey : fileCreds.apiKey;
+    const reason = available.length > 1
+        ? `piu' fonti presenti (${available.join(", ")}); scelta "${method}" per precedenza`
+        : `unica fonte: "${method}"`;
+    return { configured: true, apiKey, method, available, reason };
+}
+// Legge SOLO il file dedicato openrouter.json, ignorando le env key. Serve a
+// resolveOpenRouterAccess per distinguere la fonte-file dalla fonte-env quando
+// coesistono (readOpenRouterCreds darebbe priorita' all'env e maschererebbe il
+// file). Mantiene la stessa validazione di forma di readOpenRouterCreds.
+function readFileCredsOnly(env) {
+    const path = credsPath(env);
+    if (!path)
+        return null;
+    const json = readJson(path);
+    if (!json)
+        return null;
+    const apiKey = String(json["apiKey"] ?? "").trim();
+    if (!apiKey)
+        return null;
+    const source = json["source"] === "oauth" ? "oauth" : "manual";
+    return { apiKey, source, obtainedAt: Number(json["obtainedAt"] ?? 0) };
+}
+// Helper di precedenza riusabile (es. dal registry): ritorna la chiave da usare
+// per OpenRouter considerando tutte le fonti, oppure null se nessuna esiste.
+// Cosi' il registry puo' registrare il provider senza ricomporre la logica.
+export function openRouterApiKey(env) {
+    const access = resolveOpenRouterAccess(env);
+    return access.configured ? access.apiKey ?? null : null;
+}

package/dist/providers/openrouter-manual-fallback.d.ts

@@ -0,0 +1,25 @@
+import type { OAuthFlow } from "./openrouter-auth.js";
+export declare function normalizeAuthCode(raw: string): string;
+export declare function isLikelyAuthCode(value: string): boolean;
+export interface ManualInstructions {
+    readonly lines: readonly string[];
+    readonly authUrl: string;
+}
+export declare function buildManualInstructions(authUrl: string, reason?: string): ManualInstructions;
+export interface ManualFallbackIo {
+    print(line: string): void;
+    prompt(label: string): Promise<string | null>;
+}
+export interface ManualFallbackOptions {
+    readonly reason?: string;
+    readonly maxAttempts?: number;
+    readonly signal?: AbortSignal;
+    readonly fetchImpl?: typeof fetch;
+}
+export interface ManualFallbackResult {
+    readonly ok: boolean;
+    readonly apiKey?: string;
+    readonly error?: string;
+    readonly attempts: number;
+}
+export declare function runManualCodeFallback(io: ManualFallbackIo, flow: OAuthFlow, opts?: ManualFallbackOptions): Promise<ManualFallbackResult>;

package/dist/providers/openrouter-manual-fallback.js

@@ -0,0 +1,161 @@
+// Fallback manuale per il login OAuth di OpenRouter.
+//
+// Quando il callback automatico sul server locale non e' percorribile (porta
+// occupata, niente browser, sessione remota/SSH, redirect bloccato da firewall)
+// dobbiamo comunque permettere all'utente di completare il giro PKCE a mano:
+//   1. mostriamo il link di autorizzazione (cliccabile e copiabile);
+//   2. spieghiamo cosa fare con parole semplici;
+//   3. chiediamo di incollare il `code` che OpenRouter mostra/redirige;
+//   4. validiamo l'input (anche se incolla l'intero URL del callback) e
+//      scambiamo il code per la API key, con possibilita' di ritentare.
+//
+// Modulo PURO e testabile: tutto l'I/O passa per l'interfaccia ManualFallbackIo
+// (niente accesso diretto a stdin/stdout/console), e lo scambio del code arriva
+// dall'OAuthFlow.complete gia' fornito da openrouter-auth.ts. Nessun side effect
+// nascosto, niente dipendenze a runtime.
+// ---------------------------------------------------------------------------
+// Validazione / normalizzazione del code incollato
+// ---------------------------------------------------------------------------
+// Estrae e normalizza il `code` da cio' che l'utente incolla. Tollerante:
+//   - URL completo del callback ("http://localhost:8976/callback?code=ABC&...")
+//   - querystring nuda ("?code=ABC&state=x" o "code=ABC")
+//   - code nudo ("ABC123"), con eventuali spazi/virgolette/backtick attorno
+// Ritorna il code ripulito, o "" se non se ne ricava uno plausibile.
+export function normalizeAuthCode(raw) {
+    if (typeof raw !== "string")
+        return "";
+    // Rimuove spazi esterni e una eventuale coppia di virgolette/backtick/angolari
+    // (capita copiando da chat o markdown: <url>, "code", `code`).
+    let s = raw.trim().replace(/^[<"'`\s]+/, "").replace(/[>"'`\s]+$/, "").trim();
+    if (!s)
+        return "";
+    // Caso 1: e' un URL assoluto -> leggi ?code= dalla query.
+    const fromUrl = tryExtractFromUrl(s);
+    if (fromUrl !== null)
+        return fromUrl;
+    // Caso 2: contiene una querystring con code= (anche senza schema/host).
+    const fromQuery = tryExtractFromQuery(s);
+    if (fromQuery !== null)
+        return fromQuery;
+    // Caso 3: code nudo. Tieni solo il primo token non-spazio e togli un
+    // eventuale separatore residuo (& o # con roba dietro).
+    s = s.split(/[\s]/)[0] ?? s;
+    const amp = s.indexOf("&");
+    if (amp >= 0)
+        s = s.slice(0, amp);
+    const hash = s.indexOf("#");
+    if (hash >= 0)
+        s = s.slice(0, hash);
+    return s.trim();
+}
+function tryExtractFromUrl(s) {
+    if (!/^https?:\/\//i.test(s))
+        return null;
+    try {
+        const u = new URL(s);
+        const code = u.searchParams.get("code");
+        return code ? code.trim() : "";
+    }
+    catch {
+        return null;
+    }
+}
+function tryExtractFromQuery(s) {
+    if (!/(^|[?&])code=/.test(s))
+        return null;
+    const q = s.startsWith("?") ? s.slice(1) : s;
+    try {
+        const params = new URLSearchParams(q);
+        const code = params.get("code");
+        if (code)
+            return code.trim();
+    }
+    catch {
+        // fallthrough al parse manuale
+    }
+    const m = s.match(/[?&]?code=([^&#\s]+)/);
+    return m && m[1] ? decodeURIComponent(m[1]).trim() : "";
+}
+// Controllo di forma di un authorization code OpenRouter. Non garantisce la
+// validita' (per quella serve lo scambio), ma intercetta input vuoti o palesemente
+// sbagliati (URL incollato male, frasi, spazi). I code OpenRouter sono token
+// opachi: accettiamo una sequenza ragionevole di caratteri URL-safe.
+export function isLikelyAuthCode(value) {
+    const v = (value ?? "").trim();
+    if (v.length < 8 || v.length > 512)
+        return false;
+    if (/\s/.test(v))
+        return false;
+    return /^[A-Za-z0-9._~-]+$/.test(v);
+}
+// Costruisce le istruzioni per il percorso manuale. `reason` (opzionale) spiega
+// perche' siamo qui (es. "porta 8976 occupata", "nessun browser disponibile"):
+// se assente usiamo un messaggio neutro.
+export function buildManualInstructions(authUrl, reason) {
+    const why = (reason ?? "").trim();
+    const lines = [];
+    lines.push("Login OpenRouter — modalita' manuale");
+    if (why) {
+        lines.push(`(callback automatico non disponibile: ${why})`);
+    }
+    else {
+        lines.push("(callback automatico non disponibile: completiamo a mano)");
+    }
+    lines.push("");
+    lines.push("1. Apri questo link nel browser (copialo se non e' cliccabile):");
+    lines.push(`   ${authUrl}`);
+    lines.push("");
+    lines.push("2. Autorizza l'accesso su OpenRouter.");
+    lines.push("3. Verrai rediretto a un indirizzo localhost che potrebbe non");
+    lines.push("   aprirsi (\"impossibile raggiungere il sito\"): e' normale.");
+    lines.push("4. Copia il valore del parametro `code` dalla barra degli indirizzi");
+    lines.push("   (oppure incolla l'intero URL: estraggo io il code).");
+    lines.push("5. Incollalo qui sotto e premi Invio.");
+    return { lines, authUrl };
+}
+// Esegue il percorso di fallback manuale: mostra link+istruzioni, chiede il
+// code, lo normalizza/valida, lo scambia via flow.complete e ripete in caso di
+// input invalido o scambio fallito, fino a maxAttempts o annullamento.
+export async function runManualCodeFallback(io, flow, opts = {}) {
+    const maxAttempts = Math.max(1, Math.floor(opts.maxAttempts ?? 3));
+    const instructions = buildManualInstructions(flow.authUrl, opts.reason);
+    for (const line of instructions.lines)
+        io.print(line);
+    let attempts = 0;
+    let lastError = "";
+    while (attempts < maxAttempts) {
+        const remaining = maxAttempts - attempts;
+        const hint = attempts === 0 ? "" : ` (tentativi rimasti: ${remaining})`;
+        const raw = await io.prompt(`Incolla il code${hint}`);
+        // Annullamento esplicito (Esc/EOF): usciamo subito senza consumare logica.
+        if (raw === null) {
+            return { ok: false, error: "cancelled", attempts };
+        }
+        attempts += 1;
+        const code = normalizeAuthCode(raw);
+        if (!isLikelyAuthCode(code)) {
+            lastError = "code non riconosciuto";
+            if (attempts < maxAttempts) {
+                io.print("Input non valido: incolla il code (o l'intero URL del callback). Riprova.");
+            }
+            continue;
+        }
+        let result;
+        try {
+            result = await flow.complete(code, { signal: opts.signal, fetchImpl: opts.fetchImpl });
+        }
+        catch (err) {
+            result = { ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+        if (result.ok && result.apiKey) {
+            io.print("Autenticazione completata: API key ottenuta e salvata.");
+            return { ok: true, apiKey: result.apiKey, attempts };
+        }
+        lastError = result.error ?? "scambio fallito";
+        if (attempts < maxAttempts) {
+            io.print(`Scambio fallito: ${lastError}. Verifica di aver copiato il code giusto e riprova.`);
+        }
+    }
+    io.print("Tentativi esauriti: login manuale non riuscito.");
+    return { ok: false, error: lastError || "exhausted", attempts };
+}

package/dist/providers/openrouter.d.ts

@@ -0,0 +1,15 @@
+export interface OpenRouterModel {
+    readonly id: string;
+    readonly name?: string;
+    readonly contextLength?: number;
+    readonly promptPrice?: number;
+    readonly completionPrice?: number;
+    readonly isFree?: boolean;
+}
+export declare function parseOpenRouterModels(payload: unknown): readonly OpenRouterModel[];
+export declare function fetchOpenRouterModels(env?: NodeJS.ProcessEnv, opts?: {
+    readonly force?: boolean;
+    readonly timeoutMs?: number;
+}): Promise<readonly OpenRouterModel[]>;
+export declare function openRouterDetail(model: OpenRouterModel): string;
+export declare function _resetOpenRouterCache(): void;

package/dist/providers/openrouter.js

@@ -0,0 +1,107 @@
+// Catalogo dinamico dei modelli OpenRouter. OpenRouter espone centinaia di
+// modelli: la lista statica nel catalogo e' solo un seme. Qui scarichiamo
+// l'elenco completo dall'endpoint pubblico `/models` (nessuna chiave richiesta)
+// per alimentare il picker con barra di ricerca.
+const ENDPOINT = "https://openrouter.ai/api/v1/models";
+// Cache di sessione: l'elenco cambia di rado, evitiamo round-trip ripetuti.
+let cache = null;
+let inflight = null;
+function apiKey(env) {
+    return String(env["TALOS_OPENROUTER_API_KEY"] ?? env["OPENROUTER_API_KEY"] ?? "").trim();
+}
+function priceK(raw) {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    // OpenRouter espone il prezzo per singolo token: riportiamo a USD/1M.
+    return Math.round(n * 1_000_000 * 100) / 100;
+}
+export function parseOpenRouterModels(payload) {
+    const data = payload?.data;
+    if (!Array.isArray(data))
+        return [];
+    const out = [];
+    for (const raw of data) {
+        const item = raw;
+        const id = typeof item["id"] === "string" ? item["id"].trim() : "";
+        if (!id)
+            continue;
+        const pricing = item["pricing"];
+        const ctx = Number(item["context_length"]);
+        const promptPrice = priceK(pricing?.["prompt"]);
+        const completionPrice = priceK(pricing?.["completion"]);
+        // Gratuito: OpenRouter marca gli id free col suffisso `:free`, oppure il
+        // prezzo prompt+completion e' azzerato (priceK -> undefined su 0).
+        const isFree = id.endsWith(":free") || (promptPrice === undefined && completionPrice === undefined);
+        out.push({
+            id,
+            name: typeof item["name"] === "string" ? item["name"] : undefined,
+            contextLength: Number.isFinite(ctx) && ctx > 0 ? ctx : undefined,
+            promptPrice,
+            completionPrice,
+            isFree,
+        });
+    }
+    out.sort((a, b) => a.id.localeCompare(b.id));
+    return out;
+}
+// Scarica (e memorizza) l'elenco modelli OpenRouter. Fallisce in modo morbido:
+// in caso di errore o timeout restituisce [], cosi' il picker resta usabile coi
+// suggerimenti statici. `force` ignora la cache.
+export async function fetchOpenRouterModels(env = process.env, opts = {}) {
+    if (cache && !opts.force)
+        return cache;
+    if (inflight && !opts.force)
+        return inflight;
+    const run = (async () => {
+        const headers = { accept: "application/json" };
+        const key = apiKey(env);
+        if (key)
+            headers["authorization"] = `Bearer ${key}`;
+        headers["http-referer"] = "https://vascend.dev";
+        headers["x-title"] = "Vascend Talos";
+        try {
+            const res = await fetch(ENDPOINT, {
+                method: "GET",
+                headers,
+                signal: AbortSignal.timeout(opts.timeoutMs ?? 8000),
+            });
+            if (!res.ok)
+                return cache ?? [];
+            const models = parseOpenRouterModels(await res.json());
+            if (models.length)
+                cache = models;
+            return cache ?? models;
+        }
+        catch {
+            return cache ?? [];
+        }
+        finally {
+            inflight = null;
+        }
+    })();
+    inflight = run;
+    return run;
+}
+// Riepilogo compatto per la colonna di dettaglio del picker.
+export function openRouterDetail(model) {
+    const parts = [];
+    if (model.contextLength) {
+        parts.push(model.contextLength >= 1000 ? `${Math.round(model.contextLength / 1000)}k ctx` : `${model.contextLength} ctx`);
+    }
+    if (model.promptPrice !== undefined || model.completionPrice !== undefined) {
+        const usd = "$";
+        parts.push(`${usd}${model.promptPrice ?? "?"}/${model.completionPrice ?? "?"} per 1M`);
+    }
+    else if (model.isFree) {
+        // Nessun prezzo = gratuito: mostriamo il tag, cosi' la barra di ricerca del
+        // picker filtra i modelli free digitando "free".
+        parts.push("free");
+    }
+    return parts.join(" · ") || (model.name ?? "OpenRouter");
+}
+// Solo per i test: ripulisce la cache di sessione.
+export function _resetOpenRouterCache() {
+    cache = null;
+    inflight = null;
+}

package/dist/providers/plan-limits.d.ts

@@ -0,0 +1,6 @@
+import type { PlanLimits } from "../core/types.js";
+export interface HeaderReader {
+    get(name: string): string | null;
+    forEach?(callback: (value: string, key: string) => void): void;
+}
+export declare function planLimitsFromHeaders(providerId: string, headers: HeaderReader, now?: number): PlanLimits | null;