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

package/dist/orchestrator.js

@@ -0,0 +1,296 @@
+import { isClientAction } from "./local-tools.js";
+import { toolResultOk } from "./activity.js";
+export class OrchestrationError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "OrchestrationError";
+    }
+}
+function emit(opts, event) {
+    if (!opts.onEvent)
+        return;
+    try {
+        opts.onEvent(event);
+    }
+    catch {
+    }
+}
+function activityLabelFor(name, args, registry) {
+    const tool = registry.get(name);
+    if (!tool || isClientAction(tool) || !tool.activityLabel)
+        return undefined;
+    try {
+        return tool.activityLabel(args);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function tracked(tc, args, opts, run) {
+    const name = tc.function.name;
+    emit(opts, { type: "tool_start", id: tc.id, name, label: activityLabelFor(name, args, opts.localTools) });
+    const startedAt = Date.now();
+    let result;
+    try {
+        result = await run();
+    }
+    catch (err) {
+        emit(opts, { type: "tool_end", id: tc.id, name, ok: false, durationMs: Date.now() - startedAt });
+        throw err;
+    }
+    emit(opts, { type: "tool_end", id: tc.id, name, ok: toolResultOk(result), durationMs: Date.now() - startedAt });
+    return result;
+}
+function findToolForFunction(toolName, tools) {
+    return tools.find((s) => s.allowedTools.includes(toolName));
+}
+export const DEFAULT_BUDGET_MS = 90_000;
+export async function orchestrate(messages, llm, opts) {
+    const state = {
+        conv: [...messages],
+        turns: 0,
+        mcpCalls: 0,
+        promptTokens: 0,
+        completionTokens: 0,
+        cacheCreationTokens: 0,
+        cacheReadTokens: 0,
+        reasoningTokens: 0,
+        costUsd: 0,
+        clientActions: [],
+        budgetMs: opts.budgetMs ?? DEFAULT_BUDGET_MS,
+        maxTurns: opts.maxTurns ?? 8,
+        model: opts.model,
+    };
+    return runLoop(state, Date.now(), llm, opts);
+}
+export async function resumeOrchestration(rawState, decisions, llm, opts) {
+    const state = rawState;
+    if (!state || !Array.isArray(state.conv)) {
+        throw new OrchestrationError("Stato di ripresa non valido", "INVALID_STATE");
+    }
+    const last = state.conv[state.conv.length - 1];
+    if (!last || last.role !== "assistant" || !last.tool_calls || last.tool_calls.length === 0) {
+        throw new OrchestrationError("Nessuna tool_call sospesa da riprendere", "INVALID_STATE");
+    }
+    const decisionById = new Map(decisions.map((d) => [d.id, d]));
+    for (const tc of last.tool_calls) {
+        const args = safeParseArgs(tc.function.arguments);
+        const tool = opts.localTools.get(tc.function.name);
+        const decision = decisionById.get(tc.id);
+        let result;
+        if (tool && !isClientAction(tool) && tool.requiresConfirmation) {
+            if (decision?.approved) {
+                result = await tracked(tc, args, opts, () => opts.localTools.execute(tc.function.name, args, opts.context));
+            }
+            else {
+                result = JSON.stringify({ error: "Azione negata dall'operatore" });
+            }
+        }
+        else if (tool && isClientAction(tool) && tool.awaitsResult) {
+            if (decision && "result" in decision) {
+                result = typeof decision.result === "string" ? decision.result : JSON.stringify(decision.result ?? null);
+            }
+            else {
+                result = JSON.stringify({ error: "Nessun esito ricevuto dal client per questa azione" });
+            }
+        }
+        else if (tool && !isClientAction(tool)) {
+            result = await tracked(tc, args, opts, () => opts.localTools.execute(tc.function.name, args, opts.context));
+        }
+        else {
+            result = JSON.stringify({ error: `Tool sconosciuto: ${tc.function.name}` });
+        }
+        state.conv.push({ role: "tool", tool_call_id: tc.id, content: result });
+    }
+    return runLoop(state, Date.now(), llm, opts);
+}
+function safeParseArgs(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+async function runLoop(state, startedAt, llm, opts) {
+    const mcpTools = toolsToDefinitions(opts.remoteTools);
+    let lastResponse = null;
+    for (let turn = state.turns; turn < state.maxTurns; turn++) {
+        if (Date.now() - startedAt > state.budgetMs) {
+            throw new OrchestrationError("Timeout orchestrazione", "TIMEOUT");
+        }
+        state.turns++;
+        const isLastTurn = turn === state.maxTurns - 1;
+        const localDefs = opts.localTools.definitionsFor(opts.context);
+        const allTools = [...mcpTools, ...localDefs];
+        const tools = allTools.length > 0 && !isLastTurn ? allTools : undefined;
+        emit(opts, { type: "thinking", turn: state.turns });
+        const response = await llm.chatCompletion({
+            model: opts.model,
+            messages: state.conv,
+            tools,
+            temperature: opts.temperature,
+            max_tokens: opts.maxTokens,
+            reasoning: opts.reasoning,
+        });
+        if (response.usage) {
+            state.promptTokens += response.usage.prompt_tokens ?? 0;
+            state.completionTokens += response.usage.completion_tokens ?? 0;
+            state.cacheCreationTokens += response.usage.prompt_tokens_details?.cache_write_tokens ?? 0;
+            state.cacheReadTokens += response.usage.prompt_tokens_details?.cached_tokens ?? 0;
+            state.reasoningTokens = (state.reasoningTokens ?? 0)
+                + (response.usage.completion_tokens_details?.reasoning_tokens ?? 0);
+            state.costUsd += response.usage.cost ?? 0;
+        }
+        lastResponse = response;
+        const choice = response.choices[0];
+        if (!choice)
+            break;
+        const toolCalls = choice.message.tool_calls;
+        if (!toolCalls || toolCalls.length === 0 || choice.finish_reason !== "tool_calls") {
+            return buildDone(response, state);
+        }
+        state.conv.push({ role: "assistant", content: choice.message.content, tool_calls: toolCalls });
+        const blocking = blockingCallsIn(toolCalls, opts.localTools);
+        if (blocking.length > 0) {
+            return {
+                status: "pending",
+                pending: toolCalls.map((tc) => {
+                    const args = safeParseArgs(tc.function.arguments);
+                    return {
+                        id: tc.id,
+                        name: tc.function.name,
+                        arguments: args,
+                        reason: blockingReasonFor(tc.function.name, opts.localTools),
+                        summary: confirmationSummaryFor(tc.function.name, args, opts.localTools),
+                    };
+                }),
+                state,
+                message: choice.message.content || undefined,
+            };
+        }
+        if (Date.now() - startedAt > state.budgetMs) {
+            throw new OrchestrationError("Timeout durante esecuzione tool", "TIMEOUT");
+        }
+        await executeBatch(toolCalls, state, opts);
+    }
+    if (lastResponse)
+        return buildDone(lastResponse, state);
+    throw new OrchestrationError("Orchestrazione terminata senza risposta", "UPSTREAM_ERROR");
+}
+function blockingReasonFor(name, registry) {
+    const tool = registry.get(name);
+    if (!tool)
+        return undefined;
+    if (isClientAction(tool))
+        return tool.awaitsResult ? "client_action" : undefined;
+    return tool.requiresConfirmation ? "confirmation" : undefined;
+}
+function blockingCallsIn(toolCalls, registry) {
+    return toolCalls.filter((tc) => blockingReasonFor(tc.function.name, registry) !== undefined);
+}
+function confirmationSummaryFor(name, args, registry) {
+    const tool = registry.get(name);
+    if (!tool || isClientAction(tool) || !tool.requiresConfirmation || !tool.confirmationSummary)
+        return undefined;
+    try {
+        return tool.confirmationSummary(args);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function executeBatch(toolCalls, state, opts) {
+    const anySequential = toolCalls.some((tc) => {
+        const tool = opts.localTools.get(tc.function.name);
+        return tool?.sequential === true;
+    });
+    const run = async (tc) => {
+        const args = safeParseArgs(tc.function.arguments);
+        const tool = opts.localTools.get(tc.function.name);
+        let result;
+        if (tool && isClientAction(tool)) {
+            state.clientActions.push({ id: tc.id, name: tc.function.name, arguments: args });
+            result = JSON.stringify({ delivered: true });
+        }
+        else if (tool) {
+            result = await tracked(tc, args, opts, () => opts.localTools.execute(tc.function.name, args, opts.context));
+        }
+        else {
+            const tool = findToolForFunction(tc.function.name, opts.remoteTools);
+            if (!tool) {
+                result = JSON.stringify({ error: `Tool sconosciuto: ${tc.function.name}` });
+            }
+            else {
+                result = await tracked(tc, args, opts, async () => {
+                    try {
+                        const out = await opts.mcpExecutor(tool, tc.function.name, args);
+                        state.mcpCalls++;
+                        return out;
+                    }
+                    catch (err) {
+                        return JSON.stringify({ error: `Errore MCP: ${err.message}` });
+                    }
+                });
+            }
+        }
+        state.conv.push({ role: "tool", tool_call_id: tc.id, content: result });
+    };
+    if (anySequential) {
+        for (const tc of toolCalls)
+            await run(tc);
+    }
+    else {
+        await Promise.all(toolCalls.map(run));
+    }
+}
+function buildDone(response, state) {
+    const choice = response.choices[0];
+    return {
+        status: "done",
+        id: response.id,
+        object: "chat.completion",
+        model: response.model,
+        choices: [
+            {
+                index: 0,
+                message: { role: "assistant", content: choice?.message.content ?? "" },
+                finish_reason: choice?.finish_reason === "length" ? "length" : "stop",
+            },
+        ],
+        usage: buildUsage(state),
+        clientActions: state.clientActions,
+    };
+}
+function buildUsage(state) {
+    return {
+        prompt_tokens: state.promptTokens,
+        completion_tokens: state.completionTokens,
+        total_tokens: state.promptTokens + state.completionTokens,
+        internal_turns: state.turns,
+        cache_creation_tokens: state.cacheCreationTokens,
+        cache_read_tokens: state.cacheReadTokens,
+        reasoning_tokens: state.reasoningTokens ?? 0,
+        mcp_calls: state.mcpCalls,
+        cost_usd: Math.round(state.costUsd * 1e6) / 1e6,
+    };
+}
+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/provider-error.d.ts

@@ -0,0 +1,165 @@
+import { EmptyCompletionError } from "./types.js";
+/**
+ * L'errore del provider LLM, con dentro quel che il provider ha davvero detto.
+ *
+ * **Perché esiste.** Prima ogni chiamata fallita diventava un `Error` il cui unico contenuto era
+ * `` `Provider LLM ${status}: ${text}` ``, e chi doveva decidere se ri-coniare — `withProviderRetry`
+ * in `client.ts`, che sta sopra l'orchestratore e vede solo un `Error` qualunque — ricostruiva quella
+ * decisione con una regex sulla prosa (`/insufficient|no.?credit|payment.?required|401/i`). Lo stato
+ * HTTP non sopravviveva alla pila: esisteva solo come caratteri dentro un messaggio. Due difetti
+ * concreti, entrambi documentati da OpenRouter e non teorici:
+ *
+ * 1. **403 è "Insufficient permissions"** nella doc di OpenRouter (permessi, guardrail, moderazione).
+ *    La regex ci cascava: un blocco di moderazione bruciava un conio, occupava una seconda chiave,
+ *    falliva identico e arrivava al chiamante come `LLM_PROVIDER_ERROR` — nascondendo
+ *    l'unica classe di errore su cui l'utente finale poteva davvero intervenire.
+ * 2. **`401` come sottostringa pesca nel prompt.** Gli errori di moderazione rimandano indietro il
+ *    testo dell'utente in `metadata.flagged_input`, che finiva nel messaggio: un prompt bloccato che
+ *    contenesse quelle tre cifre — un numero di fattura, una domanda sugli stati HTTP — diventava un
+ *    errore di credito.
+ *
+ * Il segnale strutturato c'è sempre stato, ed era la stringificazione a buttarlo via: il corpo di
+ * ogni errore è `{ error: { code, message, metadata? } }`, e gli errori di provider portano in
+ * `metadata.error_type` un insieme chiuso di valori — fra cui `authentication`, `payment_required` e
+ * `permission_denied`, cioè esattamente la distinzione che la regex tentava di dedurre dalla prosa.
+ *
+ * **Non si conserva il corpo grezzo.** Quando il JSON si legge si prende `error.message` e nient'altro:
+ * `metadata.flagged_input` è il prompt del cliente, e un messaggio d'errore finisce nei log, dove il
+ * contenuto dei clienti non deve arrivare. Quando non si legge, il testo viene troncato.
+ */
+export declare class ProviderError extends Error {
+    /** Lo stato HTTP della risposta. `200` quando l'errore arrivava dentro un corpo di successo. */
+    readonly httpStatus: number;
+    /** `error.code` dal corpo: è quello che vale quando l'HTTP dice 200 (vedi `errorInBody`). */
+    readonly providerCode: number | null;
+    /** `error.metadata.error_type`, quando il provider lo manda. */
+    readonly errorType: string | null;
+    /**
+     * `Retry-After` in millisecondi, quando l'header c'è. È il provider che dice **quanto**
+     * aspettare: sostituirgli la propria curva esponenziale è indovinare dopo essere stati
+     * informati. La doc lo documenta su rate limit e indisponibilità.
+     */
+    readonly retryAfterMs: number | null;
+    /**
+     * Il motivo del provider a monte (`upstreamReason`). **Fuori dal messaggio di proposito**: il
+     * messaggio di un errore finisce spesso davanti all'utente finale, e lì non si nomina il
+     * fornitore né si mostra la sua prosa. Questo campo è per i log, dove Node lo stampa da solo.
+     */
+    readonly upstream: string | null;
+    constructor(message: string, 
+    /** Lo stato HTTP della risposta. `200` quando l'errore arrivava dentro un corpo di successo. */
+    httpStatus: number, 
+    /** `error.code` dal corpo: è quello che vale quando l'HTTP dice 200 (vedi `errorInBody`). */
+    providerCode: number | null, 
+    /** `error.metadata.error_type`, quando il provider lo manda. */
+    errorType: string | null, 
+    /**
+     * `Retry-After` in millisecondi, quando l'header c'è. È il provider che dice **quanto**
+     * aspettare: sostituirgli la propria curva esponenziale è indovinare dopo essere stati
+     * informati. La doc lo documenta su rate limit e indisponibilità.
+     */
+    retryAfterMs?: number | null, 
+    /**
+     * Il motivo del provider a monte (`upstreamReason`). **Fuori dal messaggio di proposito**: il
+     * messaggio di un errore finisce spesso davanti all'utente finale, e lì non si nomina il
+     * fornitore né si mostra la sua prosa. Questo campo è per i log, dove Node lo stampa da solo.
+     */
+    upstream?: string | null);
+}
+/**
+ * Costruisce l'errore da una risposta non-ok. Il prefisso (`label`) resta quello che i due call site
+ * avevano già — cambiarlo renderebbe irriconoscibili i messaggi nei log di chi integra.
+ */
+export declare function providerErrorFromResponse(res: Response, label: string): Promise<ProviderError>;
+/**
+ * `Retry-After` arriva in due forme, entrambe standard: un numero di secondi, o una data HTTP.
+ * Si accettano tutte e due — leggerne una sola significherebbe ignorare l'indicazione del provider
+ * esattamente nei casi in cui manda l'altra. Un valore assurdo (negativo, non numerico, una data
+ * già passata) vale "non l'ha detto": il chiamante ha comunque il proprio esponenziale.
+ */
+export declare function retryAfterMs(header: string | null): number | null;
+/**
+ * L'errore consegnato dentro una risposta **riuscita**. OpenRouter documenta che una richiesta può
+ * tornare `200 OK` con un oggetto `error` al posto della completion, quando il provider comincia a
+ * elaborare e poi fallisce. Senza questo controllo quel corpo veniva castato a `LlmResponse` e
+ * arrivava all'orchestratore, che legge `response.choices[0]` su un oggetto senza `choices`: il
+ * chiamante vedeva un `INTERNAL_ERROR` con dentro un TypeError, e un `payment_required` non
+ * innescava mai il ri-conio per cui tutto il meccanismo esiste.
+ *
+ * Lo stato che conta qui è `error.code`, non il 200 del trasporto.
+ */
+export declare function errorInBody(payload: unknown, label: string): ProviderError | null;
+/**
+ * Se un conio nuovo ha qualche speranza di riparare questo errore.
+ *
+ * Solo due casi, e sono quelli che la doc di OpenRouter definisce così:
+ * - **401 / `authentication`** — credenziale non valida o revocata: è una runtime key già
+ *   scaduta e ritirata, o scaduta fra la lettura dalla cache e la chiamata.
+ * - **402 / `payment_required`** — "your account **or API key** has insufficient credits". L'ambiguità
+ *   è loro, non nostra: la doc dice esplicitamente che quel codice non distingue il tetto della
+ *   singola key dal saldo dell'account. È per questo che il verdetto non si dà, si prova: se era il
+ *   tetto di questa key, una key nuova lo supera; altrimenti si ripete —
+ *   e l'unico messaggio onesto resta un errore di comunicazione col provider.
+ *
+ * Tutto il resto è concluso: 403 (permessi, guardrail, moderazione), 429 (rate limit, che porta
+ * `Retry-After` e vuole un'attesa, non una credenziale nuova), 5xx (il provider), 400/404 (noi).
+ */
+export declare function isRemintable(err: unknown): boolean;
+/**
+ * Se **la stessa identica richiesta**, rimandata fra un attimo, può andare a buon fine.
+ *
+ * Distinto da `isRemintable` e non sovrapponibile: lì la richiesta era giusta e la credenziale no,
+ * qui la credenziale va bene ed è il momento a essere sbagliato. Un errore non è mai entrambe le
+ * cose, e tenerle separate è ciò che impedisce a un ritentativo di incatenarsi a un ri-conio.
+ */
+export declare function isTransient(err: unknown): boolean;
+/**
+ * Come un errore del provider si presenta al chiamante: `{ code, status }` per un `FantasticoError`.
+ *
+ * `null` quando non c'è niente da dire di preciso — non è un errore del provider, o il provider non
+ * l'ha classificato — e il chiamante ricade sull'`INTERNAL_ERROR` generico.
+ *
+ * **Perché il codice porta un prefisso.** `status` in questo SDK non è mai stato un numero nostro:
+ * `auth.ts` e `client.ts:api()` ci mettono già, verbatim, lo stato HTTP del Cloud. Passare anche
+ * quello del provider è quindi coerente — ma introduce una cosa nuova, cioè due mittenti diversi
+ * dietro lo stesso numero. Il control plane usa il `403` per `EMAIL_NOT_VERIFIED` e
+ * `ACCOUNT_DISABLED`; il provider lo usa per permessi, guardrail e moderazione. Chi legge
+ * `err.status === 403` deve poter sapere **chi ha parlato**, perché i due rimedi sono opposti
+ * (sistemare l'account / far riformulare il prompt all'utente finale). Il discriminante è `code`,
+ * che è una stringa e regge già ogni altra distinzione qui dentro: `PROVIDER_` lo rende esplicito
+ * e cercabile.
+ *
+ * **E non riguarda solo il 403.** Prima, ogni errore non ri-coniabile diventava `INTERNAL_ERROR`
+ * 500: `context_length_exceeded`, il modello inesistente, il payload troppo grande — cioè gli
+ * errori più azionabili che il provider produca — arrivavano tutti travestiti da guasto dell'SDK.
+ * Una regola sola li copre; non serve una tabella per codice.
+ */
+export declare function providerFailure(err: unknown): {
+    code: string;
+    status: number;
+} | null;
+/**
+ * Il 200 che non è un successo: tetto raggiunto, e in mano non è rimasto niente.
+ *
+ * `null` quando va tutto bene — e va tutto bene in molti più casi di quanti ne fermi, di proposito:
+ * **un falso positivo qui è peggio del difetto che chiude**, perché farebbe fallire una risposta
+ * che il chiamante avrebbe usato. Tre casi che sembrano questo e non lo sono, e che restano fuori:
+ *
+ * | Caso | Perché passa |
+ * |---|---|
+ * | `length` con contenuto **non vuoto** | è troncato, ma c'è: il chiamante lo vede e `finish_reason` glielo dice. Fermarlo romperebbe il "generami un testo lungo, al troncamento penso io" |
+ * | `stop` con contenuto vuoto | un modello che sceglie di non dire niente non ha sforato nessun tetto |
+ * | contenuto vuoto **con `tool_calls`** | è la forma normale di un turno che chiama un tool: qui il contenuto non serve |
+ *
+ * Quindi si ferma una sola combinazione: tetto raggiunto **e** nessun tool chiesto **e** niente da
+ * leggere. Gli spazi bianchi contano come niente: un `"\\n"` non è una risposta.
+ */
+export declare function emptyCompletionError(args: {
+    model: string;
+    finishReason: string | undefined;
+    content: unknown;
+    toolCalls: unknown;
+    maxTokens: number | null;
+    completionTokens: number;
+    reasoningTokens: number;
+}): EmptyCompletionError | null;

package/dist/provider-error.js

@@ -0,0 +1,156 @@
+import { EmptyCompletionError } from "./types.js";
+export class ProviderError extends Error {
+    httpStatus;
+    providerCode;
+    errorType;
+    retryAfterMs;
+    upstream;
+    constructor(message, httpStatus, providerCode, errorType, retryAfterMs = null, upstream = null) {
+        super(message);
+        this.httpStatus = httpStatus;
+        this.providerCode = providerCode;
+        this.errorType = errorType;
+        this.retryAfterMs = retryAfterMs;
+        this.upstream = upstream;
+        this.name = "ProviderError";
+    }
+}
+const CONCLUSIVE_ERROR_TYPES = new Set([
+    "context_length_exceeded", "max_tokens_exceeded", "token_limit_exceeded", "string_too_long",
+    "authentication", "permission_denied", "payment_required",
+    "rate_limit_exceeded", "provider_overloaded", "provider_unavailable",
+    "invalid_request", "invalid_prompt", "not_found", "precondition_failed",
+    "payload_too_large", "unprocessable",
+    "content_policy_violation", "refusal",
+    "invalid_image", "image_too_large", "image_too_small",
+    "unsupported_image_format", "image_not_found", "image_download_failed",
+    "server", "timeout",
+]);
+const REMINTABLE_ERROR_TYPES = new Set(["authentication", "payment_required"]);
+const TRANSIENT_ERROR_TYPES = new Set(["rate_limit_exceeded", "provider_overloaded"]);
+const TRANSIENT_STATUSES = new Set([429, 503]);
+const MAX_RAW_MESSAGE = 300;
+function upstreamReason(metadata) {
+    if (typeof metadata !== "object" || metadata === null)
+        return null;
+    const { provider_name: provider, raw } = metadata;
+    let reason = null;
+    if (typeof raw === "string" && raw.length > 0) {
+        try {
+            const body = JSON.parse(raw);
+            const inner = typeof body.error === "object" && body.error !== null ? body.error.message : body.error ?? body.message;
+            reason = typeof inner === "string" ? inner : null;
+        }
+        catch {
+            reason = null;
+        }
+    }
+    if (!reason)
+        return null;
+    const who = typeof provider === "string" && provider.length > 0 ? `${provider}: ` : "";
+    return truncate(`${who}${reason}`);
+}
+function readErrorEnvelope(payload) {
+    if (typeof payload !== "object" || payload === null)
+        return null;
+    const err = payload.error;
+    if (typeof err !== "object" || err === null)
+        return null;
+    const { code, message, metadata } = err;
+    const errorType = typeof metadata === "object" && metadata !== null
+        ? metadata.error_type
+        : undefined;
+    return {
+        message: typeof message === "string" && message.length > 0 ? message : null,
+        code: typeof code === "number" ? code : null,
+        errorType: typeof errorType === "string" ? errorType : null,
+        upstream: upstreamReason(metadata),
+    };
+}
+function truncate(text) {
+    return text.length > MAX_RAW_MESSAGE ? `${text.slice(0, MAX_RAW_MESSAGE)}…` : text;
+}
+export async function providerErrorFromResponse(res, label) {
+    const raw = await res.text();
+    let parsed = null;
+    try {
+        parsed = readErrorEnvelope(JSON.parse(raw));
+    }
+    catch {
+        parsed = null;
+    }
+    const detail = parsed?.message ?? truncate(raw);
+    return new ProviderError(`${label} ${res.status}: ${detail}`, res.status, parsed?.code ?? null, parsed?.errorType ?? null, retryAfterMs(res.headers.get("Retry-After")), parsed?.upstream ?? null);
+}
+export function retryAfterMs(header) {
+    if (header === null)
+        return null;
+    const seconds = Number(header.trim());
+    if (Number.isFinite(seconds))
+        return seconds > 0 ? Math.round(seconds * 1000) : null;
+    const at = Date.parse(header);
+    if (Number.isNaN(at))
+        return null;
+    const delta = at - Date.now();
+    return delta > 0 ? delta : null;
+}
+export function errorInBody(payload, label) {
+    const parsed = readErrorEnvelope(payload);
+    if (!parsed)
+        return null;
+    const code = parsed.code ?? 200;
+    return new ProviderError(`${label} ${code}: ${parsed.message ?? "errore nel corpo della risposta"}`, 200, parsed.code, parsed.errorType, null, parsed.upstream);
+}
+export function isRemintable(err) {
+    if (!(err instanceof ProviderError))
+        return false;
+    if (err.errorType !== null && CONCLUSIVE_ERROR_TYPES.has(err.errorType)) {
+        return REMINTABLE_ERROR_TYPES.has(err.errorType);
+    }
+    const code = err.providerCode ?? err.httpStatus;
+    return code === 401 || code === 402;
+}
+export function isTransient(err) {
+    if (!(err instanceof ProviderError))
+        return false;
+    if (err.errorType !== null && CONCLUSIVE_ERROR_TYPES.has(err.errorType)) {
+        return TRANSIENT_ERROR_TYPES.has(err.errorType);
+    }
+    return TRANSIENT_STATUSES.has(err.providerCode ?? err.httpStatus);
+}
+export function providerFailure(err) {
+    if (!(err instanceof ProviderError))
+        return null;
+    if (err.errorType === null || !CONCLUSIVE_ERROR_TYPES.has(err.errorType))
+        return null;
+    const status = err.providerCode ?? (err.httpStatus === 200 ? 502 : err.httpStatus);
+    return { code: `PROVIDER_${err.errorType.toUpperCase()}`, status };
+}
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => (typeof part === "object" && part !== null && "text" in part
+            ? String(part.text ?? "")
+            : ""))
+            .join("");
+    }
+    return "";
+}
+export function emptyCompletionError(args) {
+    if (args.finishReason !== "length")
+        return null;
+    if (Array.isArray(args.toolCalls) && args.toolCalls.length > 0)
+        return null;
+    if (textOf(args.content).trim() !== "")
+        return null;
+    const budget = args.maxTokens === null ? "il budget di output" : `${args.maxTokens} token di output`;
+    const cause = args.reasoningTokens > 0
+        ? `ne ha spesi ${args.reasoningTokens} a ragionare e non ha restituito contenuto`
+        : "ha esaurito il budget senza restituire contenuto";
+    const remedy = args.reasoningTokens > 0
+        ? "spegni il ragionamento (`reasoning: { enabled: false }`) o alza `max_tokens`"
+        : "alza `max_tokens`";
+    return new EmptyCompletionError(`${args.model}: raggiunto ${budget} (${args.completionTokens} usati), ${cause} — ${remedy}`, args.model, args.maxTokens, args.completionTokens, args.reasoningTokens);
+}

package/dist/raw.d.ts

@@ -0,0 +1,48 @@
+import type { RawCompletionCreateParams, RawChatMessage, CompletionUsage } from "./types.js";
+import { type RetryConfig } from "./backoff.js";
+/** Risposta grezza di OpenRouter per una chat/completions — non normalizzata. */
+export interface RawLlmResponse {
+    id: string;
+    model: string;
+    provider?: string;
+    choices: Array<{
+        message: RawChatMessage;
+        finish_reason: string;
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+        cost?: number;
+        completion_tokens_details?: {
+            reasoning_tokens?: number;
+        };
+        prompt_tokens_details?: {
+            cached_tokens?: number;
+            cache_write_tokens?: number;
+        };
+    };
+}
+/**
+ * Una singola chiamata a OpenRouter, pass-through quasi totale (nessuna orchestrazione,
+ * nessuna esecuzione di tool: il chiamante gestisce il proprio loop — vedi
+ * `RawCompletionCreateParams` in types.ts).
+ *
+ * Pin del provider su Anthropic diretto quando c'è `cache_control` nei messaggi: verificato
+ * empiricamente (2026-07) che senza pin il routing di default di OpenRouter può finire su
+ * un provider (Amazon Bedrock) che ignora `cache_control` senza errore — si paga il prezzo
+ * pieno in silenzio.
+ *
+ * **Preferito, non esclusivo** (2026-10-05). Il pin era `allow_fallbacks: false`, e il 5 ottobre
+ * l'organizzazione Anthropic usata da OpenRouter è stata messa in attesa (`organization_on_hold`):
+ * ogni chat con `cache_control` falliva con un 400, mentre la stessa chiamata con il fallback
+ * permesso rispondeva. La cache persa per qualche ora costa il prezzo pieno; una chat ferma costa
+ * il prodotto. Quindi Anthropic resta il primo della lista, e se rifiuta si passa al successivo.
+ */
+export declare function callOpenRouterRaw(runtimeKey: string, params: RawCompletionCreateParams & {
+    model: string;
+}, fetchImpl: typeof fetch, retry?: RetryConfig | false): Promise<RawLlmResponse>;
+/** Mappa l'usage grezzo di OpenRouter (nomi di campo verificati empiricamente) in CompletionUsage. */
+export declare function normalizeRawUsage(usage: RawLlmResponse["usage"]): CompletionUsage;
+/** Normalizza finish_reason di OpenRouter nell'union tipizzato di RawChatCompletion. */
+export declare function normalizeFinishReason(reason: string | undefined): "stop" | "length" | "tool_calls";