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

package/dist/llm.d.ts

@@ -0,0 +1,40 @@
+import type { ToolDefinition, ReasoningConfig } from "./types.js";
+import type { LlmClient, LlmResponse, InternalMessage } from "./orchestrator.js";
+import { type RetryConfig } from "./backoff.js";
+export interface OpenRouterClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    referer?: string;
+    title?: string;
+    fetchImpl?: typeof fetch;
+    /** Ritentativi sugli errori transitori. `false` li spegne. Vedi `backoff.ts`. */
+    retry?: RetryConfig | false;
+}
+/**
+ * Client del provider LLM — l'unico percorso di inferenza, per ogni modello. Chiede `usage: {include: true}` così la risposta
+ * porta il **costo reale in USD**, che alimenta la regolazione del budget senza stimarlo.
+ */
+export declare class OpenRouterLlmClient implements LlmClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly referer?;
+    private readonly title?;
+    private readonly fetchImpl;
+    private readonly retry;
+    constructor(opts: OpenRouterClientOptions);
+    chatCompletion(params: {
+        model: string;
+        messages: InternalMessage[];
+        tools?: ToolDefinition[];
+        temperature?: number;
+        max_tokens?: number;
+        reasoning?: ReasoningConfig;
+    }): Promise<LlmResponse>;
+}
+/** Crea il client di inferenza. Un solo percorso: il provider LLM con la runtime key del progetto. */
+export declare function createLlmClient(opts: {
+    providerApiKey: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    retry?: RetryConfig | false;
+}): LlmClient;

package/dist/llm.js

@@ -0,0 +1,74 @@
+import { providerErrorFromResponse, errorInBody, emptyCompletionError } from "./provider-error.js";
+import { withTransientRetry } from "./backoff.js";
+export class OpenRouterLlmClient {
+    baseUrl;
+    apiKey;
+    referer;
+    title;
+    fetchImpl;
+    retry;
+    constructor(opts) {
+        this.baseUrl = (opts.baseUrl ?? "https://openrouter.ai/api/v1").replace(/\/$/, "");
+        this.apiKey = opts.apiKey;
+        this.referer = opts.referer;
+        this.title = opts.title;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.retry = opts.retry ?? {};
+    }
+    async chatCompletion(params) {
+        const body = {
+            model: params.model,
+            messages: params.messages,
+            usage: { include: true },
+            ...(params.temperature != null ? { temperature: params.temperature } : {}),
+            ...(params.max_tokens != null ? { max_tokens: params.max_tokens } : {}),
+            ...(params.reasoning != null ? { reasoning: params.reasoning } : {}),
+            ...(params.tools && params.tools.length > 0 ? { tools: params.tools } : {}),
+        };
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+        };
+        if (this.referer)
+            headers["HTTP-Referer"] = this.referer;
+        if (this.title)
+            headers["X-Title"] = this.title;
+        return withTransientRetry(async () => {
+            const res = await this.fetchImpl(`${this.baseUrl}/chat/completions`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+            });
+            if (!res.ok)
+                throw await providerErrorFromResponse(res, "Provider LLM");
+            const payload = await res.json();
+            const embedded = errorInBody(payload, "Provider LLM");
+            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;
+        }, this.retry);
+    }
+}
+export function createLlmClient(opts) {
+    return new OpenRouterLlmClient({
+        apiKey: opts.providerApiKey,
+        baseUrl: opts.baseUrl,
+        referer: "https://fantastico.cc",
+        title: "FANTASTICO SDK",
+        fetchImpl: opts.fetchImpl,
+        retry: opts.retry,
+    });
+}

package/dist/local-tools.d.ts

@@ -0,0 +1,72 @@
+import type { ToolDefinition } from "./types.js";
+/**
+ * Tool locale: la dichiarazione (nome/descrizione/schema) va al modello, `execute` resta
+ * nel processo dell'integratore e non è mai visibile al modello. Riceve gli argomenti
+ * generati dal modello più il `context` fidato dell'istanza/chiamata (mai generato dal
+ * modello: mai fidarsi di un identificatore che arriva dal modello).
+ */
+export interface LocalToolDefinition<TContext = unknown> {
+    type: "function";
+    function: ToolDefinition["function"];
+    execute: (args: Record<string, unknown>, context: TContext) => unknown | Promise<unknown>;
+    /** true = non gira in batch con altri tool dello stesso turno (default: parallelo). */
+    sequential?: boolean;
+    /** true = il modello può proporlo ma non esegue finché il chiamante non conferma. */
+    requiresConfirmation?: boolean;
+    /**
+     * Frase umana da mostrare all'operatore quando `requiresConfirmation` ferma questa
+     * tool_call (es. `(args) => \`Trasferisci $${args.amount} al conto "${args.userKey}"\``).
+     * Ignorata se `requiresConfirmation` non è true. Senza, il chiamante mostra nome+argomenti
+     * grezzi — utilizzabile, ma non pensato per un umano.
+     */
+    confirmationSummary?: (args: Record<string, unknown>) => string;
+    /**
+     * Frase breve per chi guarda il turno mentre il tool gira (es. "Leggo il contratto…"),
+     * consegnata nell'evento `tool_start` (`onEvent`, `activity.ts`). Senza, il chiamante
+     * ripiega sul nome del tool.
+     */
+    activityLabel?: (args: Record<string, unknown>) => string;
+    /** Timeout esecuzione in ms (default 10_000). */
+    timeoutMs?: number;
+    /** Filtro di disponibilità per turno; false = il tool non è offerto al modello ora. */
+    available?: (context: TContext) => boolean;
+}
+/**
+ * Tool "azione client": il server non lo esegue mai. Il modello lo propone, l'orchestratore
+ * lo consegna così com'è al chiamante (frontend), che decide come compierlo — es. navigare,
+ * aprire un pannello. Simmetrico a LocalToolDefinition ma senza `execute` lato server.
+ */
+export interface ClientActionToolDefinition<TContext = unknown> {
+    type: "function";
+    function: ToolDefinition["function"];
+    clientAction: true;
+    /**
+     * true = il loop si ferma e aspetta l'esito dal client prima di proseguire.
+     * false (default) = fire-and-forget: il loop prosegue subito, l'azione viene solo
+     * raccolta e restituita nel risultato finale (es. "naviga qui", nessuna risposta attesa).
+     */
+    awaitsResult?: boolean;
+    sequential?: boolean;
+    available?: (context: TContext) => boolean;
+}
+export type RegisteredTool<TContext = unknown> = LocalToolDefinition<TContext> | ClientActionToolDefinition<TContext>;
+export declare function isClientAction<TContext>(tool: RegisteredTool<TContext>): tool is ClientActionToolDefinition<TContext>;
+/**
+ * Registro dei tool locali/azione-client di un'istanza. Non esegue mai un'azione client
+ * (non ha modo di farlo: gira nel processo dell'integratore, non nel browser) — solo
+ * `execute()` sui tool locali veri, sempre isolato (mai lancia) e mai ritentato in automatico
+ * (una funzione dell'integratore può non essere idempotente).
+ */
+export declare class LocalToolRegistry<TContext = unknown> {
+    private readonly tools;
+    constructor(initial?: RegisteredTool<TContext>[]);
+    add(tool: RegisteredTool<TContext>): void;
+    /** Un registro nuovo: questi tool più `extra`, che vince sullo stesso nome. Questo non cambia. */
+    with(extra: RegisteredTool<TContext>[]): LocalToolRegistry<TContext>;
+    get(name: string): RegisteredTool<TContext> | undefined;
+    /** Definizioni offerte al modello per QUESTO turno: filtra per `available(context)`. */
+    definitionsFor(context: TContext): ToolDefinition[];
+    /** Esegue un tool locale (mai un'azione client, mai un tool sconosciuto). Non lancia mai:
+     *  un fallimento diventa un tool_result di errore che il modello vede e su cui reagisce. */
+    execute(name: string, args: Record<string, unknown>, context: TContext): Promise<string>;
+}

package/dist/local-tools.js

@@ -0,0 +1,55 @@
+export function isClientAction(tool) {
+    return tool.clientAction === true;
+}
+const DEFAULT_TIMEOUT_MS = 10_000;
+function withTimeout(p, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`Timeout dopo ${ms}ms`)), ms);
+        p.then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }, (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+}
+export class LocalToolRegistry {
+    tools = new Map();
+    constructor(initial = []) {
+        for (const t of initial)
+            this.add(t);
+    }
+    add(tool) {
+        this.tools.set(tool.function.name, tool);
+    }
+    with(extra) {
+        return new LocalToolRegistry([...this.tools.values(), ...extra]);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    definitionsFor(context) {
+        const defs = [];
+        for (const tool of this.tools.values()) {
+            if (tool.available && !tool.available(context))
+                continue;
+            defs.push({ type: "function", function: tool.function });
+        }
+        return defs;
+    }
+    async execute(name, args, context) {
+        const tool = this.tools.get(name);
+        if (!tool || isClientAction(tool)) {
+            return JSON.stringify({ error: `Tool locale sconosciuto: ${name}` });
+        }
+        const timeoutMs = tool.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        try {
+            const result = await withTimeout(Promise.resolve(tool.execute(args, context)), timeoutMs);
+            return typeof result === "string" ? result : JSON.stringify(result ?? null);
+        }
+        catch (err) {
+            return JSON.stringify({ error: err.message ?? "Errore tool locale" });
+        }
+    }
+}

package/dist/max-tokens.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Quanti token di risposta si possono chiedere con la runtime key che si ha in mano.
+ *
+ * **Il problema che risolve.** OpenRouter accetta o rifiuta una richiesta confrontando il costo del
+ * CASO PEGGIORE — `max_tokens` moltiplicato per il prezzo in uscita del modello — con quel che resta
+ * sulla chiave, *prima* di generare qualunque cosa. Omesso, `max_tokens` vale il massimo del
+ * modello: decine di migliaia di token. Una chiave coniata su un `block` piccolo viene quindi
+ * rifiutata anche quando la risposta vera costerebbe un millesimo di dollaro — e il messaggio parla
+ * di `max_tokens`, che è l'ultimo posto in cui si va a cercare un problema di credito.
+ *
+ * È esattamente il conto che `scripts/try-inference.mjs` fa a mano da sempre. Farlo lì e non qui
+ * voleva dire che lo script funzionava e il prodotto no.
+ *
+ * **Non è un tetto imposto al chiamante.** Un `max_tokens` esplicito passa intatto: chi lo scrive sa
+ * cosa vuole, e se non entra nel credito è giusto che OpenRouter glielo dica. Questo vale solo per
+ * il caso in cui nessuno ha detto niente.
+ */
+/**
+ * `undefined` = non scrivere `max_tokens`, che è anche la risposta quando manca un dato: senza il
+ * tetto della chiave o senza il prezzo del modello non c'è niente da calcolare, e **indovinare
+ * sarebbe peggio che tacere** — un numero inventato romperebbe le chiavi capienti per riparare
+ * quelle piccole.
+ *
+ * @param keyLimitUsd  il tetto della runtime key, in USD (dal conio: `limit`)
+ * @param pricePerOutputToken  USD per token in uscita (dal catalogo: `pricing.completion`)
+ */
+export declare function affordableMaxTokens(keyLimitUsd: number | null | undefined, pricePerOutputToken: number | null | undefined): number | undefined;

package/dist/max-tokens.js

@@ -0,0 +1,16 @@
+const HEADROOM = 0.8;
+const COMFORTABLE = 8192;
+const FLOOR = 64;
+export function affordableMaxTokens(keyLimitUsd, pricePerOutputToken) {
+    if (keyLimitUsd == null || !Number.isFinite(keyLimitUsd) || keyLimitUsd <= 0)
+        return undefined;
+    if (pricePerOutputToken == null
+        || !Number.isFinite(pricePerOutputToken)
+        || pricePerOutputToken <= 0) {
+        return undefined;
+    }
+    const affordable = Math.floor((keyLimitUsd * HEADROOM) / pricePerOutputToken);
+    if (affordable >= COMFORTABLE)
+        return undefined;
+    return Math.max(FLOOR, affordable);
+}

package/dist/mcp.d.ts

@@ -0,0 +1,14 @@
+import type { McpExecutor } from "./orchestrator.js";
+export interface McpExecutorOptions {
+    timeoutMs?: number;
+    maxRetries?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Crea un McpExecutor: chiama **il tool**, al suo endpoint, col token emesso per lui.
+ *
+ * `tool.url` e `<endpoint>/execute` e `tool.authToken` e il tool token della concessione —
+ * entrambi arrivano dal conio e li compone `AuthClient.describeTool`.
+ * Payload: { tool_id, name, arguments } → risultato JSON.
+ */
+export declare function createMcpExecutor(opts?: McpExecutorOptions): McpExecutor;

package/dist/mcp.js

@@ -0,0 +1,55 @@
+function isRetriable(status, err) {
+    if (err?.name === "AbortError" || err?.name === "TimeoutError")
+        return false;
+    const code = err?.cause?.code;
+    if (code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "EAI_AGAIN")
+        return true;
+    if (status === 429 || status === 503)
+        return true;
+    return false;
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export function createMcpExecutor(opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 180_000;
+    const maxRetries = opts.maxRetries ?? 2;
+    const fetchFn = opts.fetchImpl ?? fetch;
+    return async (tool, toolName, args) => {
+        const body = JSON.stringify({ tool_id: tool.name, name: toolName, arguments: args });
+        let lastErr;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                const res = await fetchFn(tool.url, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json", Authorization: `Bearer ${tool.authToken}` },
+                    body,
+                    signal: controller.signal,
+                });
+                clearTimeout(timer);
+                if (res.ok) {
+                    const json = await res.json();
+                    return typeof json === "string" ? json : JSON.stringify(json);
+                }
+                if (!isRetriable(res.status))
+                    throw new Error(`MCP ${tool.name}/${toolName}: ${res.status}`);
+                lastErr = new Error(`MCP ${res.status}`);
+            }
+            catch (err) {
+                clearTimeout(timer);
+                lastErr = err;
+                if (lastErr.name === "AbortError") {
+                    lastErr = new Error(`MCP ${tool.name}/${toolName}: nessuna risposta entro ${Math.round(timeoutMs / 1000)} s`);
+                    throw lastErr;
+                }
+                if (!isRetriable(undefined, lastErr))
+                    throw lastErr;
+            }
+            if (attempt < maxRetries)
+                await sleep(1000 * Math.pow(2, attempt));
+        }
+        throw lastErr ?? new Error(`MCP ${tool.name}/${toolName} failed`);
+    };
+}

package/dist/orchestrator.d.ts

@@ -0,0 +1,105 @@
+import type { ToolConfig, ToolDefinition, ToolCall, ChatCompletion, PendingCompletion, ResumeDecision, ClientAction, ReasoningConfig } from "./types.js";
+import { LocalToolRegistry } from "./local-tools.js";
+import { type ChatActivityListener } from "./activity.js";
+export interface InternalMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content?: string | null;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+}
+export type { ToolCall };
+export interface LlmResponse {
+    id: string;
+    model: string;
+    choices: Array<{
+        message: {
+            role: "assistant";
+            content?: string | null;
+            tool_calls?: ToolCall[];
+        };
+        finish_reason: string;
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+        cost?: number;
+        prompt_tokens_details?: {
+            cached_tokens?: number;
+            cache_write_tokens?: number;
+        };
+        completion_tokens_details?: {
+            /** Token di ragionamento: gia' compresi in `completion_tokens`, non da sommare. */
+            reasoning_tokens?: number;
+        };
+    };
+}
+export interface LlmClient {
+    chatCompletion(params: {
+        model: string;
+        messages: InternalMessage[];
+        tools?: ToolDefinition[];
+        temperature?: number;
+        max_tokens?: number;
+        reasoning?: ReasoningConfig;
+    }): Promise<LlmResponse>;
+}
+export type McpExecutor = (tool: ToolConfig, toolName: string, args: Record<string, unknown>) => Promise<string>;
+export interface OrchestrateOptions {
+    model: string;
+    remoteTools: ToolConfig[];
+    localTools: LocalToolRegistry;
+    /** Contesto fidato per questa chiamata, passato a ogni execute() di tool locale. */
+    context: unknown;
+    mcpExecutor: McpExecutor;
+    maxTurns?: number;
+    budgetMs?: number;
+    temperature?: number;
+    maxTokens?: number;
+    /** Passato identico a ogni turno. Omesso, non finisce nel corpo. */
+    reasoning?: ReasoningConfig;
+    /** Eventi del turno mentre accadono (vedi `activity.ts`). */
+    onEvent?: ChatActivityListener;
+}
+/** Stato serializzabile della conversazione: quello che sopravvive a una pausa/resume. */
+export interface OrchestrationState {
+    conv: InternalMessage[];
+    turns: number;
+    mcpCalls: number;
+    promptTokens: number;
+    completionTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    /**
+     * Opzionale perche' `resumeOrchestration` fa un cast, non una convalida: uno stato messo in
+     * pausa da una versione che non aveva questo campo si riprende con la nuova, e sommare a
+     * `undefined` darebbe un `NaN` che si propaga fino all'usage del chiamante.
+     */
+    reasoningTokens?: number;
+    costUsd: number;
+    clientActions: ClientAction[];
+    budgetMs: number;
+    maxTurns: number;
+    model: string;
+}
+export type OrchestrateResult = ChatCompletion | PendingCompletion;
+export declare class OrchestrationError extends Error {
+    readonly code: "TIMEOUT" | "UPSTREAM_ERROR" | "INVALID_STATE";
+    constructor(message: string, code: "TIMEOUT" | "UPSTREAM_ERROR" | "INVALID_STATE");
+}
+/**
+ * Il tetto di tempo di un'orchestrazione. Esportato perché serve anche a `client.ts`, che da esso
+ * ricava la scadenza entro cui un backoff può dormire: due default scritti in due posti
+ * divergerebbero, e il sintomo sarebbe un'attesa che sfora un budget che credeva di rispettare.
+ */
+export declare const DEFAULT_BUDGET_MS = 90000;
+export declare function orchestrate(messages: InternalMessage[], llm: LlmClient, opts: OrchestrateOptions): Promise<OrchestrateResult>;
+/**
+ * Riprende un'orchestrazione fermata da `orchestrate()`/`resumeOrchestration()` con
+ * `status: "pending"`. Ogni tool_call sospesa con `reason` deve avere una decisione
+ * corrispondente in `decisions`; se manca, viene trattata come negata/fallita (mai lasciata
+ * a metà: un tool_call senza tool_result rende la conversazione malformata per l'API).
+ * Le tool_call sospese SENZA `reason` (erano solo nello stesso turno di una bloccante)
+ * vengono eseguite in automatico, ignorando eventuali decisioni passate per loro.
+ */
+export declare function resumeOrchestration(rawState: unknown, decisions: ResumeDecision[], llm: LlmClient, opts: OrchestrateOptions): Promise<OrchestrateResult>;