@byte-42/fantastico-sdk 0.0.0-stage → 0.21.0

package/dist/types.d.ts

@@ -0,0 +1,734 @@
+/** Messaggio nella conversazione (OpenAI-compat). */
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/** Request per chat.completions.create(). */
+export interface ChatCompletionCreateParams {
+    /** Modello (opzionale: usa il default del progetto se omesso). */
+    model?: string;
+    messages: ChatMessage[];
+    /** Streaming (futuro). */
+    stream?: boolean;
+    temperature?: number;
+    max_tokens?: number;
+    /**
+     * Controllo sui thinking token, valido per **ogni turno** dell'orchestrazione. Omesso, non
+     * viene mandato nulla. Vedi {@link ReasoningConfig} — in particolare il fatto che il
+     * ragionamento scala dal `max_tokens`, che qui l'SDK calcola da sé sul tetto della chiave.
+     */
+    reasoning?: ReasoningConfig;
+    /**
+     * Identità del tenant finale (campo `user` dell'API OpenAI). Se presente, il consumo
+     * viene attribuito e limitato per quel tenant tramite la prenotazione del budget
+     * (`/api/runtime/budget`). Se assente, vale solo il tetto di progetto della runtime key.
+     */
+    user?: string;
+    /**
+     * Contesto fidato per QUESTA chiamata, iniettato in ogni tool locale invocato durante il
+     * turno (secondo argomento di `execute`) — mai visto dal modello, mai influenzato dai suoi
+     * argomenti. Sovrascrive (solo per questa chiamata) il `context` eventuale dell'istanza.
+     */
+    context?: unknown;
+    /**
+     * **Quali tool del marketplace offrire al modello in questa chiamata**, per id del tool (lo
+     * stesso id di `ai.tools.enabled()` e di `ai.runtimeKeys.ensure().tools`). Dalla 0.18.0.
+     *
+     * Omesso, il caso ordinario: tutti quelli che il conio ha concesso, come prima. `[]`: nessuno —
+     * la chiamata resta orchestrata (tool locali compresi) ma senza tool del marketplace.
+     *
+     * Restringe e non allarga: un id che il conio non ha concesso non compare, e non è un errore —
+     * vale come un tool irraggiungibile, che esce dal catalogo del giro (vedi `auth.ts`). Serve a
+     * chi confronta configurazioni diverse (Fantastico Studio: un test è modello + tool) e a chi
+     * vuole dare a un passaggio del proprio agente solo gli strumenti che gli servono.
+     */
+    marketplaceTools?: string[];
+}
+/** Un'azione delegata al client, raccolta durante l'orchestrazione (modalità fire-and-forget:
+ *  il loop prosegue subito, l'esecuzione reale spetta al chiamante). */
+export interface ClientAction {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** Una tool_call sospesa: il loop si è fermato prima di eseguirla. */
+export interface PendingToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    /**
+     * Perché è sospesa. Assente = il tool non ha bisogno di una decisione (era solo nello
+     * stesso turno di uno che la richiedeva): `resume()` lo esegue in automatico.
+     */
+    reason?: "confirmation" | "client_action";
+    /**
+     * Frase umana da mostrare all'operatore per decidere (da `LocalToolDefinition.confirmationSummary`).
+     * Assente se il tool non ne definisce una: il chiamante ripiega su nome+argomenti grezzi.
+     */
+    summary?: string;
+}
+/** Decisione del chiamante su una singola tool_call sospesa, passata a `resume()`. */
+export interface ResumeDecision {
+    id: string;
+    /** Per reason "confirmation": true = esegui ora, false = nega (il modello riceve un errore). */
+    approved?: boolean;
+    /** Per reason "client_action": l'esito che il client ha ottenuto compiendo l'azione. */
+    result?: unknown;
+}
+/** Esito quando l'orchestrazione si ferma in attesa di conferma umana o di un'azione client. */
+export interface PendingCompletion {
+    status: "pending";
+    pending: PendingToolCall[];
+    /** Stato opaco della conversazione: da ripassare identico a `resume()`. La sua forma non è
+     *  un contratto stabile — non va ispezionato né modificato dal chiamante. */
+    state: unknown;
+    /**
+     * Testo che il modello ha eventualmente prodotto nello stesso turno delle tool_call sospese
+     * (es. "Procedo con i due trasferimenti:"). Assente se il modello non ha scritto nulla.
+     * Il chiamante lo mostra come normale messaggio assistente PRIMA del gate di conferma —
+     * non è mai eseguito né interpretato, solo testo da visualizzare.
+     */
+    message?: string;
+}
+/** Usage aggregato (tutti i turni interni sommati). */
+/**
+ * Lo sforzo di ragionamento, nei valori che OpenRouter documenta.
+ *
+ * **L'unione è aperta di proposito** (`| (string & {})`: i valori noti restano suggeriti
+ * dall'autocompletamento, uno nuovo non è un errore di compilazione). Due ragioni, e la seconda
+ * conta più della prima: le due pagine di OpenRouter non concordano — `use-cases/reasoning-tokens`
+ * elenca anche `"max"`, `api-reference/parameters` no — e soprattutto un elenco chiuso qui
+ * riprodurrebbe in piccolo il difetto che questo campo esiste per chiudere: un valore valido
+ * scartato dall'SDK perché l'SDK non lo conosceva ancora.
+ */
+export type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | (string & {});
+/**
+ * Il campo `reasoning` di OpenRouter — il controllo sui "thinking token".
+ *
+ * **Perché è importante poterlo scrivere.** I token di ragionamento sono fatturati come token di
+ * output **e** scalano dal `max_tokens` della richiesta. Un modello capace di ragionare può quindi
+ * consumare l'intero budget di output pensando e restituire un contenuto **vuoto o troncato**, con
+ * un HTTP 200 e un usage regolarmente misurato. Per chi fa estrazione strutturata il guasto è
+ * silenzioso e non rumoroso: un contenuto vuoto si legge come un JSON `[]` valido, cioè "non ho
+ * trovato niente" — che è una risposta plausibile e sbagliata.
+ *
+ * **L'SDK non decide per il chiamante.** Nessun default: omesso, il campo non parte affatto e il
+ * comportamento resta quello che il modello e OpenRouter hanno di loro. Spegnere il ragionamento
+ * d'ufficio cambierebbe la risposta di ogni chiamante esistente senza che nessuno l'abbia chiesto.
+ *
+ * Vincoli dichiarati da OpenRouter: `effort` e `max_tokens` non si passano insieme, e per i modelli
+ * Anthropic il `max_tokens` della richiesta deve essere strettamente maggiore del budget di
+ * ragionamento — altrimenti non resta spazio per la risposta.
+ */
+export interface ReasoningConfig {
+    /** Accende il ragionamento; senza `effort`, OpenRouter lo attiva a sforzo "medium". */
+    enabled?: boolean;
+    /** Quanto ragionare. Mutuamente esclusivo con `max_tokens`. */
+    effort?: ReasoningEffort;
+    /** Budget esplicito di token di ragionamento (stile Anthropic/Gemini). Esclude `effort`. */
+    max_tokens?: number;
+    /** Ragiona ma non restituire il ragionamento. Supportato da tutti i modelli. */
+    exclude?: boolean;
+    /** Quali turni portano il ragionamento (GPT-5.6+). Documentato solo sulla pagina use-cases. */
+    context?: "auto" | "all_turns" | "current_turn" | (string & {});
+    /** Modalità di ragionamento (GPT-5.6+). Documentato solo sulla pagina use-cases. */
+    mode?: "standard" | "pro" | (string & {});
+}
+export interface CompletionUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    /** Turni LLM interni (inclusi quelli per MCP). */
+    internal_turns: number;
+    cache_creation_tokens: number;
+    cache_read_tokens: number;
+    /**
+     * Token spesi a ragionare, da `usage.completion_tokens_details.reasoning_tokens`.
+     *
+     * **Sono già dentro `completion_tokens`**, non si sommano: la parte visibile della risposta è
+     * `completion_tokens - reasoning_tokens`. È l'unico modo che il chiamante ha di vedere quanto è
+     * costato il pensiero — e, quando la risposta torna vuota o mozzata, di distinguere "il modello
+     * non aveva niente da dire" da "ha speso il budget a pensare". `0` quando il provider non riporta
+     * il dettaglio, che è anche il caso di ogni modello che non ragiona.
+     */
+    reasoning_tokens: number;
+    /** Invocazioni MCP avvenute internamente. */
+    mcp_calls: number;
+    /** Costo reale dell'inferenza in USD, riportato da OpenRouter (non stimato). */
+    cost_usd: number;
+}
+export interface ChatCompletionChoice {
+    index: number;
+    message: {
+        role: "assistant";
+        content: string;
+    };
+    finish_reason: "stop" | "length";
+}
+/** Risposta di chat.completions.create() a orchestrazione conclusa. */
+export interface ChatCompletion {
+    status: "done";
+    id: string;
+    object: "chat.completion";
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage: CompletionUsage;
+    /** Azioni client raccolte durante il turno (fire-and-forget): il chiamante le esegue
+     *  lato suo (es. con FantasticoActions). Vuoto se nessuna è stata richiesta. */
+    clientActions: ClientAction[];
+}
+/** Esito di create()/resume(): concluso, o fermo in attesa di conferma/azione client. */
+export type ChatCompletionResult = ChatCompletion | PendingCompletion;
+/** Opzioni di configurazione del client FANTASTICO. */
+export interface FantasticoOptions {
+    /**
+     * La credenziale FANTASTICO (obbligatoria), e **l'unica cosa che decide su quale superficie
+     * parla questo client**:
+     *
+     * - una **project key** `sk-fant-…` vale tutti i conti del progetto e opera su `/api/runtime/*`,
+     *   dove il conto si nomina (`user` in una create, `userKey` sulle chiavi);
+     * - una **chiave di conto** `ck-fant-…` ne vale uno solo e opera su `/api/edge/*`, dove il conto
+     *   **non si nomina affatto**: è quello della credenziale, e non esiste un campo con cui
+     *   indicarne un altro.
+     *
+     * Non c'è un'opzione con cui dichiarare quale delle due: il prefisso lo dice già, e dirlo due
+     * volte vuol dire poterlo dire diversamente. Vedi `surface.ts`.
+     */
+    apiKey: string;
+    /** URL del control plane, comprensivo di `/api` (default: https://fantastico.cc/api). */
+    baseUrl?: string;
+    /** Modello di default (se non specificato nella request). */
+    defaultModel?: string;
+    /**
+     * Nome visibile dell'assistente (es. "GenioAI"). L'SDK non lo usa per sé — non lo inietta
+     * da solo nel prompt, non fa branding automatico — è una singola fonte di verità che chi
+     * integra può riusare sia per comporre `defaultSystemPrompt` (`` `Ti chiami ${name}...` ``)
+     * sia lato UI (letto da `ai.name`), invece di ripetere la stringa in più punti.
+     */
+    name?: string;
+    /**
+     * Iniettato come primo messaggio "system" se il chiamante non ne ha già messo uno in
+     * `messages`. Comodo per non ripeterlo ad ogni create(); non fa sostituzione di variabili —
+     * il testo arriva già pronto da chi integra.
+     */
+    defaultSystemPrompt?: string;
+    /** Tool locali/azione-client registrati fin da subito (in alternativa/oltre a addTool()). */
+    tools?: import("./local-tools.js").RegisteredTool[];
+    /**
+     * Contesto fidato di default per ogni chiamata (secondo argomento di ogni `execute` dei
+     * tool locali), sovrascrivibile per singola create() via `ChatCompletionCreateParams.context`.
+     * Mai visto dal modello.
+     */
+    context?: unknown;
+    /**
+     * La **sessione di attività** da continuare, se se ne sta continuando una.
+     *
+     * Omessa — il caso normale — il primo conio ne apre una e il client la tiene finché vive. Vale
+     * la pena passarla in un caso solo: un processo che riparte e sa di star continuando lo stesso
+     * tratto di lavoro. **Non è una credenziale**: non autorizza niente, viene confrontata con il
+     * conto dedotto dalla credenziale, e una che non è propria (o che la potatura ha già preso) dà
+     * semplicemente una sessione nuova — mai un errore. Quella buona è sempre quella che torna,
+     * leggibile da `ai.activitySessionId`.
+     */
+    activitySessionId?: string;
+    /**
+     * Il **prodotto del marketplace** che questo client integra, per id (es. `"genioai"`).
+     *
+     * Omesso, il caso ordinario: si usa il modello e basta. Valorizzato, ogni chiave viene coniata
+     * per quel prodotto, alle condizioni con cui il progetto lo ha attivato; se il progetto non lo ha
+     * attivato dal marketplace il conio è rifiutato (`TOOL_NOT_ENABLED`). Il prodotto si accende e si
+     * spegne dal marketplace, non da questo campo.
+     *
+     * Va dichiarato da chi integra quel prodotto, e da nessun altro.
+     */
+    product?: string;
+    /** ID progetto FANTASTICO (determina quali MCP sono abilitati). */
+    projectId?: string;
+    /**
+     * USD prenotati a ogni giro di budget per un tenant (default 0.10). Il client scala in
+     * locale e regola il consumo reale al giro successivo.
+     */
+    reserveUsd?: number;
+    /** Max turni interni dell'orchestratore (default 8). */
+    maxTurns?: number;
+    /** Timeout orchestrazione in ms (default 90_000). */
+    budgetMs?: number;
+    /** Timeout di una chiamata a un tool, in ms (default 180_000). Scaduto, non si riprova: il tool può aver lavorato e addebitato. */
+    mcpTimeoutMs?: number;
+    /**
+     * Origini pubbliche dei tool → origini interne, per chiamarli senza uscire dalla macchina (es.
+     * `{ "https://tools.example.com": "http://127.0.0.1:8080" }`). Omessa, si legge
+     * `FANTASTICO_TOOL_ORIGIN_MAP` (`pubblica=interna[,…]`). Vedi `tool-origin.ts`.
+     */
+    toolOriginMap?: Record<string, string>;
+    /**
+     * Il `reasoning` di default per ogni richiesta che non ne porta uno suo.
+     *
+     * Esiste per far prendere la decisione **una volta sola**, alla costruzione, dove si vede nel
+     * codice e passa in revisione — invece che a ogni call site, dove prima o poi ne resta indietro
+     * uno. Omesso, non cambia niente per nessuno: non parte alcun campo.
+     *
+     * Il `reasoning` di una singola richiesta **sostituisce** questo, non ci si fonde: niente merge
+     * profondo, niente campo di qui che sopravvive dentro l'oggetto di lì. Prevedibile batte furbo.
+     *
+     * ⚠️ Attenzione a `{ enabled: false }` come default di client: alcuni modelli ragionano
+     * obbligatoriamente (`reasoning.mandatory` nel catalogo di OpenRouter) e **rifiutano** la
+     * richiesta di spegnerlo. Un default di client li renderebbe inutilizzabili da questo client.
+     * Vedi {@link ReasoningConfig}.
+     */
+    reasoning?: ReasoningConfig;
+    /**
+     * Quanto insistere quando il provider risponde con un errore che passa da solo — un rate limit
+     * (429), un provider sovraccarico. Default: due ritentativi, esponenziale con jitter, e
+     * `Retry-After` rispettato quando il provider lo manda. `false` li spegne.
+     *
+     * Vale la pena toccarlo perché la tolleranza alla latenza non è la stessa ovunque: una pagina
+     * che risponde a un utente non è un lavoro in coda. Comunque non si dorme mai oltre `budgetMs`:
+     * sforarlo farebbe emergere un `TIMEOUT` al posto della causa vera. Vedi `backoff.ts`.
+     */
+    retry?: import("./backoff.js").RetryOptions | false;
+    /** Iniettabile nei test. */
+    fetchImpl?: typeof fetch;
+    /**
+     * @deprecated Non fa niente. Tenuto perché un client scritto contro una versione precedente
+     * continui a compilare: valorizzarlo non cambia in alcun modo il comportamento del client.
+     *
+     * Serviva a saltare il conio e usare una chiave del provider già in mano (BYOK/sviluppo).
+     * Quella modalità non esiste più, e non perché il caso d'uso fosse sbagliato: il campo ne
+     * spegneva **cinque** alla volta. Senza conio si perdevano anche le concessioni sui tool (cioè
+     * il marketplace, per sempre), l'handle da restituire, la sessione di attività, il `max_tokens`
+     * calcolato sul tetto della chiave e il ri-conio dopo un 401 del provider.
+     *
+     * Chi lo passava per **coniare esplicitamente all'avvio** — leggere tetto e scadenza, o
+     * restituire la chiave all'uscita invece di lasciarla scadere — usi `ai.runtimeKeys.ensure()`,
+     * che dà gli stessi numeri senza spegnere nient'altro. Chi lo passava per **BYOK vero** non ha
+     * ancora una strada: quando ci sarà è il conio a restituire la chiave del cliente, non un ramo
+     * qui.
+     *
+     * **Attenzione a cosa compra questo silenzio.** Un client che lo valorizzava non coniava
+     * affatto; ora conia, quindi impegna denaro sulla riserva del progetto. La chiamata continua a
+     * funzionare, ma non è più gratis per il progetto — ed è il genere di differenza che si legge
+     * su un estratto conto invece che in un errore.
+     */
+    providerApiKey?: string;
+}
+/** Configurazione MCP risolta dal control plane. */
+export interface ToolConfig {
+    name: string;
+    url: string;
+    authToken: string;
+    allowedTools: string[];
+    toolDefinitions?: ToolDefinition[];
+}
+/** Tool definition (OpenAI function-calling format). */
+export interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/** Tool call emesso dal modello (OpenAI function-calling format). */
+export interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * Parte di contenuto testuale multi-part (stile OpenAI Chat Completions) con
+ * l'estensione `cache_control` che OpenRouter inoltra ai provider che la supportano
+ * (Anthropic in primis). FANTASTICO non interpreta mai questo campo: lo passa 1:1.
+ *
+ * Verificato empiricamente (2026-07): il caching scatta solo
+ * se la request forza `provider: {order:["Anthropic"]}` — vedi `pinProvider` sotto —
+ * e il blocco supera la soglia minima del modello (1024-4096 token a seconda del modello).
+ */
+export interface ChatContentPart {
+    type: "text";
+    text: string;
+    cache_control?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h";
+    };
+}
+/** Messaggio "raw": stesso vocabolario OpenAI di ChatMessage, ma multi-part + tool. */
+export interface RawChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | ChatContentPart[] | null;
+    /** Presente sui messaggi "assistant" quando il modello ha richiesto tool. */
+    tool_calls?: ToolCall[];
+    /** Presente sui messaggi "tool": a quale tool_call risponde. */
+    tool_call_id?: string;
+}
+/**
+ * Request per chat.completions.createRaw() — nessuna orchestrazione interna: una sola
+ * chiamata a OpenRouter, il chiamante gestisce il proprio loop di tool-use (per i casi
+ * con tool propri che l'orchestrazione opaca di create()
+ * non può risolvere).
+ */
+export interface RawCompletionCreateParams {
+    model?: string;
+    messages: RawChatMessage[];
+    /** Tool del CHIAMANTE (formato OpenAI function-calling). FANTASTICO non li esegue mai:
+     *  ritorna i tool_calls così come arrivano dal modello. Per i tool del marketplace
+     *  FANTASTICO, vedi `ai.tools.list()`/`ai.tools.execute()`. */
+    tools?: Array<ToolDefinition | {
+        type: "openrouter:web_search";
+        parameters?: {
+            engine?: "auto" | "native" | "exa" | "firecrawl" | "parallel" | "perplexity";
+            max_results?: number;
+            max_total_results?: number;
+            max_uses?: number;
+            search_context_size?: "low" | "medium" | "high";
+        };
+    }>;
+    /** Budget totale di chiamate ai tool server del provider. */
+    max_tool_calls?: number;
+    /** Formato OpenAI: forza/disabilita l'uso di tool per questo turno. */
+    tool_choice?: "auto" | "none" | "required" | {
+        type: "function";
+        function: {
+            name: string;
+        };
+    };
+    temperature?: number;
+    max_tokens?: number;
+    /** Controllo sui thinking token. Omesso, non viene mandato nulla. Vedi {@link ReasoningConfig}. */
+    reasoning?: ReasoningConfig;
+    /** Stesso significato di create(): budget per-tenant via /api/runtime/budget. */
+    user?: string;
+    /**
+     * Forza il routing su Anthropic diretto (default: true se un content-block ha
+     * `cache_control`, altrimenti non impostato). Senza questo, OpenRouter può instradare
+     * su un provider (es. Amazon Bedrock) che ignora `cache_control` senza errore: si paga
+     * il prezzo pieno in silenzio. Passa `false` esplicitamente per il routing di default.
+     */
+    pinProvider?: boolean;
+}
+/** Risposta di chat.completions.createRaw(). */
+export interface RawChatCompletion {
+    id: string;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: RawChatMessage;
+        finish_reason: "stop" | "length" | "tool_calls";
+    }>;
+    usage: CompletionUsage;
+}
+/** Parametri per la creazione di un conto utente (sub-account). */
+export interface AccountCreateParams {
+    /** Identificativo univoco del tenant/utente finale. È l'indirizzo del conto in ogni chiamata. */
+    userKey: string;
+    /**
+     * Nome con cui mostrare il conto (es. nome dello studio). Non è un identificativo: non deve
+     * essere unico e nessuna chiamata trova un conto per nome. Torna come `displayName`.
+     */
+    label?: string;
+    /**
+     * Da cosa il conto è **finanziato**. Dalla 0.13.0; omesso, `standard` — come prima.
+     *
+     * - `standard`: riceve la quota periodica del piano del progetto. Se quella quota è zero, il
+     *   conto nasce **vuoto** e va finanziato con un trasferimento dalla riserva.
+     * - `trial`: riceve **una volta sola** la concessione di prova del piano e ha una scadenza; alla
+     *   scadenza il Cloud lo sospende. È il conto giusto per un cliente in prova gratuita, e si
+     *   chiude con {@link Fantastico.accounts}`.upgrade()` quando si abbona.
+     * - `unlimited`: ogni chiave attinge alla riserva del progetto, senza quota propria.
+     *
+     * Non è l'ambiente, che è un asse a sé: un conto di sviluppo in prova è una cosa ordinaria.
+     * `trial` è rifiutato se il piano del progetto non offre prove (concessione a zero).
+     */
+    type?: "standard" | "trial" | "unlimited";
+    /** Tetto di spesa per periodo in USD; 0 = nessun limite. */
+    spendLimit?: number;
+    /** Durata del periodo di budget in giorni. */
+    periodDays?: number;
+}
+/** Info del conto restituita dal backend. */
+export interface AccountInfo {
+    _id: string;
+    userKey: string;
+    /** Il nome con cui mostrare il conto, se ne ha uno (`null` = nessuno). Dalla 0.12.1. */
+    displayName?: string | null;
+    /**
+     * Da cosa il conto è finanziato ora — vedi {@link AccountCreateParams.type}. Dalla 0.13.0.
+     * Una prova lo resta finché non la chiude `accounts.upgrade()`.
+     */
+    type?: "standard" | "trial" | "unlimited";
+    label?: string;
+    spendLimit: number;
+    periodDays: number;
+    spent: number;
+    reserved: number;
+    status: string;
+    createdAt: string;
+}
+/**
+ * Campi modificabili di un conto già esistente. Si aggiorna solo ciò che si passa.
+ *
+ * Oggi l'unico è `label`, il nome con cui mostrare il conto: una stringa lo imposta, la stringa
+ * vuota lo toglie. `spendLimit`, `periodDays` e `status` restano dichiarati per compatibilità ma il
+ * Cloud li rifiuta (`FIELD_NOT_UPDATABLE`): il credito si trasferisce dalla riserva, il periodo lo
+ * dà il piano del conto, la sospensione ha le sue rotte.
+ */
+export interface AccountUpdateParams {
+    label?: string;
+    spendLimit?: number;
+    periodDays?: number;
+    status?: "active" | "suspended";
+}
+/**
+ * Chiave di **conto** (`ck-fant-…`): la credenziale che si consegna a un
+ * client che gira **fuori dal proprio perimetro** — un plugin sul server di un cliente.
+ * Vale un conto solo, e il tetto della runtime key che conia è il credito di quel conto.
+ *
+ * Il valore in chiaro non compare qui: esiste solo nella risposta a `issue`/`rotate`.
+ */
+export interface AccountKeyInfo {
+    id: string;
+    prefix: string;
+    contoId: string;
+    projectId: string;
+    env: "dev" | "prod";
+    userKey: string;
+    label?: string;
+    createdAt: string;
+    revokedAt?: string;
+    revokedReason?: "rotated" | "revoked";
+}
+/** Emissione o rotazione: **l'unica** risposta che contiene la chiave in chiaro. */
+export interface IssuedAccountKey {
+    id: string;
+    /** Valore in chiaro — esiste solo qui. A riposo il Cloud ne tiene solo l'hash. */
+    key: string;
+    prefix: string;
+    contoId: string;
+    userKey: string;
+    label?: string;
+    createdAt: string;
+}
+/**
+ * Una runtime key OpenRouter ancora aperta su un conto — **mai il suo segreto**.
+ *
+ * Il segreto esiste una volta sola, nella risposta al conio, e da lì in poi vive solo nella
+ * memoria di chi l'ha chiesto: il Cloud non lo conserva, quindi non c'è nulla da
+ * restituire qui. `recordId` è l'handle del provider — legge e revoca, non compra — ed è lo
+ * stesso identificativo che il conio ha già consegnato.
+ *
+ * **Da non confondere con `AccountKeyInfo`**, che è una credenziale FANTASTICO (`ck-fant-…`):
+ * quella autentica verso il Cloud, è conservata come hash e non scade. Questa è una credenziale
+ * OpenRouter, non è conservata affatto, e scade.
+ */
+export interface RuntimeKeyInfo {
+    /**
+     * L'handle del provider, o `null` per un'autorizzazione la cui chiave non è mai stata coniata
+     * (un crash fra le due scritture). Occupa comunque uno slot e non è revocabile: non c'è nulla
+     * da revocare. Il reap la liquida alla scadenza.
+     */
+    recordId: string | null;
+    /** Il tetto della chiave presso il provider. */
+    keyLimit: string;
+    /** Quanto il provider dice che ha speso finora, contro quel tetto. */
+    spent: string;
+    /** Quanto ha impegnato del conto: un blocco scalato dal fattore del piano. */
+    cost: string;
+    createdAt: string;
+    /** Quando il reap la prenderà. Anticipata appena la chiave risulta esaurita. */
+    expiresAt: string;
+    /**
+     * Valorizzato quando la chiave è già stata disabilitata sul provider e sta aspettando che la
+     * finestra di riporto si chiuda. Tiene ancora il suo slot, ma non c'è più niente da chiederle:
+     * revocarla di nuovo risponde `false`.
+     */
+    disabledAt: string | null;
+}
+/**
+ * @deprecated Nessun addebito parte più da qui. Vedi `Fantastico.usage.record`.
+ */
+export interface UsageRecordParams {
+    /** Identificativo del tenant/utente finale a cui addebitare (conto). */
+    userKey: string;
+    /** Id del servizio nel registry (es. "anonimizzazione"). */
+    service: string;
+    /** Unità di consumo del listino (es. "document", "chatTurn"). */
+    unit: string;
+    /** Quantità di unità consumate. */
+    quantity: number;
+    /** Id idempotente (es. jobId): la ridelivery non riaddebita. */
+    refId?: string;
+}
+/**
+ * @deprecated L'esito di un addebito che non avviene più. Vedi `Fantastico.usage.record`.
+ */
+export interface UsageRecordResult {
+    service: string;
+    unit: string;
+    quantity: number;
+    /** **Sempre `0`**: non è stato addebitato niente. */
+    amount: number;
+    /** **Sempre `false`**: non c'è stato niente da deduplicare. */
+    deduped: boolean;
+}
+/**
+ * La runtime key con cui **questo client** sta lavorando — di nuovo, mai il suo segreto.
+ *
+ * Esiste per una ragione sola: da quando il conio è sempre dell'SDK, chi integra non ha più un
+ * posto da cui vedere cosa sta usando. Sono i quattro numeri che servono a chiudere il giro —
+ * l'handle per restituirla, il tetto per sapere quanto può chiedere, la scadenza, e la sessione
+ * sotto cui questa spesa si ritroverà a valle.
+ *
+ * Il segreto non è qui e non è altrove: vive nella memoria dell'`AuthClient` per il suo TTL e non
+ * attraversa mai la superficie pubblica. Chi ha bisogno di una credenziale del
+ * provider in mano non ha bisogno di questo SDK.
+ */
+export interface RuntimeKeyHandle {
+    /** L'handle presso il provider: lo stesso che `runtimeKeys.revoke` accetta. */
+    recordId: string;
+    /** Il tetto della chiave in USD, o `null` se il conio non l'ha dichiarato. */
+    limitUsd: number | null;
+    /** Quanto il conio ha impegnato sul conto, come stringa decimale. `null` se non dichiarato. */
+    costUsd: string | null;
+    /** Quando scade, ISO. Oltre, il reap la prende. */
+    expiresAt: string;
+    /** La sessione di attività aperta o continuata da questo conio. */
+    activitySessionId: string | null;
+    /**
+     * I tool che questo conio ha **concesso** — cioè abilitati sul progetto, con un token emesso —
+     * per id e nome. Mai il token.
+     *
+     * Non è l'elenco di `ai.tools.list()`, e la differenza è il punto: quello contiene i tool
+     * concessi **e** verificati (documento letto, digest che torna), e scarta in silenzio sia un
+     * tool non abilitato sia uno abilitato che non risponde. Chi deve distinguere "spento" da
+     * "acceso ma guasto" — una funzione di sistema che, se attiva, non può essere saltata — confronta
+     * i due elenchi: concesso e assente da `list()` vuol dire guasto, non spento.
+     */
+    tools: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+/**
+ * Il saldo del **proprio** conto (`ai.balance()`, solo con una chiave di conto).
+ *
+ * `remainingUsd` è quanto resta da **impegnare**, non il saldo lordo: una parte può essere già
+ * bloccata da una chiave viva. `lowBalance` è la soglia di preavviso, e la decide il Cloud e non
+ * l'installazione — è una scelta di prodotto, e deve poter cambiare senza toccare i client già
+ * distribuiti.
+ *
+ * **È una sonda, non un blocco.** Il rifiuto vero è il conio, che non emette una chiave quando il
+ * conto è a secco; questo serve a dire "stai per finire" prima che succeda.
+ */
+export interface ContoBalance {
+    remainingUsd: number;
+    lowBalance: boolean;
+    status: string;
+}
+/**
+ * Un modello disponibile su OpenRouter (`ai.models.list()`). Pass-through di quanto
+ * risponde il provider: solo `id` è garantito, il resto varia col catalogo — non lo
+ * ricopiamo campo per campo per non irrigidirci a ogni loro aggiunta.
+ */
+export interface OpenRouterModel {
+    id: string;
+    name?: string;
+    description?: string;
+    context_length?: number;
+    pricing?: {
+        prompt?: string;
+        completion?: string;
+        request?: string;
+        image?: string;
+        [key: string]: unknown;
+    };
+    /** Modalità in ingresso e in uscita (`output_modalities: ["speech"]` per un modello TTS). */
+    architecture?: {
+        modality?: string;
+        input_modalities?: string[];
+        output_modalities?: string[];
+        [key: string]: unknown;
+    };
+    /**
+     * Le voci che un modello text-to-speech ammette (`ai.audio.speech.models()`). Assente sui
+     * modelli di chat, e su quei TTS che la voce la prendono da un riferimento audio
+     * (`input_references`) invece che da un nome.
+     */
+    supported_voices?: string[];
+    /**
+     * Nomi dei provider che servono QUESTO modello con Zero Data Retention — per-endpoint,
+     * non per-modello: lo stesso modello può avere provider ZDR e non-ZDR insieme, e
+     * OpenRouter non garantisce di instradare verso uno ZDR a meno di richiederlo
+     * esplicitamente (`provider.zdr: true` nella chiamata). Assente sia quando nessun
+     * provider è ZDR sia quando il catalogo ZDR non era disponibile — mai da leggere come
+     * "non è ZDR" in quest'ultimo caso.
+     */
+    zdrProviders?: string[];
+    [key: string]: unknown;
+}
+/** Errore FANTASTICO strutturato. */
+export declare class FantasticoError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status: number, 
+    /**
+     * Il motivo dato dal provider LLM a monte, quando c'è (es. `Anthropic: This organization has
+     * been disabled…`). **Solo per i log**: non sta nel messaggio perché il messaggio arriva
+     * spesso davanti all'utente finale, che non deve vedere né il nome del fornitore né la sua
+     * prosa. Assente (non `undefined`) quando non c'è, così non sporca l'output di `inspect`.
+     */
+    providerDetail?: string | null);
+    readonly providerDetail?: string;
+}
+/**
+ * Il modello ha esaurito il budget di output e non ha restituito **niente**.
+ *
+ * **Perché è un errore e non una risposta.** L'HTTP è 200, l'usage è misurato e addebitato, e il
+ * contenuto è una stringa vuota. È la stessa forma di `errorInBody` (`provider-error.ts`): un 200
+ * che non è un successo — lì il fallimento è dichiarato nel corpo, qui è desumibile da
+ * `finish_reason` più un contenuto che non c'è. Per chi fa estrazione strutturata la differenza fra
+ * le due letture è tutto: `""` si analizza come un `[]` valido, cioè "non ho trovato niente" — una
+ * risposta plausibile, misurata, apparentemente riuscita, e falsa.
+ *
+ * **Non è ritentabile e non fa ri-coniare.** È una `FantasticoError`, quindi `withProviderRetry` la
+ * lascia passare intatta: una chiave nuova non cambia nulla, e un ritentativo automatico
+ * rispenderebbe i soldi del chiamante per lo stesso esito. Non si ritenta nemmeno "utilmente" con
+ * il ragionamento spento: sarebbe la stessa classe di comportamento invisibile che questo errore
+ * esiste per rendere visibile.
+ *
+ * **I numeri sono il rimedio.** Con `reasoningTokens` alto il ragionamento si è mangiato lo spazio
+ * della risposta (spegnerlo, o alzare `maxTokens`); a zero, la risposta semplicemente non ci stava
+ * (alzare `maxTokens`) — una causa su cui il campo `reasoning` non può niente. Senza questi numeri
+ * le due si distinguono solo dopo ore.
+ */
+export declare class EmptyCompletionError extends FantasticoError {
+    /** Il modello che ha risposto, come lo riporta il provider. */
+    readonly model: string;
+    /** Il `max_tokens` **effettivamente mandato**, o `null` se non ne è partito nessuno. */
+    readonly maxTokens: number | null;
+    /** Token di output di QUESTA risposta (comprensivi di quelli di ragionamento). */
+    readonly completionTokens: number;
+    /**
+     * Quanti di quei token sono stati spesi a ragionare.
+     *
+     * Su `create()` sono i numeri del **turno fallito**, non l'aggregato dell'orchestrazione: a
+     * chi deve intervenire serve sapere quale chiamata ha sforato, non quanto è costato il giro.
+     */
+    readonly reasoningTokens: number;
+    constructor(message: string, 
+    /** Il modello che ha risposto, come lo riporta il provider. */
+    model: string, 
+    /** Il `max_tokens` **effettivamente mandato**, o `null` se non ne è partito nessuno. */
+    maxTokens: number | null, 
+    /** Token di output di QUESTA risposta (comprensivi di quelli di ragionamento). */
+    completionTokens: number, 
+    /**
+     * Quanti di quei token sono stati spesi a ragionare.
+     *
+     * Su `create()` sono i numeri del **turno fallito**, non l'aggregato dell'orchestrazione: a
+     * chi deve intervenire serve sapere quale chiamata ha sforato, non quanto è costato il giro.
+     */
+    reasoningTokens: number);
+}