@vascend/talos 0.1.0

package/dist/providers/anthropic.js

@@ -0,0 +1,526 @@
+import { appendFileSync } from "node:fs";
+import { messaggioErroreTurno, verifica as verificaImmagine } from "../core/image-limits.js";
+import { planLimitsFromHeaders } from "./plan-limits.js";
+import { errorTimingDetail } from "./provider-reset.js";
+// Dump diagnostico (gated da TALOS_DEBUG_STREAM=<file>): scrive la STRUTTURA di
+// ogni evento SSE (tipi, indici, lunghezze) senza il contenuto, per capire come
+// l'endpoint consegna l'input dei tool. Best effort, non interrompe lo stream.
+function debugStreamEvent(evt) {
+    const file = process.env["TALOS_DEBUG_STREAM"];
+    if (!file)
+        return;
+    try {
+        const type = String(evt["type"] ?? "");
+        let extra = "";
+        if (type === "content_block_start") {
+            const b = evt["content_block"];
+            const inputKeys = b?.["input"] && typeof b["input"] === "object" ? Object.keys(b["input"]) : [];
+            extra = `idx=${evt["index"]} block=${b?.["type"]} inputKeys=[${inputKeys.join(",")}]`;
+        }
+        else if (type === "content_block_delta") {
+            const d = evt["delta"];
+            const pj = d?.["partial_json"];
+            extra = `idx=${evt["index"]} delta=${d?.["type"]} pjLen=${typeof pj === "string" ? pj.length : "-"}`;
+        }
+        else if (type === "message_delta") {
+            const d = evt["delta"];
+            extra = `stop=${d?.["stop_reason"]}`;
+        }
+        appendFileSync(file, `${type} ${extra}\n`, "utf8");
+    }
+    catch {
+        // best effort
+    }
+}
+const API_URL = "https://api.anthropic.com/v1/messages";
+const VERSION = "2023-06-01";
+const ANTHROPIC_RASTER_MIME = /^image\/(?:png|jpeg|webp|gif)$/i;
+function looksLikeSvgBase64(data) {
+    try {
+        const head = Buffer.from(data.replace(/\s+/g, "").slice(0, 16384), "base64")
+            .toString("utf8").replace(/^\uFEFF/u, "").trimStart();
+        return /^(?:<\?xml\b[^>]*>\s*)?(?:<!--[^]*?-->\s*)?<svg\b/is.test(head);
+    }
+    catch {
+        return false;
+    }
+}
+// Il nome del file, non il percorso intero: in un messaggio d'errore
+// "C:\Users\...\AppData\Local\Temp\shot-8891.png" e' rumore, "shot-8891.png" no.
+function nomeLeggibile(source) {
+    const s = String(source ?? "").trim();
+    if (!s)
+        return undefined;
+    return s.split(/[\\/]/).pop() || undefined;
+}
+function anthropicImageBlock(image) {
+    if (!ANTHROPIC_RASTER_MIME.test(image.mime) || looksLikeSvgBase64(image.data)) {
+        return { type: "text", text: "[Allegato SVG/vettoriale disponibile come file; payload immagine non reinviato.]" };
+    }
+    // Un'immagine oltre gli 8000 px per lato fa fallire l'INTERO turno con un 400.
+    // Un allegato troppo grande non deve poter buttare giu' la conversazione:
+    // diventa una riga di testo che dice cosa e' successo, il resto del messaggio
+    // parte comunque, e il modello puo' rispondere a quello.
+    const verdetto = verificaImmagine(image.data, { nome: nomeLeggibile(image.source) });
+    if (!verdetto.ok)
+        return { type: "text", text: `[${verdetto.spiegazione}]` };
+    return {
+        type: "image",
+        source: { type: "base64", media_type: image.mime, data: image.data },
+    };
+}
+// Mappa i nostri messaggi nel formato dell'API Anthropic, poi NORMALIZZA
+// l'accoppiamento tool_use/tool_result (vedi normalizeToolPairing).
+export function toApiMessages(req) {
+    const mapped = req.messages
+        .filter((m) => m.role !== "system")
+        .map((m) => {
+        const content = m.content.map((part) => {
+            switch (part.type) {
+                case "text":
+                    return { type: "text", text: part.text };
+                case "tool_call":
+                    return { type: "tool_use", id: part.id, name: part.name, input: part.input };
+                case "tool_result":
+                    return {
+                        type: "tool_result",
+                        tool_use_id: part.callId,
+                        content: part.media?.length
+                            ? [
+                                { type: "text", text: part.output || "Risultato visivo del tool." },
+                                ...part.media.map((image) => anthropicImageBlock(image)),
+                            ]
+                            : part.output,
+                        is_error: part.isError,
+                    };
+                case "image":
+                    // Immagine allegata al prompt: blocco `image` con source base64
+                    // inline (i bytes sono gia' stati riletti e codificati a monte,
+                    // vedi src/core/prompt-attachment.ts).
+                    return anthropicImageBlock(part);
+            }
+        });
+        // I tool_result devono viaggiare in un turno con ruolo "user".
+        const role = m.role === "tool" ? "user" : m.role;
+        return { role, content };
+    });
+    return normalizeToolPairing(mapped);
+}
+// L'API Anthropic richiede che ogni assistant `tool_use` sia seguito SUBITO da
+// un messaggio user con un `tool_result` per ciascun id, e che non esistano
+// `tool_result` orfani. Una sessione puo' violarlo se un turno e' interrotto
+// (Ctrl+C durante un tool, comando lento, crash). Qui sintetizziamo i
+// tool_result mancanti e scartiamo quelli orfani, evitando il 400.
+export function normalizeToolPairing(messages) {
+    const out = [];
+    for (let i = 0; i < messages.length; i += 1) {
+        const m = messages[i];
+        if (!m)
+            continue;
+        if (m.role === "assistant") {
+            const toolUseIds = m.content.filter((c) => c.type === "tool_use").map((c) => String(c.id));
+            out.push(m);
+            if (toolUseIds.length) {
+                const next = messages[i + 1];
+                const provided = new Set();
+                if (next && next.role === "user") {
+                    for (const c of next.content) {
+                        if (c.type === "tool_result")
+                            provided.add(String(c.tool_use_id));
+                    }
+                }
+                const missing = toolUseIds.filter((id) => !provided.has(id));
+                if (missing.length) {
+                    const synth = missing.map((id) => ({
+                        type: "tool_result",
+                        tool_use_id: id,
+                        content: "(nessun risultato: esecuzione interrotta)",
+                        is_error: true,
+                    }));
+                    if (next && next.role === "user" && next.content.some((c) => c.type === "tool_result")) {
+                        next.content = [...synth, ...next.content];
+                    }
+                    else {
+                        out.push({ role: "user", content: synth });
+                    }
+                }
+            }
+            continue;
+        }
+        // Messaggio user: scarta i tool_result orfani (id non aperto dall'assistant
+        // immediatamente precedente).
+        if (m.role === "user" && m.content.some((c) => c.type === "tool_result")) {
+            const prev = out[out.length - 1];
+            const openIds = new Set(prev && prev.role === "assistant"
+                ? prev.content.filter((c) => c.type === "tool_use").map((c) => String(c.id))
+                : []);
+            const filtered = m.content.filter((c) => c.type !== "tool_result" || openIds.has(String(c.tool_use_id)));
+            if (filtered.length)
+                out.push({ role: "user", content: filtered });
+            continue;
+        }
+        out.push(m);
+    }
+    return out;
+}
+// Applica i breakpoint di cache (prompt caching Anthropic): marca l'ultimo
+// blocco di system e l'ultimo blocco dell'ultimo messaggio con cache_control
+// ephemeral. Riduce i token fatturati sui turni successivi.
+export function withSystemCache(system, turnContext = "") {
+    return [
+        { type: "text", text: system, cache_control: { type: "ephemeral" } },
+        ...(turnContext ? [{
+                type: "text",
+                text: `[HORIZON_TURN_CONTEXT]\n${turnContext}\n[/HORIZON_TURN_CONTEXT]`,
+            }] : []),
+    ];
+}
+// DUE breakpoint sui messaggi, non uno. L'ultimo messaggio porta il contesto
+// del turno e cambia sempre: da solo cacherebbe un prefisso che al messaggio
+// successivo non esiste piu'. Marcando anche il PENULTIMO, il prefisso che
+// finisce col turno precedente resta cacheato e viene riconosciuto al turno
+// dopo. Insieme al breakpoint su system restano 3 marcatori, sotto il tetto di
+// 4 dell'API.
+export function applyMessageCache(messages) {
+    markCacheBreakpoint(messages[messages.length - 1]);
+    if (messages.length > 1)
+        markCacheBreakpoint(messages[messages.length - 2]);
+    return messages;
+}
+function markCacheBreakpoint(message) {
+    const target = message;
+    if (!target || !Array.isArray(target.content) || !target.content.length)
+        return;
+    const blocks = target.content;
+    const lastBlock = blocks[blocks.length - 1];
+    if (lastBlock)
+        lastBlock["cache_control"] = { type: "ephemeral" };
+}
+import { anthropicEffort } from "./effort.js";
+import { resolveMaxTokens } from "../core/model-limits.js";
+import { ANTHROPIC_MODELS } from "./catalog.js";
+// Beta della finestra di contesto 1M (Opus/Sonnet 4.x). Va inviata come header
+// per attivare davvero il milione di token, altrimenti l'API resta a 200k.
+export const CONTEXT_1M_BETA = "context-1m-2025-08-07";
+// 1M attivo se: il modello lo dichiara nell'id ("1m"), o TALOS_CONTEXT_1M e'
+// truthy, o TALOS_CONTEXT_WINDOW >= 1_000_000.
+export function wants1m(model, env) {
+    const flag = (env["TALOS_CONTEXT_1M"] ?? "").trim().toLowerCase();
+    // Escape hatch: TALOS_CONTEXT_1M=off|0|false disattiva la beta 1M (se
+    // l'endpoint non la accetta).
+    if (flag === "0" || flag === "false" || flag === "off" || flag === "no")
+        return false;
+    const m = model.toLowerCase();
+    if (m.includes("1m"))
+        return true;
+    if (/^(1|true|yes|on)$/.test(flag))
+        return true;
+    const w = Number(env["TALOS_CONTEXT_WINDOW"]);
+    if (Number.isFinite(w) && w >= 1_000_000)
+        return true;
+    // Opus 4.x / Sonnet 4.x: 1M attivo di default (come Claude Code).
+    return /opus-4|sonnet-4/.test(m);
+}
+export class AnthropicProvider {
+    apiKey;
+    id = "anthropic";
+    label = "Anthropic";
+    models = ANTHROPIC_MODELS;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    async complete(req) {
+        const body = {
+            model: req.model,
+            max_tokens: resolveMaxTokens(req.maxTokens, `anthropic/${req.model}`),
+            system: withSystemCache(req.system, req.turnContext),
+            messages: applyMessageCache(toApiMessages(req)),
+            stream: true,
+            tools: req.tools.map((t) => ({
+                name: t.name,
+                description: t.description,
+                input_schema: t.inputSchema,
+            })),
+        };
+        const effort = anthropicEffort(req.effort, req.model);
+        if (effort)
+            Object.assign(body, effort);
+        const headers = {
+            "content-type": "application/json",
+            "x-api-key": this.apiKey,
+            "anthropic-version": VERSION,
+        };
+        if (wants1m(req.model, process.env))
+            headers["anthropic-beta"] = CONTEXT_1M_BETA;
+        const res = await fetch(API_URL, {
+            method: "POST",
+            signal: req.signal,
+            headers,
+            body: JSON.stringify(body),
+        });
+        const limits = planLimitsFromHeaders(this.id, res.headers);
+        if (!res.ok || !res.body) {
+            const detail = await res.text().catch(() => res.statusText);
+            return {
+                text: messaggioErroreTurno("provider Anthropic", res.status, detail),
+                toolCalls: [],
+                stopReason: "error",
+                ...(limits ? { limits } : {}),
+            };
+        }
+        const turn = await parseStream(res.body, req.onDelta, req.onActivity, req.onReasoning, req.onToolDelta);
+        return limits ? { ...turn, limits } : turn;
+    }
+}
+// Parsing dello stream SSE. Accumula testo e tool_use a blocchi.
+export async function parseStream(body, onDelta, onActivity, onReasoning, onToolDelta) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let text = "";
+    let stopReason;
+    let sawTerminal = false;
+    let streamError;
+    let readError;
+    let usage;
+    // Blocchi tool_use in costruzione, indicizzati per content-block index.
+    const partial = new Map();
+    const toolCalls = [];
+    // Soglia di byte gia' segnalata per ogni tool, per non spammare onActivity.
+    const announced = new Map();
+    const processLine = (line) => {
+        if (streamError || !line.startsWith("data:"))
+            return;
+        const data = line.slice(5).trim();
+        if (!data || data === "[DONE]")
+            return;
+        let evt;
+        try {
+            evt = JSON.parse(data);
+        }
+        catch {
+            streamError = "Risposta Anthropic non valida: evento SSE JSON illeggibile.";
+            return;
+        }
+        debugStreamEvent(evt);
+        const providerError = readProviderError(evt);
+        if (providerError) {
+            streamError = providerError;
+            stopReason = "error";
+            sawTerminal = true;
+            return;
+        }
+        handleEvent(evt, partial, toolCalls, (t) => {
+            text += t;
+            onDelta?.(t);
+        }, onActivity, announced, onReasoning, onToolDelta);
+        const sr = readStopReason(evt);
+        if (sr) {
+            stopReason = sr;
+            sawTerminal = true;
+        }
+        else if (hasUnknownStopReason(evt)) {
+            const delta = evt["delta"];
+            streamError = `Risposta Anthropic terminata con stop_reason non supportato: ${String(delta["stop_reason"])}.`;
+            stopReason = "error";
+            sawTerminal = true;
+        }
+        else if (evt["type"] === "message_stop") {
+            // `message_stop` e' il terminale semantico dello stream Anthropic. In
+            // assenza del precedente message_delta, il solo esito sicuro e' end.
+            stopReason ??= "end";
+            sawTerminal = true;
+        }
+        const u = readUsage(evt);
+        if (u)
+            usage = u;
+    };
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            for (const line of lines)
+                processLine(line);
+        }
+    }
+    catch (err) {
+        readError = err;
+    }
+    // TextDecoder puo' trattenere byte multibyte e l'ultimo evento SSE puo'
+    // arrivare senza newline: entrambi vanno processati prima di valutare l'EOF.
+    buffer += decoder.decode();
+    if (buffer)
+        for (const line of buffer.split("\n"))
+            processLine(line);
+    if (streamError) {
+        return { text: streamError, toolCalls: [], stopReason: "error", usage };
+    }
+    if (!sawTerminal) {
+        return prematureStreamTurn("Anthropic", text, readError, usage);
+    }
+    for (const p of partial.values()) {
+        // Preferisci il JSON streammato; se manca o e' troncato, ripiega sul seed
+        // (input inline ricevuto in content_block_start).
+        let input = {};
+        const tryParse = (raw) => {
+            if (!raw)
+                return null;
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+        };
+        const parsed = tryParse(p.json) ?? tryParse(p.seedJson ?? "");
+        input = parsed ?? {};
+        // JSON arrivato ma illeggibile = troncato a meta'. Un tool call senza
+        // argomenti (`{}` legittimo) non ha JSON da parsare, quindi i due casi
+        // restano distinti.
+        const rawChars = (p.json || p.seedJson || "").length;
+        toolCalls.push({
+            type: "tool_call",
+            id: p.id,
+            name: p.name,
+            input,
+            ...(parsed === null && rawChars > 0 ? { inputTruncatedChars: rawChars } : {}),
+        });
+    }
+    // Non mascherare il troncamento: se l'output e' stato tagliato (max_tokens),
+    // mantienilo (un tool input grande puo' arrivare spezzato). Altrimenti, con
+    // tool presenti, lo stato e' tool_use.
+    if (toolCalls.length > 0 && stopReason !== "max_tokens")
+        stopReason = "tool_use";
+    return { text, toolCalls, stopReason: stopReason ?? "end", usage };
+}
+function prematureStreamTurn(provider, streamedText, readError, usage) {
+    if (!streamedText) {
+        const detail = readError instanceof Error && readError.message ? ` (${readError.message})` : "";
+        return {
+            text: `Errore di rete: connection closed prima che ${provider} completasse la risposta${detail}.`,
+            toolCalls: [],
+            stopReason: "error",
+            usage,
+        };
+    }
+    return {
+        text: `Risposta ${provider} incompleta: EOF prematuro dopo ${streamedText.length} caratteri; nessuna tool call e' stata eseguita.`,
+        toolCalls: [],
+        stopReason: "error",
+        usage,
+    };
+}
+function handleEvent(evt, partial, _toolCalls, pushText, onActivity, announced, onReasoning, onToolDelta) {
+    const type = evt["type"];
+    if (type === "content_block_start") {
+        const block = evt["content_block"];
+        const index = evt["index"];
+        if (block?.["type"] === "tool_use") {
+            // Alcuni endpoint (incluso l'OAuth dell'abbonamento) consegnano l'input
+            // del tool GIA' COMPLETO qui in content_block.input, senza poi inviare
+            // input_json_delta. Lo usiamo come seed: se poi arrivano delta, vengono
+            // accodati (e se il seed era completo, i delta sostituiscono via parse).
+            const seed = block["input"];
+            const seedJson = seed && typeof seed === "object" && Object.keys(seed).length
+                ? JSON.stringify(seed)
+                : "";
+            partial.set(index, {
+                id: String(block["id"]),
+                name: String(block["name"]),
+                json: "",
+                seedJson,
+            });
+            onToolDelta?.({ id: String(block["id"]), name: String(block["name"]), index, delta: "" });
+            onActivity?.(`preparo ${String(block["name"])}`);
+        }
+        else if (block?.["type"] === "thinking") {
+            // Pensiero esteso: non e' testo, ma il run e' vivo. Segnalalo.
+            onActivity?.("ragiono…");
+            // Alcuni endpoint consegnano il pensiero gia' completo qui invece che a
+            // delta: senza questo, quel ragionamento non lo vedrebbe nessuno.
+            const seme = block["thinking"];
+            if (typeof seme === "string" && seme)
+                onReasoning?.(seme);
+        }
+    }
+    else if (type === "content_block_delta") {
+        const delta = evt["delta"];
+        const index = evt["index"];
+        if (delta?.["type"] === "text_delta") {
+            pushText(String(delta["text"]));
+        }
+        else if (delta?.["type"] === "thinking_delta") {
+            onActivity?.("ragiono…");
+            // Il contenuto del pensiero, non solo il fatto che stia pensando: prima
+            // arrivava fin qui e veniva buttato via.
+            const pezzo = delta["thinking"];
+            if (typeof pezzo === "string" && pezzo)
+                onReasoning?.(pezzo);
+        }
+        else if (delta?.["type"] === "input_json_delta") {
+            const cur = partial.get(index);
+            if (cur) {
+                const piece = String(delta["partial_json"]);
+                cur.json += piece;
+                onToolDelta?.({ id: cur.id, name: cur.name, index, delta: piece });
+                // Segnala il progresso ogni ~2 KB: input grandi (es. write_file di un
+                // file lungo) non sembrano piu' "bloccati".
+                if (onActivity && announced) {
+                    const kb = Math.floor(cur.json.length / 2048);
+                    if (kb > (announced.get(index) ?? 0)) {
+                        announced.set(index, kb);
+                        onActivity(`scrivo ${cur.name} · ${Math.round(cur.json.length / 1024)} KB`);
+                    }
+                }
+            }
+        }
+    }
+}
+function readStopReason(evt) {
+    if (evt["type"] !== "message_delta")
+        return null;
+    const delta = evt["delta"];
+    const reason = delta?.["stop_reason"];
+    if (reason === "tool_use")
+        return "tool_use";
+    if (reason === "max_tokens")
+        return "max_tokens";
+    if (reason === "end_turn" || reason === "stop_sequence")
+        return "end";
+    return null;
+}
+function hasUnknownStopReason(evt) {
+    if (evt["type"] !== "message_delta")
+        return false;
+    const delta = evt["delta"];
+    return delta?.["stop_reason"] !== undefined
+        && delta["stop_reason"] !== null
+        && readStopReason(evt) === null;
+}
+function readProviderError(evt) {
+    const raw = evt["error"];
+    if (evt["type"] !== "error" && raw === undefined)
+        return null;
+    if (typeof raw === "string")
+        return `Errore provider Anthropic: ${raw}`;
+    const kind = String(raw?.["type"] ?? raw?.["code"] ?? "stream_error");
+    const message = String(raw?.["message"] ?? evt["message"] ?? "errore streaming senza dettagli");
+    return `Errore provider Anthropic (${kind}): ${message}${errorTimingDetail(raw)}${errorTimingDetail(evt)}`;
+}
+function readUsage(evt) {
+    const usage = evt["usage"];
+    if (!usage)
+        return undefined;
+    const cacheRead = usage["cache_read_input_tokens"];
+    const cacheWrite = usage["cache_creation_input_tokens"];
+    return {
+        inputTokens: Number(usage["input_tokens"] ?? 0),
+        outputTokens: Number(usage["output_tokens"] ?? 0),
+        ...(cacheRead !== undefined ? { cacheReadTokens: Number(cacheRead) } : {}),
+        ...(cacheWrite !== undefined ? { cacheWriteTokens: Number(cacheWrite) } : {}),
+    };
+}

package/dist/providers/catalog.d.ts

@@ -0,0 +1,15 @@
+export interface ProviderSpec {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: "anthropic" | "openai";
+    readonly envKey: string;
+    readonly baseUrl?: string;
+    readonly baseUrlEnv?: string;
+    readonly defaultBaseUrl?: string;
+    readonly optionalEndpoint?: boolean;
+    readonly models: readonly string[];
+}
+export declare const ANTHROPIC_MODELS: readonly ["claude-fable-5-1", "claude-fable-5", "claude-opus-5", "claude-sonnet-5", "claude-haiku-4-5-20251001", "claude-opus-4-8", "claude-sonnet-4-6"];
+export declare const OPENAI_MODELS: readonly ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-4o", "gpt-4o-mini", "o3", "o4-mini"];
+export declare const CHATGPT_MODELS: readonly ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-6-astra", "gpt-5-codex", "gpt-5", "gpt-5-mini", "o4-mini"];
+export declare const PROVIDER_CATALOG: readonly ProviderSpec[];