talos-code 0.0.1 → 0.1.0

package/vendor/harness-ui/src/model-catalog-models-dev.mjs

@@ -0,0 +1,276 @@
+/**
+ * P-E, 12/09/2026: API models.dev dietro un contratto AVM.
+ * Ricerca, pin, licenza e collegamenti non applicati nel rapporto P-E in harness-ui/.claude/.
+ * I prezzi sono dichiarazioni per la stima; questo modulo non calcola la spesa di una sessione.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { fornitore, catalogoDiRiservaPer } from './provider-registry.mjs';
+
+export const MODELS_DEV_SCHEMA_REVISION = 'e7a74d6dc7ce56d1a9dda94c18fcf185248d77b4';
+const URL_PREDEFINITO = 'https://models.dev/api.json';
+// Politica applicativa ripresa da Hermes; non è una promessa di aggiornamento della fonte.
+const TTL_MS = 4 * 60 * 60 * 1000;
+const RINVIO_MS = 5 * 60 * 1000;
+const LICENZA_DATI = `MIT License
+
+Copyright (c) 2025 models.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.`;
+
+export class ModelsDevCatalogError extends Error {
+  constructor(message, code = 'CATALOG_UNAVAILABLE') {
+    super(message);
+    this.name = 'ModelsDevCatalogError';
+    this.code = code;
+  }
+}
+
+// Nessuna coercizione: false, stringa vuota e null non sono il numero zero.
+const Numero = z.number().finite().nonnegative();
+const Prezzi = z.object({
+  input: Numero.nullish(), output: Numero.nullish(),
+  cache_read: Numero.nullish(), cache_write: Numero.nullish(),
+  reasoning: Numero.nullish(), input_audio: Numero.nullish(), output_audio: Numero.nullish(),
+});
+const Fascia = Prezzi.extend({ tier: z.object({ type: z.literal('context'), size: Numero.int() }) });
+const Costi = Prezzi.extend({ tiers: z.array(Fascia).optional(), context_over_200k: Prezzi.optional() });
+const Identificatore = z.string().min(1).max(1024);
+const Modello = z.object({
+  id: Identificatore, name: z.string().min(1).optional(),
+  limit: z.object({ context: Numero.nullish(), input: Numero.nullish(), output: Numero.nullish() }).nullish(),
+  cost: Costi.nullish(), tool_call: z.boolean().nullish(), reasoning: z.boolean().nullish(),
+  modalities: z.object({ input: z.array(z.string()).optional(), output: z.array(z.string()).optional() }).nullish(),
+  release_date: z.string().optional(), last_updated: z.string().optional(),
+});
+const Catalogo = z.record(Identificatore, z.object({
+  id: Identificatore, name: z.string().min(1), models: z.record(Identificatore, Modello),
+})).superRefine((dati, ctx) => {
+  if (!Object.keys(dati).length) ctx.addIssue({ code: 'custom', message: 'Catalogo vuoto' });
+  for (const [id, p] of Object.entries(dati)) {
+    if (p.id !== id) ctx.addIssue({ code: 'custom', message: 'Identità fornitore incoerente' });
+    for (const [modelloId, m] of Object.entries(p.models)) {
+      if (m.id !== modelloId) ctx.addIssue({ code: 'custom', message: 'Identità modello incoerente' });
+    }
+  }
+});
+const Etag = z.string().regex(/^(W\/)?"[^"\r\n]*"$/u).max(1024).nullable();
+const Busta = z.object({
+  versione: z.literal(1), schemaRevision: z.literal(MODELS_DEV_SCHEMA_REVISION),
+  url: z.string(), etag: Etag,
+  acquisitoAlle: z.number().int().nonnegative(), verificatoAlle: z.number().int().nonnegative(),
+  sha256: z.string().regex(/^[a-f0-9]{64}$/u), dati: Catalogo,
+});
+const impronta = testo => createHash('sha256').update(testo).digest('hex');
+const numeroOppureNull = valore => typeof valore === 'number' && Number.isFinite(valore) && valore >= 0 ? valore : null;
+const perToken = valore => valore == null ? null : valore / 1_000_000;
+const eta = (ora, acquisitoAlle) => ora >= acquisitoAlle ? ora - acquisitoAlle : null;
+
+function prezziPerMilione(costi) {
+  return {
+    valuta: 'USD', unita: 'milione-token',
+    ...Object.fromEntries(['input', 'output', 'cache_read', 'cache_write', 'reasoning', 'input_audio', 'output_audio'].map(k => [k, numeroOppureNull(costi?.[k])])),
+    tiers: structuredClone(costi?.tiers ?? []),
+    context_over_200k: structuredClone(costi?.context_over_200k ?? null),
+  };
+}
+
+function normalizza(m, record, metadati) {
+  const prezzi = prezziPerMilione(m.cost);
+  return {
+    // Solo OpenRouter usa gli id senza prefisso di destinazione; gli id upstream restano intatti.
+    id: record.id === 'openrouter' ? m.id : `${record.id}:${m.id}`,
+    modelId: m.id, provider: record.id, nome: m.name || 'Nome non disponibile', alias: false,
+    contextLength: m.limit?.context > 0 ? m.limit.context : null,
+    maxOutputTokens: m.limit?.output > 0 ? m.limit.output : null,
+    maxInputTokens: m.limit?.input > 0 ? m.limit.input : null,
+    contestoVerificato: false,
+    prezzoPrompt: perToken(prezzi.input), prezzoCompletion: perToken(prezzi.output),
+    prezzoCacheRead: perToken(prezzi.cache_read), prezzoCacheWrite: perToken(prezzi.cache_write),
+    prezziPerMilione: prezzi,
+    capacita: { toolCall: m.tool_call ?? null, reasoning: m.reasoning ?? null },
+    inputModalities: m.modalities?.input ? [...m.modalities.input] : null,
+    outputModalities: m.modalities?.output ? [...m.modalities.output] : null,
+    // Il selettore storico legge qui livelli/configurazione, non un booleano di supporto.
+    reasoning: null,
+    dataRilascio: m.release_date ?? null, ultimoAggiornamentoFonte: m.last_updated ?? null,
+    catalogo: structuredClone(metadati),
+  };
+}
+
+/**
+ * Cache unica per URL, sotto la cartella dati ricevuta da loadConfig().
+ * fetchFn, clock e fsImpl sono iniettabili: nessuna rete necessaria nei test.
+ * ottieni(id, opzioni) espone soltanto i modelli del record richiesto, non i campi di trasporto upstream.
+ */
+export function createModelsDevCatalog({
+  cartellaStore, url = URL_PREDEFINITO, fetchFn = globalThis.fetch, clock = () => new Date(),
+  ttlMs = TTL_MS, retryMs = RINVIO_MS, timeoutMs = 15_000, fsImpl = {},
+} = {}) {
+  let indirizzo;
+  try { indirizzo = new URL(url); } catch { throw new ModelsDevCatalogError('Indirizzo del catalogo non valido.', 'CONFIG_INVALID'); }
+  if (!['http:', 'https:'].includes(indirizzo.protocol) || indirizzo.username || indirizzo.password || indirizzo.hash || !cartellaStore) {
+    throw new ModelsDevCatalogError('Configurazione del catalogo non valida.', 'CONFIG_INVALID');
+  }
+  url = indirizzo.href;
+  const fs = { mkdir, readFile, rename, rm, writeFile, ...fsImpl };
+  const cartellaCache = join(cartellaStore, 'cache');
+  const percorsoCache = join(cartellaCache, `models-dev-${impronta(url).slice(0, 16)}.json`);
+  let copia = null, discoLetto = false, inVolo = null, riprovaAlle = 0, fallbackRete = false;
+  const avvisi = new Map();
+  const avvisa = (codice, messaggio) => avvisi.set(codice, { codice, messaggio });
+
+  function erroreSenzaCopia() {
+    return avvisi.has('CATALOG_CACHE_CORRUPT')
+      ? new ModelsDevCatalogError('Copia del catalogo danneggiata: rifiutata. La fonte non è disponibile per recuperarla.', 'CATALOG_CACHE_CORRUPT')
+      : new ModelsDevCatalogError('Catalogo non disponibile: impossibile leggere la fonte e nessuna copia salvata utilizzabile.');
+  }
+
+  async function leggiDisco() {
+    if (discoLetto) return;
+    discoLetto = true;
+    let testo;
+    try { testo = await fs.readFile(percorsoCache, 'utf8'); }
+    catch (e) {
+      if (e.code !== 'ENOENT') avvisa('CATALOG_CACHE_READ_FAILED', 'La copia salvata non è leggibile.');
+      return;
+    }
+    try {
+      const busta = JSON.parse(testo);
+      if (!Busta.safeParse(busta).success || busta.url !== url || busta.verificatoAlle < busta.acquisitoAlle || impronta(JSON.stringify(busta.dati)) !== busta.sha256) throw new Error('Copia non valida');
+      copia = busta;
+    } catch {
+      // Nessun ETag viene caricato separatamente: non può sopravvivere ai dati che garantisce.
+      avvisa('CATALOG_CACHE_CORRUPT', 'Copia del catalogo danneggiata: rifiutata.');
+    }
+  }
+
+  async function salvaDisco() {
+    const temporaneo = `${percorsoCache}.${randomUUID()}.tmp`;
+    try {
+      await fs.mkdir(cartellaCache, { recursive: true });
+      await fs.writeFile(temporaneo, JSON.stringify(copia), { encoding: 'utf8', flag: 'wx' });
+      await fs.rename(temporaneo, percorsoCache);
+      avvisi.delete('CATALOG_CACHE_WRITE_FAILED');
+    } catch {
+      avvisa('CATALOG_CACHE_WRITE_FAILED', 'Catalogo letto, ma non è stato possibile salvare la copia.');
+    } finally {
+      await fs.rm(temporaneo, { force: true }).catch(() => {});
+    }
+  }
+
+  async function aggiorna(forza) {
+    await leggiDisco();
+    const ora = clock().getTime();
+    const etaVerifica = copia ? eta(ora, copia.verificatoAlle) : null;
+    if (!forza && !copia && ora < riprovaAlle) throw erroreSenzaCopia();
+    if (!forza && copia && ((etaVerifica !== null && etaVerifica < ttlMs) || ora < riprovaAlle)) return true;
+    try {
+      const headers = { Accept: 'application/json' };
+      if (copia?.etag) headers['If-None-Match'] = copia.etag;
+      const risposta = await fetchFn(url, { method: 'GET', headers, credentials: 'omit', signal: AbortSignal.timeout(timeoutMs) });
+      const ricevutoEtag = risposta.headers?.get('etag') ?? null;
+      const nuovoEtag = Etag.safeParse(ricevutoEtag).success ? ricevutoEtag : null;
+      const invariato = risposta.status === 304;
+      if (invariato) {
+        if (!copia) throw new ModelsDevCatalogError('Il catalogo non ha restituito dati utilizzabili.');
+        copia = { ...copia, verificatoAlle: clock().getTime(), etag: nuovoEtag ?? copia.etag };
+      } else {
+        if (!risposta.ok) {
+          await risposta.body?.cancel?.();
+          throw new ModelsDevCatalogError('La fonte del catalogo non è disponibile.');
+        }
+        const dati = await risposta.json();
+        if (!Catalogo.safeParse(dati).success) throw new ModelsDevCatalogError('La fonte ha restituito un catalogo non valido.');
+        const acquisitoAlle = clock().getTime();
+        copia = { versione: 1, schemaRevision: MODELS_DEV_SCHEMA_REVISION, url,
+          etag: nuovoEtag, acquisitoAlle, verificatoAlle: acquisitoAlle,
+          sha256: impronta(JSON.stringify(dati)), dati, licenza: LICENZA_DATI };
+      }
+      fallbackRete = false;
+      riprovaAlle = 0;
+      avvisi.delete('CATALOG_REFRESH_FAILED');
+      await salvaDisco();
+      return invariato;
+    } catch {
+      riprovaAlle = clock().getTime() + retryMs;
+      if (!copia) {
+        throw erroreSenzaCopia();
+      }
+      fallbackRete = true;
+      avvisa('CATALOG_REFRESH_FAILED', 'Aggiornamento non disponibile: viene usata la copia salvata.');
+      return true;
+    }
+  }
+
+  async function ottieni(id, { forzaAggiornamento = false } = {}) {
+    const record = fornitore(id);
+    const modelsDevId = record?.modelsDevId ?? null;
+    const indisponibile = { provider: id, modelsDevId, disponibile: false, modelli: [],
+      motivo: `Catalogo${record ? ` ${record.etichetta}` : ''} non disponibile.`, fonte: 'models.dev',
+      aggiornatoAlle: null, verificatoAlle: null, etaCacheMs: null, daCache: false, fallbackRete: false, avvisi: [] };
+    if (!modelsDevId) return indisponibile;
+    // Una promessa condivisa comprende lettura disco, download e scrittura atomica.
+    if (!inVolo) inVolo = aggiorna(forzaAggiornamento).finally(() => { inVolo = null; });
+    const daCache = await inVolo;
+    const metadati = { fonte: 'models.dev', aggiornatoAlle: new Date(copia.acquisitoAlle).toISOString(),
+      verificatoAlle: new Date(copia.verificatoAlle).toISOString(), etaCacheMs: eta(clock().getTime(), copia.acquisitoAlle),
+      daCache, fallbackRete, avvisi: structuredClone([...avvisi.values()]) };
+    if (!Object.hasOwn(copia.dati, modelsDevId)) return { ...indisponibile, ...metadati };
+    const modelli = Object.values(copia.dati[modelsDevId].models)
+      .map(m => normalizza(m, record, metadati))
+      .sort((a, b) => a.nome.localeCompare(b.nome, 'it') || a.id.localeCompare(b.id));
+    return { provider: id, modelsDevId, disponibile: true, modelli, motivo: null, ...metadati };
+  }
+
+  return Object.freeze({ ottieni, percorsoCache });
+}
+
+/** Porta per GET /api/v1/providers/:id/models. Nessuna chiave transita nel catalogo. */
+export function createProviderModelCatalog({ catalogo, chiaveConfigurata } = {}) {
+  async function ottieni(id, opzioni) {
+    const record = fornitore(id);
+    if (!record?.destinazioneChat || record.catalogo.fonte === 'runtime-locale' || id === 'openrouter') {
+      throw new ModelsDevCatalogError('Catalogo non disponibile per questa destinazione.', 'REPORT_UNAVAILABLE');
+    }
+    if (record.chiaveObbligatoria && (typeof chiaveConfigurata !== 'function' || await chiaveConfigurata(id) !== true)) {
+      throw new ModelsDevCatalogError(`Collega la chiave ${record.etichetta} dal pannello Provider.`, 'PROVIDER_KEY_REQUIRED');
+    }
+    let dati;
+    try {
+      dati = await catalogo.ottieni(id, opzioni);
+    } catch (errore) {
+      // Il catalogo stesso preferisce già la copia valida, anche vecchia. Qui non ne ha una.
+      const riserva = catalogoDiRiservaPer(id);
+      if (!riserva) throw new ModelsDevCatalogError('Catalogo non disponibile.', 'CATALOG_UPSTREAM_ERROR');
+      if (errore instanceof ModelsDevCatalogError && errore.code === 'CATALOG_CACHE_CORRUPT') {
+        const avviso = { codice: 'CATALOG_CACHE_CORRUPT', messaggio: 'Copia danneggiata rifiutata: viene usato l’elenco di riserva.' };
+        riserva.avvisi.push(avviso);
+        for (const m of riserva.modelli) m.catalogo.avvisi.push({ ...avviso });
+      }
+      return { ...riserva, credenzialeVerificata: false };
+    }
+    // Un catalogo raggiunto che non pubblica quel fornitore non è un guasto di rete.
+    if (!dati.disponibile) throw new ModelsDevCatalogError(dati.motivo, 'CATALOG_UPSTREAM_ERROR');
+    return { ...dati, credenzialeVerificata: false };
+  }
+  return Object.freeze({ ottieni });
+}

package/vendor/harness-ui/src/model-catalog.mjs

@@ -0,0 +1,129 @@
+/**
+ * model-catalog.mjs — il catalogo VERO di OpenRouter, non 7 scorciatoie
+ * scritte a mano. Owner, 27/8: "introdurre nella modale un picker per il
+ * modello, dropdown stilizzato (l'abbiamo già fatto nel mobile)" — il
+ * componente mobile (TalosMobileComposerModelPicker.vue) raggruppa i
+ * modelli per provider e dice onestamente quando la scoperta È FALLITA
+ * (non solo "zero risultati"). Stesso principio qui.
+ *
+ * ⛔ `GET https://openrouter.ai/api/v1/models` è pubblico — verificato
+ * dal vivo il 27/8: 417 modelli, nessuna chiave richiesta per leggerlo
+ * (l'autenticazione serve solo per CHIAMARE un modello, non per elencarli).
+ * Formato risposta confermato: `{data: [{id, name, context_length,
+ * pricing:{prompt, completion}, ...}]}` — `id` è già nel formato
+ * `vendor/nome-modello` che talosHarness.mjs instrada.
+ */
+
+import { catalogoDiRiservaPer } from './provider-registry.mjs';
+
+const OPENROUTER_MODELS_URL = 'https://openrouter.ai/api/v1/models';
+const TTL_PREDEFINITO_MS = 10 * 60 * 1000; // 10 minuti — non richiamare OpenRouter a ogni apertura del foglio.
+
+export class ModelCatalogError extends Error {
+  constructor(message, code = 'CATALOG_UNAVAILABLE') {
+    super(message);
+    this.name = 'ModelCatalogError';
+    this.code = code;
+  }
+}
+
+function normalizza(modelloGrezzo) {
+  const id = typeof modelloGrezzo?.id === 'string' ? modelloGrezzo.id : '';
+  // ⛔ 27/8, trovato dalla pipeline QA visiva: 12 dei 417 id reali hanno il
+  // prefisso `~` (alias "sempre l'ultima versione", es.
+  // `~deepseek/deepseek-v4-flash-latest`). Il PROVIDER va calcolato dopo
+  // averlo tolto, altrimenti "deepseek" e "~deepseek" diventano due gruppi
+  // diversi nel picker per lo stesso vendor. `id` resta INTATTO (con la
+  // tilde) — è quello che viaggia nella chiamata vera.
+  const alias = id.startsWith('~');
+  const idSenzaAlias = alias ? id.slice(1) : id;
+  const provider = idSenzaAlias.includes('/') ? idSenzaAlias.split('/')[0] : 'altro';
+  const listaStringhe = (value) => Array.isArray(value)
+    ? value.filter((item) => typeof item === 'string' && item.length <= 128).slice(0, 32)
+    : [];
+  const architecture = modelloGrezzo?.architecture && typeof modelloGrezzo.architecture === 'object'
+    ? modelloGrezzo.architecture : {};
+  const reasoningGrezzo = modelloGrezzo?.reasoning && typeof modelloGrezzo.reasoning === 'object'
+    ? modelloGrezzo.reasoning : null;
+  const reasoning = reasoningGrezzo ? {
+    supportedEfforts: listaStringhe(reasoningGrezzo.supported_efforts),
+    defaultEffort: typeof reasoningGrezzo.default_effort === 'string' && reasoningGrezzo.default_effort.length <= 128
+      ? reasoningGrezzo.default_effort : null,
+    defaultEnabled: typeof reasoningGrezzo.default_enabled === 'boolean' ? reasoningGrezzo.default_enabled : null,
+    mandatory: reasoningGrezzo.mandatory === true,
+  } : null;
+  return {
+    id,
+    provider,
+    alias,
+    nome: typeof modelloGrezzo?.name === 'string' && modelloGrezzo.name ? modelloGrezzo.name : id,
+    contextLength: Number.isFinite(modelloGrezzo?.context_length) ? modelloGrezzo.context_length : null,
+    prezzoPrompt: modelloGrezzo?.pricing?.prompt ?? null,
+    prezzoCompletion: modelloGrezzo?.pricing?.completion ?? null,
+    inputModalities: listaStringhe(architecture.input_modalities),
+    outputModalities: listaStringhe(architecture.output_modalities),
+    supportedParameters: listaStringhe(modelloGrezzo?.supported_parameters),
+    reasoning,
+    description: typeof modelloGrezzo?.description === 'string' ? modelloGrezzo.description.slice(0, 2000) : '',
+    createdAt: Number.isFinite(modelloGrezzo?.created) ? modelloGrezzo.created : null,
+  };
+}
+
+/**
+ * @param {{fetchFn?: typeof fetch, clock?: () => Date, ttlMs?: number, url?: string}} [opts]
+ */
+export function createModelCatalog({
+  fetchFn = fetch, clock = () => new Date(), ttlMs = TTL_PREDEFINITO_MS, url = OPENROUTER_MODELS_URL,
+} = {}) {
+  let cache = null; // { creatoAlle: number, modelli: Array }
+
+  /**
+   * @param {{forzaAggiornamento?: boolean}} [opts]
+   * @returns {Promise<{modelli: Array, daCache: boolean, aggiornatoAlle: string|null}>}
+   */
+  async function ottieni({ forzaAggiornamento = false } = {}) {
+    const ora = clock().getTime();
+    if (!forzaAggiornamento && cache && (ora - cache.creatoAlle) < ttlMs) {
+      return { modelli: cache.modelli, daCache: true, aggiornatoAlle: new Date(cache.creatoAlle).toISOString() };
+    }
+
+    try {
+      let risposta;
+      try {
+        risposta = await fetchFn(url, { headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(15_000) });
+      } catch {
+        // ⛔ un errore di rete non è "zero modelli": la UI deve poterli distinguere (stesso principio di discoveryProblems nel mobile).
+        throw new ModelCatalogError('Catalogo OpenRouter non raggiungibile.', 'CATALOG_UNREACHABLE');
+      }
+      if (!risposta.ok) {
+        throw new ModelCatalogError(`Catalogo OpenRouter ha risposto ${risposta.status}`, 'CATALOG_UPSTREAM_ERROR');
+      }
+      let corpo;
+      try {
+        corpo = await risposta.json();
+      } catch {
+        throw new ModelCatalogError('Catalogo OpenRouter: risposta non valida', 'CATALOG_UPSTREAM_ERROR');
+      }
+      if (!Array.isArray(corpo?.data)) {
+        throw new ModelCatalogError('Catalogo OpenRouter: formato inatteso', 'CATALOG_UPSTREAM_ERROR');
+      }
+
+      const modelli = corpo.data
+        .map(normalizza)
+        .filter((modello) => modello.id !== '')
+        .sort((a, b) => a.provider.localeCompare(b.provider) || a.nome.localeCompare(b.nome));
+
+      cache = { creatoAlle: ora, modelli };
+      return { modelli, daCache: false, aggiornatoAlle: new Date(ora).toISOString() };
+    } catch {
+      // P-F: la copia reale ha precedenza; la riserva non entra mai nella cache del catalogo.
+      if (cache) return { modelli: structuredClone(cache.modelli), daCache: true, fonte: 'openrouter',
+        aggiornatoAlle: new Date(cache.creatoAlle).toISOString(),
+        etaCacheMs: Math.max(0, clock().getTime() - cache.creatoAlle), fallbackRete: true,
+        motivo: 'Catalogo non raggiungibile: viene usata la copia salvata.' };
+      return catalogoDiRiservaPer('openrouter');
+    }
+  }
+
+  return Object.freeze({ ottieni });
+}

package/vendor/harness-ui/src/model-destination.mjs

@@ -0,0 +1,189 @@
+/**
+ * Dove vive un modello, e come gli si parla.
+ *
+ * ## Perché esiste
+ *
+ * Owner, 03/9: «se non riesco ad aggiungere più provider oltre a OpenRouter e
+ * soprattutto usare i modelli locali, l'applicazione è spacciata». E prima:
+ * «non è un limite quello che mi hai detto tu, è un finto limite».
+ *
+ * Aveva ragione, e la misura lo dimostra: nel kernel c'era UNA sola chiamata
+ * cablata (riga 406 della copia caricata dal desktop, 392 di quella mobile) —
+ * una stringa, non un'architettura. E sulla macchina dell'owner erano già
+ * salvate CINQUE credenziali funzionanti, misurate il 03/9 contro i servizi
+ * veri: OpenRouter 424 modelli, OpenAI 124, Gemini 50, Anthropic 11,
+ * DeepSeek 3. Cinque provider pagati e fermi, perché nessuno li chiamava.
+ *
+ * ## Il fatto che rende la cura piccola
+ *
+ * Quasi tutti parlano GIÀ lo stesso protocollo: `POST /v1/chat/completions`
+ * con `Authorization: Bearer`, stesso corpo. Vale per OpenAI, DeepSeek,
+ * OpenRouter, Ollama e — verificato in `local-runtime-llama-server.mjs`, che
+ * chiama esattamente quell'endpoint — anche per llama.cpp in locale.
+ * ⇒ Per i modelli LOCALI e altri quattro provider basta cambiare indirizzo e
+ * intestazioni. Nessuna traduzione del corpo, nessun adattatore nuovo.
+ *
+ * Anthropic e Gemini usano native-provider-adapter con SDK fissati nel lock:
+ * /v1/messages e :generateContent, immagini e firme di ragionamento native.
+ *
+ * ## La convenzione sul nome, e perché i DUE PUNTI
+ *
+ * Gli id OpenRouter sono già `autore/modello` (`deepseek/deepseek-v4-flash`),
+ * quindi lo slash è occupato e non può separare la fonte. Si usa il carattere
+ * `:` come prefisso — `local:qwen3-0.6b-…`, `ollama:llama3.2` — e
+ * **nessun prefisso significa OpenRouter**, così tutto ciò che esiste oggi
+ * continua a funzionare identico, senza migrare una sola sessione salvata.
+ */
+
+import { ID_DESTINAZIONE_CHAT, ID_NATIVI_SDK, REGISTRO_FORNITORI, idPerWire } from './provider-registry.mjs';
+// P-K
+import { destinazioneCloud } from './provider-auth-cloud.mjs';
+// P-K — fine
+
+export class ModelDestinationError extends Error {
+  constructor(message, code = 'MODEL_DESTINATION_INVALID') {
+    super(message);
+    this.name = 'ModelDestinationError';
+    this.code = code;
+  }
+}
+
+/**
+ * Le fonti riconosciute nel prefisso. ⛔ Tutto il resto è un id OpenRouter.
+ *
+ * ⛔ 12/09 — P-A: era un array scritto a mano, e `config.mjs:186` ne teneva una **copia dentro una
+ *   stringa di regex**. Adesso tutte e due si derivano dal registro: aggiungere `lmstudio` è stata
+ *   una riga di dato, non sette modifiche sparse (P-C).
+ */
+export const FONTI_MODELLO = ID_DESTINAZIONE_CHAT;
+
+/**
+ * Spacca `fonte:modello`. ⛔ Solo sul PRIMO due punti, e solo se ciò che sta
+ * davanti è una fonte conosciuta: un id che contenesse un `:` per altri motivi
+ * non deve essere dirottato su un provider inesistente.
+ */
+export function separaFonteModello(modello) {
+  if (typeof modello !== 'string' || modello.trim() === '') {
+    throw new ModelDestinationError('model id is missing', 'MODEL_DESTINATION_INVALID');
+  }
+  const taglio = modello.indexOf(':');
+  if (taglio > 0) {
+    const fonte = modello.slice(0, taglio);
+    if (FONTI_MODELLO.includes(fonte)) return { fonte, modelloRemoto: modello.slice(taglio + 1) };
+  }
+  return { fonte: 'openrouter', modelloRemoto: modello };
+}
+
+/** Lista di sessione: solo identificatori, mai indirizzi, chiavi o capacità dichiarate dal client. */
+export function validaFallbackProviders(lista = [], { usaAttrezzi = false } = {}) {
+  const invalida = () => { throw new ModelDestinationError('Controlla i fornitori e i modelli scelti per continuare la sessione.', 'PROVIDER_FALLBACK_INVALID'); };
+  if (!Array.isArray(lista) || lista.length > 8) invalida();
+  const viste = new Set();
+  return lista.map(voce => {
+    if (!voce || typeof voce !== 'object' || Array.isArray(voce) || Object.keys(voce).some(k => !['provider', 'model'].includes(k))) invalida();
+    const { provider, model } = voce;
+    const record = Object.hasOwn(REGISTRO_FORNITORI, provider) ? REGISTRO_FORNITORI[provider] : null;
+    if (!record?.destinazioneChat || !record.credenziale || typeof model !== 'string' || model.length > 200 || !/^[a-zA-Z0-9][a-zA-Z0-9._/:@-]*$/u.test(model) || model.includes('://') || FONTI_MODELLO.some(p => model.startsWith(`${p}:`))) invalida();
+    const id = `${provider}:${model}`;
+    if (viste.has(id)) invalida();
+    viste.add(id);
+    if (usaAttrezzi && record.modelliDiRiserva?.find(m => m.id === model)?.toolCalling !== true) {
+      throw new ModelDestinationError('Il modello di riserva non dichiara il supporto agli attrezzi della sessione.', 'PROVIDER_FALLBACK_TOOLS_UNSUPPORTED');
+    }
+    return Object.freeze({ provider, model });
+  });
+}
+
+/**
+ * Chi parla `POST {base}{percorso}` con Bearer: il corpo non si tocca.
+ * ⛔ `wire: 'locale'` sta qui dentro perché il supervisore espone lo stesso protocollo — ma esce
+ *   prima, sulla sua strada: la sua chiave non deve passare da questo file.
+ */
+const COMPATIBILI_OPENAI = Object.freeze([...idPerWire('openai-chat'), ...idPerWire('locale')]);
+
+/**
+ * Chi NON lo parla, e cosa gli servirebbe. ⛔ Il messaggio dice la cosa vera —
+ * la credenziale può essere ottima, manca la traduzione dalla nostra parte —
+ * perché un errore che sembra colpa della chiave manda a rigenerarne una buona.
+ *
+ * ⛔ Sono i tre wire serviti dagli SDK fissati nel lock (`native-provider-adapter.mjs`): il
+ *   registro li nomina uno per uno, così «nativo» smette di essere una lista da ricordare.
+ */
+const NATIVI = ID_NATIVI_SDK;
+
+/**
+ * @param {string} modello id, con o senza prefisso di fonte
+ * @param {object} deps
+ * @param {(fonte: string) => string|null} deps.leggiChiave dal portachiavi
+ * @param {(fonte: string) => {endpoint?: string|null}} deps.leggiRuntime indirizzo configurato
+ * @param {() => boolean} [deps.localePronto] il motore locale è acceso adesso?
+ * @returns {{fonte: string, url: string, headers: Record<string,string>, modelloRemoto: string}}
+ */
+export function risolviDestinazioneModello(modello, { leggiChiave, leggiRuntime, localePronto = () => false } = {}) {
+  if (typeof leggiChiave !== 'function' || typeof leggiRuntime !== 'function') {
+    throw new ModelDestinationError('destination dependencies are invalid', 'MODEL_DESTINATION_MISCONFIGURED');
+  }
+  const { fonte, modelloRemoto } = separaFonteModello(modello);
+
+  // P-L · nessuna chiave, nessun endpoint scelto dal browser e nessun ripiego remoto.
+  if (REGISTRO_FORNITORI[fonte]?.wire === 'acp') {
+    let runtime = null;
+    try { runtime = leggiRuntime(fonte); }
+    catch (e) { if (e?.code !== 'PROVIDER_INVALID') throw e; }
+    return { fonte, modelloRemoto, esterno: true, runtime };
+  }
+  // P-L · fine destinazione agente esterno.
+
+  if (!COMPATIBILI_OPENAI.includes(fonte) && !NATIVI.includes(fonte)) throw new ModelDestinationError(`Fonte del modello non riconosciuta: ${fonte}`, 'MODEL_DESTINATION_INVALID');
+
+  if (fonte === 'local') {
+    /*
+     * ⛔⛔ IL MOTORE LOCALE VUOLE UNA CHIAVE — misurato, non dedotto.
+     *
+     * La prima stesura costruiva l'URL a mano e non mandava credenziali,
+     * ragionando che «127.0.0.1 non ha autenticazione». Provato dal vivo
+     * contro il runtime acceso: **HTTP 401, "Invalid API Key" in 4 ms**.
+     * `llama-server-supervisor.mjs` genera `randomBytes(32)` a ogni avvio e
+     * lo passa come `--api-key`; la chiave vive solo lì dentro, e `status()`
+     * NON la espone — giustamente, perché quella risposta finisce nel
+     * browser.
+     *
+     * ⇒ Non si copia il segreto qui: si passa dal `request()` del
+     * supervisore, che è il punto in cui la chiave già sta. Il risolutore
+     * dice SOLO che la destinazione è locale e che il motore è pronto; a
+     * spedire ci pensa chi possiede la credenziale.
+     */
+    if (typeof localePronto !== 'function' || !localePronto()) {
+      throw new ModelDestinationError('Il motore locale non è acceso: caricalo dal Laboratorio modelli prima di usarlo in chat.', 'LOCAL_RUNTIME_NOT_READY');
+    }
+    return { fonte, modelloRemoto, locale: true, percorso: REGISTRO_FORNITORI[fonte].endpoint.chat };
+  }
+
+  const runtime = leggiRuntime(fonte) || {};
+  const record = REGISTRO_FORNITORI[fonte];
+  const base = typeof runtime.endpoint === 'string' && runtime.endpoint.trim() !== '' ? runtime.endpoint.replace(/\/+$/u, '') : null;
+  if (!base) throw new ModelDestinationError(`Manca l'indirizzo di ${record.etichetta}.`, 'PROVIDER_RUNTIME_INVALID');
+
+  const chiave = leggiChiave(fonte);
+  /*
+   * ⛔ Ollama e LM Studio girano in casa e non hanno account: pretendere una
+   * chiave li escluderebbe per una regola che non li riguarda. Gli altri sì, e
+   * senza si dice CHE COSA manca invece di partire e prendersi un 401.
+   * ⛔ 12/09 — la domanda non è più «è ollama?»: è `chiaveObbligatoria` sul record. Erano due
+   *   verità diverse (`requiresKey` nel portachiavi diceva già `false` per Ollama, e qui c'era un
+   *   confronto per nome), e ora è una sola.
+   */
+  if (record.chiaveObbligatoria === true && (typeof chiave !== 'string' || chiave.trim() === '')) {
+    throw new ModelDestinationError(`Manca la chiave per ${record.etichetta}: inseriscila in Laboratorio modelli → Provider.`, 'PROVIDER_KEY_MISSING');
+  }
+
+  // P-K — lo stesso contratto di autenticazione per chat e sonda.
+  if (record.cloud) return destinazioneCloud(fonte, runtime, chiave, modelloRemoto);
+  // P-K — fine
+  if (NATIVI.includes(fonte)) return { fonte, modelloRemoto, native: true, baseURL: base, apiKey: chiave };
+  const headers = { 'Content-Type': 'application/json' };
+  if (chiave) headers.Authorization = `Bearer ${chiave}`;
+  /* ⛔ Ollama e LM Studio espongono il protocollo OpenAI sotto /v1, il loro indirizzo base no:
+     è il record a dire dove bussare (`endpoint.chat`), non un `if` sul nome. */
+  return { fonte, modelloRemoto, url: `${base}${record.endpoint.chat}`, headers };
+}