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

package/dist/client.js

@@ -0,0 +1,410 @@
+import { normalizeToolOriginMap, toolOriginMapFromEnv } from "./tool-origin.js";
+import { FantasticoError } from "./types.js";
+import { surfaceOf, unsupportedOnSurface } from "./surface.js";
+import { AuthClient } from "./auth.js";
+import { createLlmClient } from "./llm.js";
+import { isRemintable, providerFailure, ProviderError } from "./provider-error.js";
+import { affordableMaxTokens } from "./max-tokens.js";
+import { orchestrate, resumeOrchestration, DEFAULT_BUDGET_MS, } from "./orchestrator.js";
+import { createMcpExecutor } from "./mcp.js";
+import { callOpenRouterRaw, normalizeRawUsage, normalizeFinishReason } from "./raw.js";
+import { LocalToolRegistry } from "./local-tools.js";
+import { callOpenRouterDecision, createDecisionTool, } from "./decisions.js";
+import { callOpenRouterSpeech, } from "./speech.js";
+function upstreamOf(err) {
+    return err instanceof ProviderError ? err.upstream : null;
+}
+export class Fantastico {
+    opts;
+    auth;
+    fetchImpl;
+    mcpExecutor;
+    localTools;
+    unsettled = new Map();
+    name;
+    surface;
+    chat;
+    tools;
+    models;
+    accounts;
+    runtimeKeys;
+    decisions;
+    audio;
+    balance;
+    usage;
+    get activitySessionId() {
+        return this.auth.getActivitySessionId();
+    }
+    constructor(options) {
+        if (!options.apiKey)
+            throw new Error("apiKey è obbligatoria");
+        this.surface = surfaceOf(options.apiKey);
+        this.opts = {
+            baseUrl: "https://fantastico.cc/api",
+            defaultModel: "anthropic/claude-sonnet-5",
+            maxTurns: 8,
+            budgetMs: 90_000,
+            mcpTimeoutMs: 180_000,
+            reserveUsd: 0.1,
+            ...options,
+        };
+        this.name = this.opts.name;
+        this.fetchImpl = this.opts.fetchImpl ?? fetch;
+        const toolOrigins = this.opts.toolOriginMap ? normalizeToolOriginMap(this.opts.toolOriginMap) : toolOriginMapFromEnv();
+        this.auth = new AuthClient({
+            apiKey: this.opts.apiKey,
+            baseUrl: this.opts.baseUrl,
+            ...(this.opts.activitySessionId === undefined
+                ? {}
+                : { activitySessionId: this.opts.activitySessionId }),
+            ...(this.opts.product === undefined ? {} : { product: this.opts.product }),
+            ...(toolOrigins === undefined ? {} : { toolOriginMap: toolOrigins }),
+            fetchImpl: this.fetchImpl,
+        });
+        this.mcpExecutor = createMcpExecutor({
+            timeoutMs: this.opts.mcpTimeoutMs,
+            fetchImpl: this.fetchImpl,
+        });
+        this.localTools = new LocalToolRegistry(this.opts.tools ?? []);
+        this.chat = {
+            completions: {
+                create: (params, options) => this.createCompletion(params, options),
+                resume: (state, decisions, context, options) => this.resumeCompletion(state, decisions, context, options),
+                createRaw: (params) => this.createRawCompletion(params),
+            },
+        };
+        this.tools = {
+            list: async (user) => toolsToDefinitions(await this.remoteTools(this.tenantOf(user))),
+            enabled: async () => (await this.api("GET", `/${this.surface}/tools`)).tools,
+            execute: async (name, args, user) => {
+                const tools = await this.remoteTools(this.tenantOf(user));
+                const tool = tools.find((s) => s.allowedTools.includes(name));
+                if (!tool)
+                    throw new FantasticoError(`Tool sconosciuto: ${name}`, "UNKNOWN_TOOL", 404);
+                return this.mcpExecutor(tool, name, args);
+            },
+        };
+        this.models = {
+            list: async () => (await this.api("GET", `/${this.surface}/models`)).models,
+        };
+        const conto = (userKey, suffix = "") => `/conti/${encodeURIComponent(userKey)}${suffix}`;
+        this.accounts = {
+            create: (params) => this.conti("POST", "/conti", params),
+            list: () => this.conti("GET", "/conti"),
+            get: (userKey) => this.conti("GET", conto(userKey)),
+            update: (userKey, params) => this.conti("PATCH", conto(userKey), params),
+            upgrade: (userKey) => this.conti("POST", conto(userKey, "/upgrade"), {}),
+            keys: {
+                list: () => this.conti("GET", "/conti/keys"),
+                issue: (userKey, label) => this.conti("POST", conto(userKey, "/key"), label ? { label } : {}),
+                rotate: (userKey) => this.conti("POST", conto(userKey, "/key/rotate"), {}),
+                revoke: (userKey) => this.conti("DELETE", conto(userKey, "/key")),
+            },
+        };
+        const forConto = (userKey) => {
+            if (userKey === undefined)
+                return "";
+            if (this.surface !== "runtime") {
+                throw unsupportedOnSurface("Nominare un conto sulle proprie runtime key", "runtime");
+            }
+            return `?userKey=${encodeURIComponent(userKey)}`;
+        };
+        this.runtimeKeys = {
+            ensure: async (user) => {
+                const userKey = this.tenantOf(user);
+                await this.auth.getRuntimeKey(userKey);
+                const handle = this.auth.getHandle(userKey);
+                if (handle === null)
+                    throw new FantasticoError("Conio non riuscito", "MINT_FAILED", 402);
+                return handle;
+            },
+            current: (user) => this.auth.getHandle(this.tenantOf(user)),
+            list: async (userKey) => this.api("GET", `/${this.surface}/keys${forConto(userKey)}`),
+            revoke: async (recordId, userKey) => {
+                const result = await this.api("DELETE", `/${this.surface}/keys/${encodeURIComponent(recordId)}${forConto(userKey)}`);
+                const mine = this.auth.findByRecordId(recordId);
+                if (mine !== null)
+                    this.auth.invalidate(mine.userKey);
+                return result;
+            },
+        };
+        this.balance = async () => {
+            if (this.surface !== "edge") {
+                throw unsupportedOnSurface("Il saldo del proprio conto (con una project key i conti sono molti: `accounts.get`)", "edge");
+            }
+            return this.auth.balance();
+        };
+        this.decisions = {
+            evaluate: (params) => this.evaluateDecision(params),
+            tool: (config) => createDecisionTool(config, (params) => this.evaluateDecision(params)),
+        };
+        this.audio = {
+            speech: {
+                create: (params) => this.createSpeech(params),
+                models: async () => (await this.api("GET", `/${this.surface}/models/speech`)).models,
+            },
+        };
+        this.usage = {
+            record: async (params) => ({
+                service: params.service,
+                unit: params.unit,
+                quantity: params.quantity,
+                amount: 0,
+                deduped: false,
+            }),
+        };
+    }
+    tenantOf(user) {
+        if (user !== undefined && this.surface !== "runtime") {
+            throw unsupportedOnSurface("Attribuire la chiamata a un conto con `user` (una chiave di conto ne vale già uno solo)", "runtime");
+        }
+        return user;
+    }
+    async conti(method, path, body) {
+        if (this.surface !== "runtime") {
+            throw unsupportedOnSurface("L'anagrafica dei conti è di un progetto", "runtime");
+        }
+        return this.api(method, path, body);
+    }
+    addTool(tool) {
+        this.localTools.add(tool);
+    }
+    async defaultMaxTokens(model, explicit, userKey) {
+        if (explicit != null)
+            return explicit;
+        const limit = this.auth.getKeyLimitUsd(userKey);
+        if (limit === null)
+            return undefined;
+        return affordableMaxTokens(limit, await this.auth.outputPricePerToken(model));
+    }
+    asFantasticoError(err, msg) {
+        const named = providerFailure(err);
+        const detail = upstreamOf(err);
+        if (named !== null)
+            return new FantasticoError(msg, named.code, named.status, detail);
+        return new FantasticoError(msg || "Errore interno", "INTERNAL_ERROR", 500, detail);
+    }
+    retryConfig(deadlineAt) {
+        const opt = this.opts.retry;
+        if (opt === false)
+            return false;
+        return { ...(opt ?? {}), deadlineAt };
+    }
+    remintingLlm(model, deadlineAt, userKey) {
+        const retry = this.retryConfig(deadlineAt);
+        return {
+            chatCompletion: (params) => this.withProviderRetry(async (runtimeKey) => {
+                const llm = createLlmClient({ providerApiKey: runtimeKey, fetchImpl: this.fetchImpl, retry });
+                return llm.chatCompletion({
+                    ...params,
+                    max_tokens: await this.defaultMaxTokens(model, params.max_tokens, userKey),
+                });
+            }, userKey),
+        };
+    }
+    async withProviderRetry(run, userKey) {
+        const mintKey = async () => {
+            try {
+                return await this.auth.getRuntimeKey(userKey);
+            }
+            catch (err) {
+                if (err instanceof FantasticoError)
+                    throw err;
+                throw new FantasticoError(err.message, "MINT_FAILED", 402);
+            }
+        };
+        const runtimeKey = await mintKey();
+        try {
+            return await run(runtimeKey);
+        }
+        catch (err) {
+            if (err instanceof FantasticoError)
+                throw err;
+            const msg = err.message ?? "";
+            if (!isRemintable(err))
+                throw this.asFantasticoError(err, msg);
+            this.auth.invalidate(userKey);
+            const freshKey = await mintKey();
+            try {
+                return await run(freshKey);
+            }
+            catch (second) {
+                const named = providerFailure(second);
+                if (named !== null && !isRemintable(second)) {
+                    throw new FantasticoError(second.message, named.code, named.status, upstreamOf(second));
+                }
+                throw new FantasticoError("Errore nella comunicazione con il provider LLM", "LLM_PROVIDER_ERROR", 502, upstreamOf(second));
+            }
+        }
+    }
+    async createCompletion(params, options) {
+        const model = params.model ?? this.opts.defaultModel;
+        const userKey = this.tenantOf(params.user);
+        if (userKey) {
+            const used = this.unsettled.get(userKey) ?? 0;
+            await this.auth.reserveBudget(userKey, used, this.opts.reserveUsd);
+            this.unsettled.set(userKey, 0);
+        }
+        const granted = await this.remoteTools(userKey);
+        const only = params.marketplaceTools;
+        const remoteTools = only === undefined ? granted : granted.filter((t) => only.includes(t.name));
+        const messages = params.messages.map((m) => ({ role: m.role, content: m.content }));
+        if (this.opts.defaultSystemPrompt && messages[0]?.role !== "system") {
+            messages.unshift({ role: "system", content: this.opts.defaultSystemPrompt });
+        }
+        const context = params.context ?? this.opts.context;
+        const budgetMs = this.opts.budgetMs ?? DEFAULT_BUDGET_MS;
+        const result = await orchestrate(messages, this.remintingLlm(model, Date.now() + budgetMs, userKey), {
+            model,
+            remoteTools,
+            localTools: options?.localTools?.length ? this.localTools.with(options.localTools) : this.localTools,
+            context,
+            mcpExecutor: this.mcpExecutor,
+            maxTurns: this.opts.maxTurns,
+            budgetMs,
+            temperature: params.temperature,
+            reasoning: params.reasoning ?? this.opts.reasoning,
+            maxTokens: params.max_tokens,
+            onEvent: options?.onEvent,
+        });
+        if (userKey && result.status === "done") {
+            this.unsettled.set(userKey, (this.unsettled.get(userKey) ?? 0) + result.usage.cost_usd);
+        }
+        return stampTenant(result, userKey);
+    }
+    async remoteTools(userKey) {
+        try {
+            await this.auth.getRuntimeKey(userKey);
+        }
+        catch {
+        }
+        try {
+            return await this.auth.getTools(userKey);
+        }
+        catch {
+            return [];
+        }
+    }
+    async resumeCompletion(rawState, decisions, context, options) {
+        const model = rawState?.model ?? this.opts.defaultModel;
+        const userKey = this.tenantOf(tenantFromState(rawState));
+        const remoteTools = await this.remoteTools(userKey);
+        const budgetMs = this.opts.budgetMs ?? DEFAULT_BUDGET_MS;
+        const result = await resumeOrchestration(rawState, decisions, this.remintingLlm(model, Date.now() + budgetMs, userKey), {
+            model,
+            remoteTools,
+            localTools: options?.localTools?.length ? this.localTools.with(options.localTools) : this.localTools,
+            context: context ?? this.opts.context,
+            mcpExecutor: this.mcpExecutor,
+            maxTurns: this.opts.maxTurns,
+            budgetMs,
+            onEvent: options?.onEvent,
+        });
+        return stampTenant(result, userKey);
+    }
+    async createRawCompletion(params) {
+        const model = params.model ?? this.opts.defaultModel;
+        const userKey = this.tenantOf(params.user);
+        if (userKey) {
+            const used = this.unsettled.get(userKey) ?? 0;
+            await this.auth.reserveBudget(userKey, used, this.opts.reserveUsd);
+            this.unsettled.set(userKey, 0);
+        }
+        const deadlineAt = Date.now() + (this.opts.budgetMs ?? DEFAULT_BUDGET_MS);
+        const raw = await this.withProviderRetry(async (runtimeKey) => callOpenRouterRaw(runtimeKey, {
+            ...params,
+            model,
+            max_tokens: await this.defaultMaxTokens(model, params.max_tokens, userKey),
+            reasoning: params.reasoning ?? this.opts.reasoning,
+        }, this.fetchImpl, this.retryConfig(deadlineAt)), userKey);
+        const usage = normalizeRawUsage(raw.usage);
+        if (userKey) {
+            this.unsettled.set(userKey, (this.unsettled.get(userKey) ?? 0) + usage.cost_usd);
+        }
+        const choice = raw.choices[0];
+        return {
+            id: raw.id,
+            model: raw.model,
+            choices: [{
+                    index: 0,
+                    message: choice?.message ?? { role: "assistant", content: "" },
+                    finish_reason: normalizeFinishReason(choice?.finish_reason),
+                }],
+            usage,
+        };
+    }
+    async evaluateDecision(params) {
+        const userKey = this.tenantOf(params.user);
+        if (userKey) {
+            const used = this.unsettled.get(userKey) ?? 0;
+            await this.auth.reserveBudget(userKey, used, this.opts.reserveUsd);
+            this.unsettled.set(userKey, 0);
+        }
+        const deadlineAt = Date.now() + (this.opts.budgetMs ?? DEFAULT_BUDGET_MS);
+        const result = await this.withProviderRetry((runtimeKey) => callOpenRouterDecision(runtimeKey, params, this.fetchImpl, this.retryConfig(deadlineAt)), userKey);
+        if (userKey) {
+            this.unsettled.set(userKey, (this.unsettled.get(userKey) ?? 0) + result.usage.cost_usd);
+        }
+        return result;
+    }
+    async createSpeech(params) {
+        const userKey = this.tenantOf(params.user);
+        if (userKey) {
+            const used = this.unsettled.get(userKey) ?? 0;
+            await this.auth.reserveBudget(userKey, used, this.opts.reserveUsd);
+            this.unsettled.set(userKey, 0);
+        }
+        const deadlineAt = Date.now() + (this.opts.budgetMs ?? DEFAULT_BUDGET_MS);
+        return this.withProviderRetry((runtimeKey) => callOpenRouterSpeech(runtimeKey, params, this.fetchImpl, this.retryConfig(deadlineAt)), userKey);
+    }
+    async api(method, path, body) {
+        const res = await this.fetchImpl(`${this.opts.baseUrl}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.opts.apiKey}`,
+                ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        if (!res.ok) {
+            const err = (await res.json().catch(() => ({})));
+            throw new FantasticoError(err.message ?? `${method} ${path} fallita (${res.status})`, err.type ?? "REQUEST_FAILED", res.status);
+        }
+        return (await res.json());
+    }
+    async flushBudget(userKey) {
+        const used = this.unsettled.get(userKey) ?? 0;
+        if (used <= 0)
+            return;
+        await this.auth.reserveBudget(userKey, used, 0);
+        this.unsettled.set(userKey, 0);
+    }
+}
+const TENANT_ON_STATE = "__fantasticoUser";
+function tenantFromState(rawState) {
+    const user = rawState?.[TENANT_ON_STATE];
+    return typeof user === "string" && user.length > 0 ? user : undefined;
+}
+function stampTenant(result, userKey) {
+    if (userKey === undefined || result.status !== "pending")
+        return result;
+    const state = result.state;
+    if (state !== null && typeof state === "object") {
+        state[TENANT_ON_STATE] = userKey;
+    }
+    return result;
+}
+function toolsToDefinitions(tools) {
+    const defs = [];
+    for (const svc of tools) {
+        if (svc.toolDefinitions) {
+            defs.push(...svc.toolDefinitions);
+        }
+        else {
+            for (const name of svc.allowedTools) {
+                defs.push({ type: "function", function: { name, description: `Tool ${svc.name}`, parameters: { type: "object", properties: {} } } });
+            }
+        }
+    }
+    return defs;
+}

package/dist/decisions.d.ts

@@ -0,0 +1,149 @@
+import type { LocalToolDefinition } from "./local-tools.js";
+import { type RetryConfig } from "./backoff.js";
+/**
+ * Modelli "System One" (Jev di TypeSafe e affini, in alpha su OpenRouter a metà settembre 2026):
+ * non generano testo, restituiscono una **decisione tipizzata con probabilità** a partire da uno
+ * stato applicativo. Su OpenRouter non passano dalla `/chat/completions` che usa il resto
+ * dell'SDK (`llm.ts`, `raw.ts`): hanno un endpoint dedicato — `POST /api/alpha/decisions` — con un
+ * corpo diverso (`state` + `questions`, non `messages`) e non compaiono nel catalogo modelli
+ * standard (`ai.models.list()`). Questo file è il trasporto verso quell'endpoint; l'integrazione
+ * nel loop di tool-use di un LLM classico è `createDecisionTool` più sotto.
+ *
+ * **Verificato sul campo (2026-09-21, 0.15.1).** La 0.15.0 nasceva dalla documentazione pubblica e
+ * aveva la forma sbagliata: `bool` invece di `noul`, criteri di `choice` come array invece che come
+ * mappa, e una risposta `{ value, probability }` che l'endpoint non manda mai — `normalize…`
+ * scartava i campi veri e restituiva risposte vuote. Ora tipi e normalizzazione seguono le risposte
+ * reali di `typesafe/jev-1.13`. Resta un endpoint alpha: la forma può cambiare senza preavviso, e
+ * una risposta di tipo sconosciuto passa com'è invece di essere scartata.
+ *
+ * Id modello: `typesafe/jev-1.13` (versione fissata) o l'alias mobile `~typesafe/jev-latest`, con
+ * la tilde — `typesafe/jev-latest` non esiste.
+ */
+/**
+ * Una domanda. `type` è un'unione CHIUSA, e di proposito: la 0.15.0 la teneva aperta e per questo
+ * nessun compilatore poteva accorgersi che `bool` non esiste (l'endpoint risponde 400).
+ *
+ * - `noul` — sì/no: la risposta è la probabilità che sia SÌ. I criteri sono opzionali.
+ * - `choice` — una scelta fra etichette. I criteri sono OBBLIGATORI, come mappa etichetta → descrizione.
+ * - `score` — una posizione su una scala ordinata. I criteri sono un array, dal livello più basso.
+ */
+export type DecisionQuestion = {
+    type: "noul";
+    instructions: string;
+    criteria?: {
+        true?: string;
+        false?: string;
+    };
+} | {
+    type: "choice";
+    instructions: string;
+    criteria: Record<string, string>;
+} | {
+    type: "score";
+    instructions: string;
+    criteria: string[];
+};
+/** Risposta a una domanda `noul`: `noul` è P(sì), da 0 a 1. */
+export interface NoulAnswer {
+    type: "noul";
+    noul: number;
+}
+/** Risposta a una `choice`: l'etichetta più probabile e le probabilità di tutte. */
+export interface ChoiceAnswer {
+    type: "choice";
+    choice: string;
+    probabilities: Record<string, number>;
+    confidence?: number;
+}
+/** Risposta a uno `score`: continuo (media pesata sui livelli), non un intero — arrotondare prima di una soglia. */
+export interface ScoreAnswer {
+    type: "score";
+    score: number;
+    probabilities: Record<string, number>;
+    confidence?: number;
+}
+/**
+ * Il verdetto per una singola domanda: valore tipizzato con la sua probabilità, mai testo libero.
+ * Si distingue per `type`. Un tipo che l'SDK non conosce ancora passa com'è (`{ type: string, … }`).
+ */
+export type DecisionAnswer = NoulAnswer | ChoiceAnswer | ScoreAnswer | ({
+    type: string;
+} & Record<string, unknown>);
+export interface DecisionUsage {
+    /** Token in ingresso/uscita — l'endpoint li chiama `input_tokens`/`output_tokens`. */
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    /** Costo reale in USD, come lo riporta OpenRouter — stessa fonte di `cost_usd` altrove
+     *  nell'SDK, mai stimato lato client. */
+    cost_usd: number;
+}
+/** Risposta dell'endpoint Decisions: una per domanda posta, nessuna scelta implicita fra loro. */
+export interface DecisionResult {
+    id: string;
+    /** Il modello che ha risposto, con la data di versione (`typesafe/jev-1.13-20260917`). */
+    model: string;
+    provider?: string;
+    answers: Record<string, DecisionAnswer>;
+    usage: DecisionUsage;
+}
+/** Richiesta a un modello System One: nessun `messages`, nessun `max_tokens` — non sono concetti
+ *  che questa famiglia di modelli conosce. */
+export interface EvaluateDecisionParams {
+    /** Fisso per questo tipo di modello: non esiste un default sensato come per la chat, la
+     *  famiglia "System One" è volutamente ristretta e chi la chiama la sceglie a mano. */
+    model: string;
+    /** Lo stato applicativo su cui decidere — dati, non prompt: nessuna istruzione va qui dentro,
+     *  le istruzioni stanno in {@link DecisionQuestion.instructions}. */
+    state: Record<string, unknown>;
+    questions: Record<string, DecisionQuestion>;
+    /** Identità del tenant finale, come `user` in `chat.completions.create()`: se presente, il
+     *  costo di questa decisione è attribuito e limitato per quel conto. */
+    user?: string;
+}
+/**
+ * Una singola chiamata all'endpoint Decisions — pass-through quasi totale, stessa forma di
+ * `callOpenRouterRaw` in `raw.ts`: nessuna orchestrazione, un ritentativo sui soli errori
+ * transitori (`backoff.ts`), un errore tipizzato (`provider-error.ts`) che `client.ts` può usare
+ * per decidere se ri-coniare.
+ */
+export declare function callOpenRouterDecision(runtimeKey: string, params: EvaluateDecisionParams, fetchImpl: typeof fetch, retry?: RetryConfig | false): Promise<DecisionResult>;
+/**
+ * Configura un tool locale che, chiamato dal modello **conversazionale** che sta orchestrando
+ * (Claude, GPT, ... via `chat.completions.create()`), delega la decisione a un modello System
+ * One come Jev — restando dentro lo stesso loop e la stessa runtime key/conto.
+ *
+ * **`questions` e `model` sono fissi per questo tool, non li sceglie il modello che lo chiama.**
+ * Il modello conversazionale può decidere *quando* chiamare il tool e *quali fatti* passargli
+ * (`parameters`), non *come* Jev deve rispondere: la forma del verdetto (bool/choice/score) è
+ * decisa da chi integra, in anticipo — esattamente come un `LocalToolDefinition` normale non
+ * lascia il modello scegliere quale funzione locale gira dietro un nome.
+ *
+ * **`state` non sono gli argomenti del modello per default fidato: è una scelta esplicita.**
+ * Il default (nessun `state` passato) manda a Jev esattamente gli argomenti che il modello ha
+ * generato — comodo per prototipare, ma un modello può sbagliare un campo o ometterne uno. Chi
+ * ha dati fidati da aggiungere (un ruolo utente, un flag di piano) li inietta qui dal `context`,
+ * mai generato dal modello — stessa regola di `LocalToolDefinition.execute`.
+ */
+export interface DecisionToolConfig<TContext = unknown> {
+    name: string;
+    description: string;
+    model: string;
+    questions: Record<string, DecisionQuestion>;
+    /** JSON Schema (function-calling) degli argomenti che il modello conversazionale fornisce. */
+    parameters: Record<string, unknown>;
+    /** Costruisce lo `state` da mandare a Jev. Default: gli argomenti del modello, invariati. */
+    state?: (args: Record<string, unknown>, context: TContext) => Record<string, unknown>;
+    /** Il conto a cui attribuire il costo di questa decisione. Default: nessuno (conto del
+     *  proprietario, come ogni chiamata senza `user`). */
+    user?: (context: TContext) => string | undefined;
+    sequential?: boolean;
+    timeoutMs?: number;
+    available?: (context: TContext) => boolean;
+}
+/**
+ * Costruisce il `LocalToolDefinition` da registrare con `ai.addTool(...)` o nel costruttore
+ * (`tools: [...]`). `evaluate` è l'unico punto di contatto col client FANTASTICO: chi chiama
+ * questa funzione non sa nulla del conio o della runtime key, solo che `evaluate` restituisce un
+ * {@link DecisionResult} pagato sul conto giusto — è `client.ts` a passare quella chiusura.
+ */
+export declare function createDecisionTool<TContext = unknown>(config: DecisionToolConfig<TContext>, evaluate: (params: EvaluateDecisionParams) => Promise<DecisionResult>): LocalToolDefinition<TContext>;

package/dist/decisions.js

@@ -0,0 +1,71 @@
+import { providerErrorFromResponse, errorInBody } from "./provider-error.js";
+import { withTransientRetry } from "./backoff.js";
+export async function callOpenRouterDecision(runtimeKey, params, fetchImpl, retry = {}) {
+    const body = {
+        model: params.model,
+        state: params.state,
+        questions: params.questions,
+    };
+    return withTransientRetry(async () => {
+        const res = await fetchImpl("https://openrouter.ai/api/alpha/decisions", {
+            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 Decisions");
+        const payload = await res.json();
+        const embedded = errorInBody(payload, "OpenRouter Decisions");
+        if (embedded)
+            throw embedded;
+        return normalizeDecisionResponse(payload, params.model);
+    }, retry);
+}
+function normalizeDecisionResponse(payload, requestedModel) {
+    const p = payload;
+    const answers = {};
+    for (const [name, a] of Object.entries(p.answers ?? {})) {
+        if (a && typeof a === "object" && typeof a.type === "string") {
+            answers[name] = a;
+        }
+    }
+    return {
+        id: p.id ?? "",
+        model: p.model ?? requestedModel,
+        ...(p.provider ? { provider: p.provider } : {}),
+        answers,
+        usage: {
+            prompt_tokens: p.usage?.input_tokens ?? p.usage?.prompt_tokens,
+            completion_tokens: p.usage?.output_tokens ?? p.usage?.completion_tokens,
+            cost_usd: p.usage?.cost ?? 0,
+        },
+    };
+}
+export function createDecisionTool(config, evaluate) {
+    return {
+        type: "function",
+        function: {
+            name: config.name,
+            description: config.description,
+            parameters: config.parameters,
+        },
+        sequential: config.sequential,
+        timeoutMs: config.timeoutMs,
+        available: config.available,
+        execute: async (args, context) => {
+            const state = config.state ? config.state(args, context) : args;
+            const result = await evaluate({
+                model: config.model,
+                state,
+                questions: config.questions,
+                user: config.user?.(context),
+            });
+            return result.answers;
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { Fantastico } from "./client.js";
+export { parseToolOriginMap, resolveToolEndpoint, toolOriginMapFromEnv, type ToolOriginMap } from "./tool-origin.js";
+export { FantasticoError, EmptyCompletionError } from "./types.js";
+export { ProviderError } from "./provider-error.js";
+export type { FantasticoOptions, ChatCompletionCreateParams, ReasoningConfig, ReasoningEffort, ChatCompletion, ChatCompletionResult, ChatMessage, CompletionUsage, ChatCompletionChoice, ToolDefinition, ToolCall, ChatContentPart, RawChatMessage, RawCompletionCreateParams, RawChatCompletion, AccountCreateParams, AccountUpdateParams, AccountInfo, AccountKeyInfo, IssuedAccountKey, RuntimeKeyInfo, RuntimeKeyHandle, ContoBalance, ClientAction, PendingToolCall, PendingCompletion, ResumeDecision, OpenRouterModel, } from "./types.js";
+export type { LocalToolDefinition, ClientActionToolDefinition, RegisteredTool } from "./local-tools.js";
+export { LocalToolRegistry } from "./local-tools.js";
+export type { DecisionQuestion, DecisionAnswer, NoulAnswer, ChoiceAnswer, ScoreAnswer, DecisionUsage, DecisionResult, EvaluateDecisionParams, DecisionToolConfig, } from "./decisions.js";
+export type { SpeechCreateParams, SpeechTurn, SpeechResult, SpeechModel } from "./speech.js";
+export { FantasticoActions } from "./browser-actions.js";
+export { writeActivityStream, ACTIVITY_STREAM_CONTENT_TYPE } from "./activity.js";
+export type { ChatActivityEvent, ChatActivityListener, ChatActivityOptions } from "./activity.js";
+export type { Surface } from "./surface.js";
+export type { ClientActionHandler } from "./browser-actions.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { Fantastico } from "./client.js";
+export { parseToolOriginMap, resolveToolEndpoint, toolOriginMapFromEnv } from "./tool-origin.js";
+export { FantasticoError, EmptyCompletionError } from "./types.js";
+export { ProviderError } from "./provider-error.js";
+export { LocalToolRegistry } from "./local-tools.js";
+export { FantasticoActions } from "./browser-actions.js";
+export { writeActivityStream, ACTIVITY_STREAM_CONTENT_TYPE } from "./activity.js";