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

package/dist/auth.d.ts

@@ -0,0 +1,216 @@
+import { type ToolOriginMap } from "./tool-origin.js";
+import type { ContoBalance, RuntimeKeyHandle, ToolConfig } from "./types.js";
+export interface AuthClientOptions {
+    /** La credenziale verso il Cloud: project key `sk-fant-…` o chiave di conto `ck-fant-…`. */
+    apiKey: string;
+    /** Base url comprensivo di `/api`. */
+    baseUrl: string;
+    /** La sessione di attività da continuare, se il chiamante ne aveva una. Vedi il campo omonimo. */
+    activitySessionId?: string;
+    /** Il prodotto del marketplace che questo client integra, mandato a ogni conio. Vedi
+     *  `FantasticoOptions.product`. */
+    product?: string;
+    /** Origini pubbliche dei tool → origini interne. Vedi `tool-origin.ts`. */
+    toolOriginMap?: ToolOriginMap;
+    fetchImpl: typeof fetch;
+}
+/** Un tool raggiungibile e la credenziale con cui parlarci, dal conio. */
+export interface ToolGrant {
+    id: string;
+    name: string;
+    endpoint: string;
+    /** Cambia quando cambiano i tool: e' la chiave di cache degli schemi. `null` = non dichiarata. */
+    schemaVersion: string | null;
+    /**
+     * Il digest di cio' che il control plane ha registrato per questo tool.
+     *
+     * Arriva col conio, cioe' per una strada diversa da quella con cui arrivera' il documento; e' il
+     * confronto fra le due che vale qualcosa. `null` non dovrebbe capitare — un tool senza schema non
+     * riceve un token, quindi non produce una concessione — e se capita si tratta come "non
+     * verificabile", che ha lo stesso esito di "non corrisponde".
+     */
+    schemaHash: string | null;
+    /** Il segreto. Torna una volta sola dal conio e non e' recuperabile da nessuna parte. */
+    token: string;
+}
+/** Esito di una prenotazione di budget per un tenant. */
+export interface BudgetResult {
+    granted: number;
+    remaining: number;
+    lowBalance: boolean;
+}
+/**
+ * Client verso il control plane FANTASTICO.
+ *
+ * Una sola credenziale, e la sceglie chi costruisce: project key `sk-fant-…` (superficie
+ * `/api/runtime`) o chiave di conto `ck-fant-…` (superficie `/api/edge`). In nessuno dei due casi
+ * entra un segreto di piattaforma nel perimetro del cliente. Tiene le runtime key OpenRouter in
+ * memoria con rinnovo prima della scadenza — mai su disco, mai nei log — **una per conto**.
+ */
+export declare class AuthClient {
+    private readonly opts;
+    /**
+     * Una chiave viva **per conto**, non una per client — e la chiave della mappa è la `userKey`
+     * del tenant, `""` per il conto che la credenziale sottintende (il proprietario del progetto
+     * su `/runtime`, il conto della credenziale su `/edge`).
+     *
+     * **È il conto che paga, quindi è il conto che conia.** Un conio apre un *hold* sul conto che
+     * nomina, quindi ogni tenant ha la propria: una key, una sessione e dei tool token per
+     * ciascuno.
+     *
+     * Non è una cache che cresce senza fine nel senso che preoccupa: una voce tiene una chiave che
+     * scade da sola, e il `maxOpenKeys` del piano è **per conto**, quindi un tenant in più non
+     * consuma gli slot degli altri.
+     */
+    private readonly accounts;
+    /** Listino del provider, per {@link outputPricePerToken}. Vedi il TTL li accanto.
+     *  Uno solo per client: il prezzo di un modello non dipende da chi paga. */
+    private models;
+    /** Schemi gia' scaricati, per `${tool}@${versione}`: la versione e' il motivo per cui il
+     *  Cloud la manda, e cambia esattamente quando cambiano i tool. */
+    private schemas;
+    /**
+     * Quale delle due superfici parlare, **dedotta dalla chiave e non ricevuta**.
+     *
+     * Cambia il prefisso delle rotte e nient'altro: `/runtime/key` e `/edge/key` portano allo stesso
+     * `ledger.mint` e rispondono la stessa forma. Quel che cambia davvero è **chi nomina il conto**:
+     * su `/runtime` lo nomina il chiamante — la project key vale per tutti i conti del progetto,
+     * quindi il conio deve dire quale paga — mentre su `/edge` il conto è quello della credenziale e
+     * nel corpo non c'è un campo di identità da riempire, né deve essercene uno.
+     *
+     * Dedotta qui e non passata dal costruttore perché `surfaceOf` è una funzione pura della stessa
+     * stringa: chiamarla due volte dà due volte lo stesso valore, mentre un parametro può portarne
+     * uno che non corrisponde alla chiave con cui viaggia.
+     */
+    private readonly surface;
+    constructor(opts: AuthClientOptions);
+    /**
+     * Lo stato del conto nominato, creandolo vuoto la prima volta. `undefined` = il conto che la
+     * credenziale sottintende.
+     */
+    private state;
+    private headers;
+    /**
+     * L'url di una rotta del control plane sulla superficie di questa credenziale.
+     *
+     * `/runtime` ed `/edge` sono anche i due valori di {@link Surface}, e non è una coincidenza da
+     * cui dipendere per caso: le due superfici portano le stesse rotte con lo stesso nome
+     * (`/key`, `/keys`, `/models`), e a cambiare è chi nomina il conto. Le poche che esistono solo
+     * di qua o solo di là non passano da qui — hanno un metodo loro che dice perché.
+     */
+    private url;
+    /**
+     * Runtime key OpenRouter **del conto indicato**: conia (o riusa quella in memoria) via
+     * `POST <superficie>/key`.
+     *
+     * `userKey` è il tenant a cui la chiamata è attribuita — il campo `user` di
+     * `chat.completions.create`. Omesso, è il conto che la credenziale sottintende. La chiave
+     * coniata **impegna il conto che nomina**, quindi passarlo o no decide chi paga.
+     */
+    getRuntimeKey(userKey?: string): Promise<string>;
+    /**
+     * Butta via la runtime key in mano (es. dopo un 401 da OpenRouter): il prossimo giro ne conia
+     * un'altra.
+     *
+     * **Non c'è niente da dire al Cloud, e prima si diceva.** Qui partiva un `force: true` nel corpo
+     * del conio, per saltare una cache di riuso che il vecchio servizio `vending` teneva: senza, il
+     * Cloud avrebbe restituito la STESSA chiave appena scartata. Il ledger non ha quella cache —
+     * ogni conio apre un hold suo — e `ledger.mint` non dichiara affatto quel parametro, quindi il
+     * campo viaggiava e nessuno lo leggeva. Quel che conta è tutto qui: senza la copia locale, il
+     * prossimo `getRuntimeKey()` chiede davvero.
+     */
+    invalidate(userKey?: string): void;
+    /** I tool token in mano per quel conto, gia' con endpoint e versione dello schema. Vuoto
+     *  prima del conio. */
+    getToolGrants(userKey?: string): readonly ToolGrant[];
+    /**
+     * Il tetto in USD della runtime key in mano per quel conto, o `null` se non se ne è ancora
+     * coniata una. Da leggere subito dopo `getRuntimeKey()`, **con lo stesso conto**: due tenant
+     * hanno due chiavi e due tetti, e leggere quello sbagliato darebbe un `max_tokens` calcolato
+     * su una chiave che non sta per essere usata.
+     */
+    getKeyLimitUsd(userKey?: string): number | null;
+    /**
+     * Cosa si sta usando, senza il segreto: handle, tetto, impegno, scadenza e sessione.
+     *
+     * `null` finché non si è coniato — e chiamarlo prima del primo conio è la cosa da non fare:
+     * `client.ts` lo legge sempre dopo un `getRuntimeKey()`, che è ciò che rende il `null`
+     * impossibile al chiamante invece che soltanto improbabile.
+     */
+    getHandle(userKey?: string): RuntimeKeyHandle | null;
+    /** L'handle che porta questo `recordId`, se è uno di quelli in mano — e il conto a cui
+     *  appartiene. Serve a `runtimeKeys.revoke`, che nomina una chiave e non un conto. */
+    findByRecordId(recordId: string): {
+        userKey: string;
+    } | null;
+    /** La sessione di attività corrente di quel conto, o `null` prima del suo primo conio. Non è
+     *  una credenziale: non autorizza niente e si può loggare e mostrare. Serve a raggruppare la
+     *  spesa a valle. */
+    getActivitySessionId(userKey?: string): string | null;
+    /**
+     * Il saldo del proprio conto (`GET /api/edge/balance`) — **solo sulla superficie edge**.
+     *
+     * È il gemello di `reserveBudget` per una credenziale che non può nominare un conto: la
+     * domanda "quanto resta" è la stessa, ma qui non c'è niente da prenotare e niente da regolare,
+     * perché non c'è un tenant a cui attribuire. Il blocco vero resta il conio.
+     */
+    balance(): Promise<ContoBalance>;
+    /**
+     * Regola il consumo di un tenant e prenota il budget successivo (`/api/runtime/budget`).
+     * Se il tenant o il progetto sono a secco, il Cloud risponde 402 e qui si solleva un
+     * FantasticoError **prima** che parta la chiamata LLM.
+     */
+    reserveBudget(userKey: string, usedUsd: number, requestUsd: number): Promise<BudgetResult>;
+    /**
+     * I tool di questa sessione: **uno per concessione**, chiesti a ciascun tool.
+     *
+     * **Non c'e piu un ripiego**. Sotto c'era `legacyCatalogTools`: un solo
+     * "tool" sintetico chiamato `fantastico` che leggeva `GET /api/tools` e instradava ogni
+     * esecuzione su `POST /api/tools/execute` con la project key. Quelle due rotte non esistono
+     * piu, e il ripiego non era neutro — **saltava la verifica**: il catalogo lo componeva il
+     * Cloud, quindi non c'era un documento firmato di cui ricalcolare il digest, e le descrizioni
+     * che finivano davanti al modello arrivavano senza che niente ne rispondesse.
+     *
+     * **Nessuna concessione significa nessun tool, e va detto cosi.** Prima significava "prova
+     * dall'altra parte", quindi un conio senza token — un piano che non prezza un tratto di
+     * lavoro, un progetto che non ha abilitato niente — si vedeva solo come una chat che
+     * funzionava un po' peggio. Ora e un elenco vuoto, che e la verita.
+     *
+     * **Non conia.** La discovery e' una lettura, e restituisce quello che l'ultimo conio ha
+     * portato: chi ha bisogno dei token si assicura la chiave **prima** di chiamare qui, ed e'
+     * `client.ts` a farlo in un posto solo (`remoteTools`). Se coniasse anche questo, ci sarebbero
+     * due punti da cui parte un conio, e il secondo sarebbe quello che nessuno si aspetta.
+     */
+    getTools(userKey?: string): Promise<ToolConfig[]>;
+    /**
+     * Chiede a UN tool i propri tool, presentando il token emesso per lui.
+     *
+     * **Lo schema lo dice il tool, non il control plane.** Il ledger tiene endpoint, listino e
+     * il *digest* dello schema, mai le descrizioni: sono dati del tool, e una copia nel control
+     * plane sarebbe una seconda fonte di verita' per qualcosa che non puo' validare. In piu' una
+     * descrizione di tool e' testo che finisce nel contesto di un modello, quindi deve venire da chi
+     * ne risponde.
+     *
+     * **Un tool che non risponde esce dal catalogo di questo giro, e basta.** Il degrado e' lo
+     * stesso che questo metodo ha sempre avuto verso il Cloud: N endpoint non devono diventare N modi
+     * nuovi di far fallire una chat che senza tool funzionerebbe.
+     */
+    private describeTool;
+    /**
+     * Il prezzo in USD di **un** token in uscita per un modello, dal catalogo del provider.
+     *
+     * Serve solo a `max-tokens.ts`, ed e' per questo che sta qui accanto al tetto della chiave: i due
+     * numeri hanno senso solo insieme, e chiederli a due posti diversi era il motivo per cui il conto
+     * non veniva fatto affatto.
+     *
+     * **Best-effort per costruzione**: se il catalogo non risponde si torna `null`, che a valle
+     * significa "non scrivere `max_tokens`" — cioe' esattamente il comportamento di prima. Un
+     * arricchimento che fallisce deve togliere un miglioramento, mai una chiamata.
+     *
+     * Cache in memoria con TTL, come quella che il Cloud tiene davanti alla stessa rotta: il
+     * listino non cambia fra due messaggi di una chat, e senza cache questo aggiungerebbe un giro di
+     * rete a ogni conio.
+     */
+    outputPricePerToken(model: string): Promise<number | null>;
+    private mint;
+}

package/dist/auth.js

@@ -0,0 +1,224 @@
+import { resolveToolEndpoint } from "./tool-origin.js";
+import { schemaDigest } from "./schema-digest.js";
+import { wireTool } from "./tool-definition.js";
+import { FantasticoError } from "./types.js";
+import { surfaceOf } from "./surface.js";
+const MODELS_TTL_MS = 5 * 60_000;
+export class AuthClient {
+    opts;
+    accounts = new Map();
+    models = null;
+    schemas = new Map();
+    surface;
+    constructor(opts) {
+        this.opts = opts;
+        this.surface = surfaceOf(opts.apiKey);
+        this.state().activitySessionId = opts.activitySessionId ?? null;
+    }
+    state(userKey) {
+        const id = userKey ?? "";
+        let s = this.accounts.get(id);
+        if (s === undefined) {
+            s = { runtimeKey: null, mintPromise: null, activitySessionId: null, tools: [] };
+            this.accounts.set(id, s);
+        }
+        return s;
+    }
+    headers(json = false) {
+        const h = { Authorization: `Bearer ${this.opts.apiKey}` };
+        if (json)
+            h["Content-Type"] = "application/json";
+        return h;
+    }
+    url(path) {
+        return `${this.opts.baseUrl}/${this.surface}${path}`;
+    }
+    async getRuntimeKey(userKey) {
+        const st = this.state(userKey);
+        const skew = 60_000;
+        if (st.runtimeKey && st.runtimeKey.expiresAt - Date.now() > skew) {
+            return st.runtimeKey.key;
+        }
+        if (st.mintPromise)
+            return (await st.mintPromise).key;
+        st.mintPromise = this.mint(userKey).finally(() => {
+            st.mintPromise = null;
+        });
+        const fresh = await st.mintPromise;
+        st.runtimeKey = fresh;
+        return fresh.key;
+    }
+    invalidate(userKey) {
+        const st = this.state(userKey);
+        st.runtimeKey = null;
+        st.tools = [];
+    }
+    getToolGrants(userKey) {
+        return this.state(userKey).tools;
+    }
+    getKeyLimitUsd(userKey) {
+        return this.state(userKey).runtimeKey?.limitUsd ?? null;
+    }
+    getHandle(userKey) {
+        const st = this.state(userKey);
+        const k = st.runtimeKey;
+        if (k === null)
+            return null;
+        return {
+            recordId: k.recordId,
+            limitUsd: k.limitUsd,
+            costUsd: k.costUsd,
+            expiresAt: new Date(k.expiresAt).toISOString(),
+            activitySessionId: st.activitySessionId,
+            tools: st.tools.map((g) => ({ id: g.id, name: g.name })),
+        };
+    }
+    findByRecordId(recordId) {
+        for (const [userKey, st] of this.accounts) {
+            if (st.runtimeKey?.recordId === recordId)
+                return { userKey };
+        }
+        return null;
+    }
+    getActivitySessionId(userKey) {
+        return this.state(userKey).activitySessionId;
+    }
+    async balance() {
+        const res = await this.opts.fetchImpl(this.url("/balance"), {
+            method: "GET",
+            headers: this.headers(),
+        });
+        if (!res.ok) {
+            const body = (await res.json().catch(() => ({})));
+            throw new FantasticoError(body.message ?? `Saldo non disponibile (${res.status})`, body.type ?? "BALANCE_FAILED", res.status);
+        }
+        return (await res.json());
+    }
+    async reserveBudget(userKey, usedUsd, requestUsd) {
+        const res = await this.opts.fetchImpl(`${this.opts.baseUrl}/runtime/budget`, {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({ userKey, used: usedUsd, request: requestUsd }),
+        });
+        if (!res.ok) {
+            const body = (await res.json().catch(() => ({})));
+            throw new FantasticoError(body.message ?? `Budget negato (${res.status})`, body.type ?? "BUDGET_DENIED", res.status);
+        }
+        const data = (await res.json());
+        return data;
+    }
+    async getTools(userKey) {
+        const grants = this.getToolGrants(userKey);
+        if (grants.length === 0)
+            return [];
+        const configs = await Promise.all(grants.map((g) => this.describeTool(g)));
+        return configs.filter((c) => c !== null);
+    }
+    async describeTool(grant) {
+        const cacheKey = `${grant.id}@${grant.schemaVersion ?? "?"}`;
+        const cached = grant.schemaVersion === null ? undefined : this.schemas.get(cacheKey);
+        let tools = cached;
+        if (tools === undefined) {
+            try {
+                const res = await this.opts.fetchImpl(resolveToolEndpoint(grant.endpoint, this.opts.toolOriginMap), {
+                    method: "GET",
+                    headers: { Authorization: `Bearer ${grant.token}` },
+                });
+                if (!res.ok)
+                    return null;
+                const body = (await res.json().catch(() => ({})));
+                if (body.schema === undefined)
+                    return null;
+                const digest = await schemaDigest(body.schema);
+                if (digest === null || grant.schemaHash === null || digest !== grant.schemaHash) {
+                    return null;
+                }
+                tools = body.schema.functions ?? [];
+                if (grant.schemaVersion !== null)
+                    this.schemas.set(cacheKey, tools);
+            }
+            catch {
+                return null;
+            }
+        }
+        if (tools.length === 0)
+            return null;
+        return {
+            name: grant.id,
+            url: `${resolveToolEndpoint(grant.endpoint, this.opts.toolOriginMap)}/execute`,
+            authToken: grant.token,
+            allowedTools: tools.map((t) => t.function.name),
+            toolDefinitions: tools.map(wireTool),
+        };
+    }
+    async outputPricePerToken(model) {
+        const now = Date.now();
+        if (this.models === null || now - this.models.at > MODELS_TTL_MS) {
+            try {
+                const res = await this.opts.fetchImpl(this.url("/models"), {
+                    method: "GET",
+                    headers: this.headers(),
+                });
+                if (!res.ok)
+                    return null;
+                const body = (await res.json());
+                const byId = new Map();
+                for (const m of body.models ?? []) {
+                    const price = Number(m.pricing?.completion);
+                    if (m.id !== undefined && Number.isFinite(price) && price > 0)
+                        byId.set(m.id, price);
+                }
+                this.models = { at: now, byId };
+            }
+            catch {
+                return null;
+            }
+        }
+        return this.models.byId.get(model) ?? null;
+    }
+    async mint(userKey) {
+        const st = this.state(userKey);
+        const sent = st.activitySessionId;
+        const named = this.surface === "runtime" && userKey !== undefined ? { userKey } : {};
+        const bought = this.opts.product === undefined ? {} : { product: this.opts.product };
+        const res = await this.opts.fetchImpl(this.url("/key"), {
+            method: "POST",
+            headers: this.headers(true),
+            body: JSON.stringify({
+                ...named,
+                ...bought,
+                ...(sent === null ? {} : { activitySessionId: sent }),
+            }),
+        });
+        if (!res.ok) {
+            const body = (await res.json().catch(() => ({})));
+            throw new FantasticoError(body.message ?? `Conio runtime key fallito (${res.status})`, body.type ?? "MINT_FAILED", res.status);
+        }
+        const data = (await res.json());
+        if (data.activitySessionId !== undefined) {
+            if (sent !== null && sent !== data.activitySessionId) {
+                console.warn(`[fantastico] sessione di attività sostituita dal ledger: ${sent} -> ` +
+                    `${data.activitySessionId}. La spesa precedente resta raggruppata sotto la vecchia.`);
+            }
+            st.activitySessionId = data.activitySessionId;
+        }
+        const limitUsd = data.limit == null ? null : Number(data.limit);
+        st.tools = (data.tools ?? [])
+            .filter((svc) => typeof svc.endpoint === "string")
+            .map((svc) => ({
+            id: svc.id,
+            name: svc.name ?? svc.id,
+            endpoint: svc.endpoint,
+            schemaVersion: svc.schemaVersion ?? null,
+            schemaHash: typeof svc.schemaHash === "string" ? svc.schemaHash : null,
+            token: svc.token,
+        }));
+        return {
+            key: data.runtimeKey,
+            expiresAt: new Date(data.expiresAt).getTime(),
+            recordId: data.recordId,
+            limitUsd: limitUsd !== null && Number.isFinite(limitUsd) ? limitUsd : null,
+            costUsd: data.cost == null ? null : String(data.cost),
+        };
+    }
+}

package/dist/backoff.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Quanto insistere su un errore che passa da solo (429, provider sovraccarico).
+ *
+ * `false` la spegne del tutto. I default sono pensati per una chiamata dentro una richiesta HTTP:
+ * due ritentativi, qualche secondo in tutto, mai più di dieci per singola attesa.
+ */
+export interface RetryOptions {
+    /** Quanti **ritentativi** dopo il primo tentativo. `0` equivale a spegnerla. Default 2. */
+    attempts?: number;
+    /** Base dell'esponenziale quando il provider non dice `Retry-After`. Default 500 ms. */
+    baseDelayMs?: number;
+    /** Tetto su ogni singola attesa, **compreso** un `Retry-After` esagerato. Default 10 s. */
+    maxDelayMs?: number;
+}
+export interface RetryConfig extends RetryOptions {
+    /**
+     * L'istante oltre il quale non si dorme più.
+     *
+     * Serve perché l'orchestratore controlla il proprio `budgetMs` solo **in cima a ogni turno**
+     * (`orchestrator.ts`): un'attesa dentro la chiamata HTTP gli è invisibile, quindi senza questo
+     * limite un backoff potrebbe sforare il budget del chiamante e far emergere un `TIMEOUT` al
+     * turno successivo — al posto della causa vera, che era un rate limit. Se non c'è tempo per
+     * l'attesa, l'errore del provider si propaga subito: dire "429" è più utile che dire "timeout".
+     */
+    deadlineAt?: number;
+    /** Iniettabili nei test: un'attesa vera renderebbe la suite lenta e il jitter non asseribile. */
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+}
+/**
+ * L'attesa prima del ritentativo numero `attempt` (1-based).
+ *
+ * Ordine delle preferenze: **`Retry-After` se c'è** — il provider ha detto il numero, e indovinarne
+ * un altro dopo essere stati informati è l'unica opzione chiaramente sbagliata — altrimenti un
+ * esponenziale `base * 2^(attempt-1)`. In entrambi i casi si applica il tetto, e in entrambi il
+ * **jitter**, che non è un ornamento: molti client diversi condividono lo stesso
+ * account presso il provider, quindi prendono il 429 nello stesso istante. Senza jitter ritenterebbero
+ * all'unisono e se lo ri-procurerebbero — la ritentata diventerebbe la causa.
+ */
+export declare function delayFor(err: unknown, attempt: number, cfg: RetryConfig): number;
+/**
+ * Esegue `run`, e lo rifà se fallisce con un errore transitorio.
+ *
+ * Sta **attorno alla singola richiesta HTTP**, non attorno all'orchestrazione: lì un ritentativo
+ * rigioverebbe la conversazione da capo, ripagando i turni già fatti e rieseguendo i loro tool
+ * (vedi la nota su `RemintingLlmClient` in `client.ts`). Qui invece non c'è niente da rieseguire.
+ */
+export declare function withTransientRetry<T>(run: () => Promise<T>, cfg: RetryConfig | false): Promise<T>;

package/dist/backoff.js

@@ -0,0 +1,31 @@
+import { ProviderError, isTransient } from "./provider-error.js";
+const DEFAULTS = { attempts: 2, baseDelayMs: 500, maxDelayMs: 10_000 };
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function delayFor(err, attempt, cfg) {
+    const base = cfg.baseDelayMs ?? DEFAULTS.baseDelayMs;
+    const max = cfg.maxDelayMs ?? DEFAULTS.maxDelayMs;
+    const random = cfg.random ?? Math.random;
+    const stated = err instanceof ProviderError ? err.retryAfterMs : null;
+    const wanted = stated ?? base * 2 ** (attempt - 1);
+    const capped = Math.min(wanted, max);
+    return Math.round(capped * (0.5 + random() * 0.5));
+}
+export async function withTransientRetry(run, cfg) {
+    if (cfg === false)
+        return run();
+    const attempts = cfg.attempts ?? DEFAULTS.attempts;
+    const sleep = cfg.sleep ?? wait;
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await run();
+        }
+        catch (err) {
+            if (attempt >= attempts || !isTransient(err))
+                throw err;
+            const delay = delayFor(err, attempt + 1, cfg);
+            if (cfg.deadlineAt !== undefined && Date.now() + delay > cfg.deadlineAt)
+                throw err;
+            await sleep(delay);
+        }
+    }
+}

package/dist/browser-actions.d.ts

@@ -0,0 +1,28 @@
+import type { ClientAction } from "./types.js";
+export type ClientActionHandler = (args: Record<string, unknown>) => unknown | Promise<unknown>;
+/**
+ * Esecutore lato client delle azioni consegnate dal server — `ChatCompletion.clientActions`
+ * (fire-and-forget) o l'esito da rimandare a `resume()` per un `PendingToolCall` con
+ * `reason: "client_action"`. Nessuna dipendenza Node: niente fetch, niente chiavi — gira nel
+ * browser, si limita a mappare nome→funzione reale registrata dall'integratore, simmetrico
+ * a `{ definition, execute }` lato server ma senza mai vedere una project key.
+ */
+export declare class FantasticoActions {
+    private readonly handlers;
+    constructor(initial?: Record<string, ClientActionHandler>);
+    on(name: string, handler: ClientActionHandler): void;
+    /** Esegue una singola azione. Non lancia mai: un handler mancante o che fallisce diventa
+     *  un esito d'errore, non un'eccezione che spacca il resto del batch. */
+    run(action: ClientAction): Promise<{
+        id: string;
+        result?: unknown;
+        error?: string;
+    }>;
+    /** Esegue un elenco di azioni (tipicamente `ChatCompletion.clientActions`) in parallelo,
+     *  isolando i fallimenti gli uni dagli altri. */
+    runAll(actions: ClientAction[]): Promise<Array<{
+        id: string;
+        result?: unknown;
+        error?: string;
+    }>>;
+}

package/dist/browser-actions.js

@@ -0,0 +1,25 @@
+export class FantasticoActions {
+    handlers = new Map();
+    constructor(initial = {}) {
+        for (const [name, handler] of Object.entries(initial))
+            this.on(name, handler);
+    }
+    on(name, handler) {
+        this.handlers.set(name, handler);
+    }
+    async run(action) {
+        const handler = this.handlers.get(action.name);
+        if (!handler)
+            return { id: action.id, error: `Nessun handler registrato per "${action.name}"` };
+        try {
+            const result = await handler(action.arguments);
+            return { id: action.id, result };
+        }
+        catch (err) {
+            return { id: action.id, error: err.message ?? "Errore azione client" };
+        }
+    }
+    async runAll(actions) {
+        return Promise.all(actions.map((a) => this.run(a)));
+    }
+}