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

package/dist/raw.js

@@ -0,0 +1,72 @@
+import { providerErrorFromResponse, errorInBody, emptyCompletionError } from "./provider-error.js";
+import { withTransientRetry } from "./backoff.js";
+function hasCacheControl(messages) {
+    return messages.some((m) => Array.isArray(m.content) && m.content.some((part) => part.cache_control != null));
+}
+export async function callOpenRouterRaw(runtimeKey, params, fetchImpl, retry = {}) {
+    const pinProvider = params.pinProvider ?? hasCacheControl(params.messages);
+    const body = {
+        model: params.model,
+        messages: params.messages,
+        usage: { include: true },
+        ...(pinProvider ? { provider: { order: ["Anthropic"], allow_fallbacks: true } } : {}),
+        ...(params.tools && params.tools.length > 0 ? { tools: params.tools } : {}),
+        ...(params.tool_choice != null ? { tool_choice: params.tool_choice } : {}),
+        ...(params.max_tool_calls != null ? { max_tool_calls: params.max_tool_calls } : {}),
+        ...(params.temperature != null ? { temperature: params.temperature } : {}),
+        ...(params.max_tokens != null ? { max_tokens: params.max_tokens } : {}),
+        ...(params.reasoning != null ? { reasoning: params.reasoning } : {}),
+    };
+    return withTransientRetry(async () => {
+        const res = await fetchImpl("https://openrouter.ai/api/v1/chat/completions", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${runtimeKey}`,
+                "Content-Type": "application/json",
+                "HTTP-Referer": "https://fantastico.cc",
+                "X-Title": "FANTASTICO SDK",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw await providerErrorFromResponse(res, "OpenRouter");
+        const payload = await res.json();
+        const embedded = errorInBody(payload, "OpenRouter");
+        if (embedded)
+            throw embedded;
+        const completion = payload;
+        const choice = completion.choices?.[0];
+        const empty = emptyCompletionError({
+            model: completion.model ?? params.model,
+            finishReason: choice?.finish_reason,
+            content: choice?.message.content,
+            toolCalls: choice?.message.tool_calls,
+            maxTokens: params.max_tokens ?? null,
+            completionTokens: completion.usage?.completion_tokens ?? 0,
+            reasoningTokens: completion.usage?.completion_tokens_details?.reasoning_tokens ?? 0,
+        });
+        if (empty)
+            throw empty;
+        return completion;
+    }, retry);
+}
+export function normalizeRawUsage(usage) {
+    return {
+        prompt_tokens: usage?.prompt_tokens ?? 0,
+        completion_tokens: usage?.completion_tokens ?? 0,
+        total_tokens: usage?.total_tokens ?? 0,
+        internal_turns: 1,
+        cache_creation_tokens: usage?.prompt_tokens_details?.cache_write_tokens ?? 0,
+        cache_read_tokens: usage?.prompt_tokens_details?.cached_tokens ?? 0,
+        reasoning_tokens: usage?.completion_tokens_details?.reasoning_tokens ?? 0,
+        mcp_calls: 0,
+        cost_usd: usage?.cost ?? 0,
+    };
+}
+export function normalizeFinishReason(reason) {
+    if (reason === "length")
+        return "length";
+    if (reason === "tool_calls")
+        return "tool_calls";
+    return "stop";
+}

package/dist/schema-digest.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Il digest del documento di uno strumento, ricalcolato da chi lo riceve.
+ *
+ * **Serve a rispondere a una domanda sola**: cio che il tool mi ha appena consegnato e' cio che il
+ * control plane ha registrato? Le due cose arrivano per strade diverse — la concessione col conio,
+ * il documento dal tool — e se non coincidono o il tool e' cambiato o qualcosa in mezzo lo ha
+ * cambiato. Da qui non si distinguono, e nessuno dei due casi e' un motivo per proseguire: quel
+ * documento sta per essere messo davanti a un modello per conto di chi ci ha dato la chiave.
+ *
+ * **Canonicalizza prima di firmare, non firma i byte.** Questo lato fa `JSON.parse` e il testo
+ * originale non esiste piu'; e un tool di terze parti serializzera' a modo suo, con un altro ordine
+ * di chiavi e un'altra spaziatura. Firmare i byte renderebbe la verifica sensibile a una virgola,
+ * cioe' rumore. Gemello di `backend/src/lib/tool-schema.ts` — due copie perche' questo pacchetto
+ * non ha dipendenze, tenute oneste dallo stesso vettore di prova nei due test.
+ */
+/** JSON deterministico: chiavi ordinate, nessuno spazio. Gli array NON si ordinano. */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * SHA-256 esadecimale della forma canonica.
+ *
+ * **WebCrypto e non `node:crypto`**: questo pacchetto non importa nulla, nemmeno un builtin, ed e'
+ * una proprieta' che vale la pena non perdere per una riga di hash. `crypto.subtle` c'e' su Node 18+
+ * e nei browser. Asincrona, che qui non costa niente: si e' gia' dentro una `await`.
+ */
+export declare function schemaDigest(document: unknown): Promise<string | null>;

package/dist/schema-digest.js

@@ -0,0 +1,20 @@
+export function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+}
+export async function schemaDigest(document) {
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle === undefined)
+        return null;
+    const bytes = new TextEncoder().encode(canonicalJson(document));
+    const digest = await subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}

package/dist/speech.d.ts

@@ -0,0 +1,107 @@
+import type { OpenRouterModel } from "./types.js";
+import { type RetryConfig } from "./backoff.js";
+/**
+ * Voce sintetica (text-to-speech) sullo stesso conto e la stessa runtime key di ogni altra chiamata.
+ *
+ * OpenRouter ha un endpoint dedicato, `POST /api/v1/audio/speech`, compatibile con l'Audio Speech
+ * API di OpenAI: non passa dalla `/chat/completions` di `llm.ts`/`raw.ts`, e i suoi modelli **non
+ * compaiono nel catalogo `/models` senza filtro** — si elencano con `?output_modalities=speech`,
+ * ed è ciò che `ai.audio.speech.models()` restituisce, voci comprese (`supported_voices`).
+ *
+ * **Verificato sul campo (2026-10-17)**, con una runtime key a tetto di 5 centesimi:
+ *
+ * - **la spesa finisce nell'`usage` della chiave** come quella di una chat, quindi il ledger la
+ *   liquida sull'hold del conio senza una riga di codice in più — è per questo che qui non c'è
+ *   nessuna dichiarazione di consumo;
+ * - **il prezzo è per carattere di testo** dove il catalogo ha `pricing.completion: "0"` (Mistral
+ *   e ElevenLabs: 70 caratteri × prezzo = costo esatto), **per token** su Gemini TTS (token di
+ *   testo in ingresso più token di audio in uscita, che dipendono dalla durata), per secondo di
+ *   audio su Seed Audio. Il catalogo non dichiara l'unità: la si legge da quale dei due prezzi è
+ *   diverso da zero;
+ * - **il formato dipende dal modello e il catalogo non lo dice**: HeyGen e Gemini rispondono solo
+ *   `pcm` (400 con il messaggio esplicito se si chiede `mp3`), Mistral ed ElevenLabs servono
+ *   `mp3`. Per questo `response_format` omesso **non si scrive**: vale il default del provider
+ *   (`pcm`), e chi vuole `mp3` lo chiede sapendo che il modello lo serve;
+ * - la risposta **non porta il costo**: solo `X-Generation-Id`, e `GET /generation?id=` risponde
+ *   dopo circa cinque secondi. Leggerlo dentro la chiamata la rallenterebbe di quel tanto per un
+ *   numero che il ledger misura comunque; quindi il risultato porta l'id e non un costo stimato.
+ *   Un `cost_usd` inventato qui sarebbe la stima lato client che il resto dell'SDK non fa mai.
+ */
+/** Un turno di un input a più voci (solo Gemini TTS e i Fish Audio non-S1 lo accettano). */
+export interface SpeechTurn {
+    text: string;
+    /** Eredita `voice` della richiesta se omessa. */
+    voice?: string;
+    /** Eredita `instructions` della richiesta se omesse. */
+    instructions?: string;
+}
+export interface SpeechCreateParams {
+    /**
+     * Un modello con `output_modalities: ["speech"]` — da `ai.audio.speech.models()`. Senza default,
+     * di proposito: le voci sono del modello, quindi scegliere una voce è già scegliere un modello,
+     * e un default che un giorno sparisse dal catalogo fallirebbe in silenzio per tutti.
+     */
+    model: string;
+    /** Il testo da leggere, o una sequenza di turni con la loro voce. */
+    input: string | SpeechTurn[];
+    /** Una delle `supported_voices` del modello. Obbligatoria per quasi tutti: omessa, il
+     *  provider risponde 400 a meno che non documenti un default. */
+    voice?: string;
+    /** Tono o stile ("warm and friendly"). Letto da OpenAI, Gemini e Fish Audio, ignorato altrove. */
+    instructions?: string;
+    /**
+     * `mp3` o `pcm`. **Omesso non si scrive**, e vale il default del provider (`pcm`): quale dei
+     * due un modello serva non è nel catalogo, e un default `mp3` scritto qui romperebbe HeyGen e
+     * Gemini con un 400. Il `contentType` della risposta dice cosa è arrivato — per `pcm` anche
+     * frequenza e canali (`audio/pcm;rate=24000;channels=1`).
+     */
+    response_format?: "mp3" | "pcm";
+    /** Velocità, `1.0` di default. Alcuni modelli la ignorano, altri rifiutano un valore non standard. */
+    speed?: number;
+    /** Riferimenti audio/immagine per clonare o disegnare una voce: pass-through verso il provider. */
+    input_references?: Array<Record<string, unknown>>;
+    /** `zdr: true` instrada solo verso endpoint Zero Data Retention. */
+    provider?: {
+        zdr?: boolean;
+        [key: string]: unknown;
+    };
+    /** Il tenant finale, come `user` in `chat.completions.create()`: la spesa va sul suo conto. */
+    user?: string;
+}
+export interface SpeechResult {
+    /** I byte dell'audio, nel formato che `contentType` dichiara. */
+    audio: Uint8Array;
+    /** `audio/mpeg` per mp3; per pcm porta anche frequenza e canali. */
+    contentType: string;
+    /** Il modello richiesto: il provider non lo ripete nella risposta. */
+    model: string;
+    /**
+     * L'id della generazione presso il provider (`X-Generation-Id`), per i log. Non è il costo:
+     * quello lo misura il ledger dall'usage della chiave e compare nell'estratto conto alla
+     * liquidazione, come per una chat.
+     */
+    generationId: string | null;
+}
+/**
+ * Un modello text-to-speech del catalogo (`ai.audio.speech.models()`): la stessa forma di
+ * `OpenRouterModel`, con `supported_voices` dove il modello le dichiara.
+ *
+ * **Come leggere il prezzo.** `pricing.completion: "0"` → `pricing.prompt` è USD per **carattere**
+ * di testo (il caso di quasi tutti). Entrambi diversi da zero → per token, in ingresso e in uscita
+ * (Gemini TTS). `pricing.prompt: "0"` con `completion` > 0 → per **secondo** di audio generato
+ * (Seed Audio). Alcuni modelli non dichiarano voci: Fish Audio le prende da `input_references`.
+ */
+export type SpeechModel = OpenRouterModel & {
+    supported_voices?: string[];
+};
+/**
+ * Una singola chiamata all'endpoint TTS — stessa forma di `callOpenRouterRaw` e
+ * `callOpenRouterDecision`: nessuna orchestrazione, ritentativo sui soli errori transitori
+ * (`backoff.ts`), errore tipizzato (`provider-error.ts`) su cui `client.ts` decide se ri-coniare.
+ *
+ * **La risposta è audio, l'errore è JSON.** Lo stato HTTP decide: un non-2xx porta l'envelope
+ * `{ error: { code, message, metadata } }` di sempre — quindi 401/402 fanno ri-coniare e 429/503
+ * si riprovano come per una chat. Un 200 che porta JSON al posto dell'audio è un errore nel corpo
+ * (`errorInBody`), e un 200 vuoto è un errore e basta: nessuno dei due è una voce.
+ */
+export declare function callOpenRouterSpeech(runtimeKey: string, params: SpeechCreateParams, fetchImpl: typeof fetch, retry?: RetryConfig | false): Promise<SpeechResult>;

package/dist/speech.js

@@ -0,0 +1,48 @@
+import { FantasticoError } from "./types.js";
+import { providerErrorFromResponse, errorInBody } from "./provider-error.js";
+import { withTransientRetry } from "./backoff.js";
+const SPEECH_URL = "https://openrouter.ai/api/v1/audio/speech";
+export async function callOpenRouterSpeech(runtimeKey, params, fetchImpl, retry = {}) {
+    const body = {
+        model: params.model,
+        input: params.input,
+        ...(params.voice != null ? { voice: params.voice } : {}),
+        ...(params.instructions != null ? { instructions: params.instructions } : {}),
+        ...(params.response_format != null ? { response_format: params.response_format } : {}),
+        ...(params.speed != null ? { speed: params.speed } : {}),
+        ...(params.input_references != null ? { input_references: params.input_references } : {}),
+        ...(params.provider != null ? { provider: params.provider } : {}),
+    };
+    return withTransientRetry(async () => {
+        const res = await fetchImpl(SPEECH_URL, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${runtimeKey}`,
+                "Content-Type": "application/json",
+                "HTTP-Referer": "https://fantastico.cc",
+                "X-Title": "FANTASTICO SDK",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            throw await providerErrorFromResponse(res, "OpenRouter Speech");
+        const contentType = res.headers.get("content-type") ?? "";
+        if (/json/i.test(contentType)) {
+            const payload = await res.json().catch(() => null);
+            const embedded = errorInBody(payload, "OpenRouter Speech");
+            if (embedded)
+                throw embedded;
+            throw new FantasticoError(`${params.model}: il provider ha risposto JSON al posto dell'audio`, "EMPTY_AUDIO", 502);
+        }
+        const audio = new Uint8Array(await res.arrayBuffer());
+        if (audio.byteLength === 0) {
+            throw new FantasticoError(`${params.model}: il provider ha risposto senza audio`, "EMPTY_AUDIO", 502);
+        }
+        return {
+            audio,
+            contentType,
+            model: params.model,
+            generationId: res.headers.get("x-generation-id"),
+        };
+    }, retry);
+}

package/dist/surface.d.ts

@@ -0,0 +1,35 @@
+import { FantasticoError } from "./types.js";
+/**
+ * Le due superfici del control plane, e la credenziale che le sceglie.
+ *
+ * **Non è una modalità del client: è una proprietà della chiave.** `/api/runtime/*` vuole una
+ * project key e legge il conto dal corpo della richiesta; `/api/edge/*` vuole una chiave di conto
+ * e non ha **nessun campo** con cui nominarne uno — l'identità è quella della credenziale, punto
+ *. Sono due contratti diversi per due assunzioni di fiducia diverse, e il
+ * prefisso della chiave dice già quale dei due si sta usando.
+ *
+ * Quindi qui non si sceglie niente e non si configura niente: si **legge** la chiave. Un'opzione
+ * con cui dichiarare la superficie sarebbe un secondo posto in cui dire la stessa cosa, cioè un
+ * posto in cui dirla diversamente — e il sintomo sarebbe un 401 su ogni chiamata, senza che
+ * niente indichi quale delle due dichiarazioni fosse quella sbagliata.
+ */
+export type Surface = "runtime" | "edge";
+/**
+ * La superficie di una chiave, dal suo prefisso.
+ *
+ * È lo stesso controllo che il backend fa prima di guardare il resto della stringa
+ * (`authorizeProjectKey` / `authorizeContoKey` in `api.service.ts`), quindi non si indovina
+ * nulla: una chiave che non comincia in uno dei due modi non sarebbe accettata da nessuna delle
+ * due superfici, e fermarsi alla costruzione risparmia un 401 su ogni chiamata successiva.
+ */
+export declare function surfaceOf(apiKey: string): Surface;
+/**
+ * Il rifiuto per un'operazione che **su questa superficie non esiste**.
+ *
+ * Le due non offrono le stesse cose, e fingere di sì costerebbe più di quanto renda: l'anagrafica
+ * dei conti è di un progetto e una chiave di conto ne vale uno solo; il saldo del proprio conto è
+ * una domanda che solo chi ne ha uno può porre. Detto con un errore parlante, chi integra lo
+ * scopre alla prima chiamata; simulato, lo scoprirebbe da un elenco vuoto o da un numero preso da
+ * qualcun altro.
+ */
+export declare function unsupportedOnSurface(what: string, needs: Surface): FantasticoError;

package/dist/surface.js

@@ -0,0 +1,13 @@
+import { FantasticoError } from "./types.js";
+export function surfaceOf(apiKey) {
+    if (apiKey.startsWith("sk-fant-"))
+        return "runtime";
+    if (apiKey.startsWith("ck-fant-"))
+        return "edge";
+    throw new FantasticoError('Credenziale non riconosciuta: una project key comincia per "sk-fant-", '
+        + 'una chiave di conto per "ck-fant-"', "UNKNOWN_CREDENTIAL", 400);
+}
+export function unsupportedOnSurface(what, needs) {
+    const credential = needs === "runtime" ? "project key `sk-fant-…`" : "chiave di conto `ck-fant-…`";
+    return new FantasticoError(`${what}: serve una ${credential}, cioè la superficie /api/${needs}`, "SURFACE_UNSUPPORTED", 400);
+}

package/dist/tool-definition.d.ts

@@ -0,0 +1,22 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * Un tool ridotto a **cio che l'array `tools` di una richiesta al provider ammette**:
+ * `{type, function:{name, description, parameters}}`, ricostruito campo per campo.
+ *
+ * **Perche' qui e non solo dal lato di chi scrive il manifest.** Questo pacchetto e' l'unico posto
+ * che compone davvero la richiesta al provider, e cio' che ci mette dentro arriva da `JSON.parse`
+ * della risposta di un tool — cioe' da un host che non e' il nostro. Un tool di terze parti puo'
+ * annotare le proprie funzioni come vuole: nel suo documento quei campi sono legittimi, il digest
+ * torna e la verifica passa. Quello che non e' legittimo e' **inoltrarli**, perche' da li' in poi
+ * non sono piu' annotazioni di un manifest, sono un oggetto fuori contratto spedito a un endpoint
+ * di qualcun altro, che ha tutto il diritto di rifiutarlo.
+ *
+ * **Ricostruito e non ripulito**: l'insieme delle chiavi che escono e' scritto qui, invece di
+ * essere "tutto quello che c'era meno quelle a cui avevo pensato". Un campo che nessuno ha previsto
+ * non passa per il solo fatto di esistere.
+ *
+ * **Dopo la verifica, mai prima.** Quel che si firma e' il documento come il tool l'ha scritto: se
+ * si normalizzasse prima di ricalcolare il digest, la verifica direbbe che due documenti diversi
+ * sono lo stesso — che e' esattamente cio' che non deve poter dire.
+ */
+export declare function wireTool(t: ToolDefinition): ToolDefinition;

package/dist/tool-definition.js

@@ -0,0 +1,10 @@
+export function wireTool(t) {
+    return {
+        type: "function",
+        function: {
+            name: t.function.name,
+            description: t.function.description,
+            parameters: t.function.parameters,
+        },
+    };
+}

package/dist/tool-origin.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Raggiungere un tool per una strada interna invece che per il suo indirizzo pubblico.
+ *
+ * **Perché esiste.** Un tool si registra con il suo indirizzo pubblico, e chi lo chiama dalla
+ * stessa macchina (o dalla stessa rete privata) su cui gira uscirebbe su internet per rientrare,
+ * passando per proxy e CDN con i loro timeout: una chiamata lunga verrebbe tagliata a metà
+ * mentre il tool finisce il lavoro e lo addebita.
+ *
+ * Con la mappa la chiamata va diretta al processo del tool (es. `http://127.0.0.1:8080`). Cambia
+ * solo **dove** si manda la richiesta: il token resta quello della concessione e il documento del
+ * tool si verifica contro lo stesso digest, quindi una mappa sbagliata fa cadere il tool dalla
+ * sessione come un tool irraggiungibile, mai eseguire qualcos'altro al suo posto.
+ *
+ * **Solo dentro la stessa macchina o rete privata**: verso un'origine `http://` il token viaggia
+ * in chiaro, quindi una destinazione `http://` è accettata solo se è loopback o un indirizzo di
+ * rete privata, un nome senza punti (come il nome di un container) o un dominio riservato all'uso
+ * privato (`host.docker.internal`, `*.internal`, `*.local`). Verso qualunque altro host
+ * la destinazione deve essere `https://`.
+ *
+ * Forma: `{ "https://tools.example.com": "http://127.0.0.1:8080" }`, oppure la stessa cosa come
+ * stringa `pubblica=interna[,pubblica=interna…]` (la variabile `FANTASTICO_TOOL_ORIGIN_MAP`).
+ */
+export type ToolOriginMap = Record<string, string>;
+/** Legge la forma testuale. Una voce malformata è un errore: una mappa ignorata in silenzio è il
+ *  modo di scoprire mesi dopo che le chiamate passavano ancora da fuori. */
+export declare function parseToolOriginMap(text: string): ToolOriginMap;
+/** Origini confrontabili: protocollo e host minuscoli, senza barra finale né percorso. */
+export declare function normalizeToolOriginMap(map: ToolOriginMap): ToolOriginMap;
+/** L'indirizzo da usare davvero per un endpoint di tool: quello interno se la sua origine è mappata. */
+export declare function resolveToolEndpoint(endpoint: string, map: ToolOriginMap | undefined): string;
+/** La mappa dall'ambiente, se il runtime ne ha uno (Node sì, un browser no). */
+export declare function toolOriginMapFromEnv(): ToolOriginMap | undefined;

package/dist/tool-origin.js

@@ -0,0 +1,65 @@
+export function parseToolOriginMap(text) {
+    const map = {};
+    for (const entry of text.split(",").map((e) => e.trim()).filter(Boolean)) {
+        const eq = entry.indexOf("=");
+        if (eq <= 0)
+            throw new Error(`FANTASTICO_TOOL_ORIGIN_MAP: voce senza '=': '${entry}'`);
+        map[entry.slice(0, eq).trim()] = entry.slice(eq + 1).trim();
+    }
+    return normalizeToolOriginMap(map);
+}
+export function normalizeToolOriginMap(map) {
+    const out = {};
+    for (const [from, to] of Object.entries(map)) {
+        let source;
+        let target;
+        try {
+            source = new URL(from);
+            target = new URL(to);
+        }
+        catch {
+            throw new Error(`mappa delle origini dei tool: indirizzo non valido in '${from}=${to}'`);
+        }
+        if (target.protocol !== "https:" && !(target.protocol === "http:" && isLocalHost(target.hostname))) {
+            throw new Error(`mappa delle origini dei tool: '${to}' non è https:// né un indirizzo locale — ` +
+                `il token del tool viaggerebbe in chiaro fuori dalla macchina`);
+        }
+        out[source.origin] = target.origin;
+    }
+    return out;
+}
+function isLocalHost(hostname) {
+    const h = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    if (h === "localhost" || h === "::1")
+        return true;
+    if ([".localhost", ".internal", ".local"].some((suffix) => h.endsWith(suffix)))
+        return true;
+    if (!h.includes(".") && !h.includes(":"))
+        return true;
+    const v4 = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (v4) {
+        const [a, b] = [Number(v4[1]), Number(v4[2])];
+        return a === 127 || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+    }
+    return /^f[cd][0-9a-f]{2}:/.test(h) || /^fe[89ab][0-9a-f]:/.test(h);
+}
+export function resolveToolEndpoint(endpoint, map) {
+    if (!map)
+        return endpoint;
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        return endpoint;
+    }
+    const target = map[url.origin];
+    if (!target)
+        return endpoint;
+    return target + endpoint.slice(url.origin.length);
+}
+export function toolOriginMapFromEnv() {
+    const env = globalThis.process?.env;
+    const text = env?.FANTASTICO_TOOL_ORIGIN_MAP;
+    return text ? parseToolOriginMap(text) : undefined;
+}