atom-agent 0.3.0 → 1.1.0

package/dist/kilo.js

@@ -0,0 +1,343 @@
+// Kilo Gateway provider (ATOM's default provider).
+//
+// Kilo exposes an OpenAI-compatible surface:
+//   GET  {base}/models
+//   POST {base}/chat/completions
+// Chat/streaming/tool-call wire behavior is the shared OpenAI-chat path in
+// src/zen.ts — this module owns ONLY Kilo-specific concerns:
+//   - endpoint constants + header construction (auth is optional: free
+//     `:free` models work anonymously, so no Authorization header is sent
+//     when no key is configured)
+//   - dynamic catalog parsing into ATOM's normalized model representation
+//   - free-model detection (`:free` suffix, incl. the `kilo-auto/free`
+//     dynamic routing model)
+//   - TTL-cached discovery (manual refresh clears it)
+//   - provider-specific error normalization (concise, actionable, key-free)
+//
+// Nothing here is imported by other providers: no Kilo behavior leaks.
+export const KILO_BASE_URL = "https://api.kilo.ai/api/gateway";
+export const KILO_CHAT_ENDPOINT = `${KILO_BASE_URL}/chat/completions`;
+export const KILO_MODELS_URL = `${KILO_BASE_URL}/models`;
+// Env var names in precedence order (mirrors the ProviderDef.envVars shape;
+// the registry entry is the single declaration point).
+export const KILO_ENV_VARS = ["KILO_API_KEY"];
+// Dynamic routing model: Kilo picks a free model server-side. Preferred
+// whenever the user has no API key and the live catalog exposes it — but
+// never assumed present (the catalog is authoritative, see
+// preferFreeKiloModel).
+export const KILO_AUTO_MODEL = "kilo-auto/free";
+// Offline placeholder only: the live /models list is authoritative. Kept to
+// one routing id (not a catalog) so nothing here goes stale as Kilo changes
+// its models.
+export const KILO_FALLBACK_MODELS = [KILO_AUTO_MODEL];
+// Discovery cache TTL: 5 minutes. The App also keeps successful lists in its
+// session cache; this TTL bounds gateway hits across provider switches while
+// staying fresh enough for a changing catalog.
+export const KILO_MODELS_TTL_MS = 5 * 60 * 1000;
+// A model is free when its id carries the `:free` suffix (Kilo's free-model
+// convention) or names the free routing slot (`<provider>/free`, e.g.
+// `kilo-auto/free`), or its catalog pricing is explicitly zero. Unknown
+// pricing is NOT free — never assume.
+export function isFreeKiloModel(id) {
+    if (id.endsWith(":free"))
+        return true;
+    if (/\/free$/.test(id))
+        return true;
+    return false;
+}
+function finiteCount(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? Math.floor(value)
+        : undefined;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function entryId(entry) {
+    if (typeof entry === "string")
+        return entry || null;
+    if (typeof entry !== "object" || entry === null)
+        return null;
+    const e = entry;
+    const id = e["id"] ?? e["name"];
+    return typeof id === "string" && id.length > 0 ? id : null;
+}
+function entryRecord(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return null;
+    return entry;
+}
+function parseContextLength(e) {
+    for (const key of [
+        "context_length",
+        "contextLength",
+        "max_context_length",
+        "maxContextLength",
+        "context_window",
+        "contextWindow",
+    ]) {
+        const hit = finiteCount(e[key]);
+        if (hit !== undefined)
+            return hit;
+    }
+    return undefined;
+}
+function parseCapabilities(e) {
+    const raw = e["capabilities"] ?? e["supported_parameters"] ?? e["supportedParameters"];
+    if (!Array.isArray(raw))
+        return undefined;
+    const out = raw.filter((v) => typeof v === "string" && v.length > 0);
+    return out.length > 0 ? out : undefined;
+}
+function parsePricing(e) {
+    const raw = e["pricing"];
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const p = raw;
+    const num = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : undefined;
+    // Kilo/OpenRouter-style pricing may be a decimal string ("0") — accept it.
+    const coerce = (v) => {
+        if (typeof v === "number")
+            return num(v);
+        if (typeof v === "string" && v.trim().length > 0) {
+            const n = Number(v.trim());
+            return Number.isFinite(n) && n >= 0 ? n : undefined;
+        }
+        return undefined;
+    };
+    const prompt = coerce(p["prompt"]) ?? coerce(p["input"]);
+    const completion = coerce(p["completion"]) ?? coerce(p["output"]);
+    if (prompt === undefined && completion === undefined)
+        return undefined;
+    return {
+        pricing: {
+            ...(prompt !== undefined ? { prompt } : {}),
+            ...(completion !== undefined ? { completion } : {}),
+        },
+        zero: (prompt ?? 0) === 0 && (completion ?? 0) === 0,
+    };
+}
+function parseToolsSupported(e) {
+    for (const key of [
+        "tools_supported",
+        "toolsSupported",
+        "supports_tools",
+        "supportsTools",
+        "tool_support",
+        "toolSupport",
+    ]) {
+        if (typeof e[key] === "boolean")
+            return e[key];
+    }
+    // Some catalogs advertise function calling via supported parameters.
+    const caps = parseCapabilities(e);
+    if (caps?.some((c) => /tool|function/i.test(c)))
+        return true;
+    return undefined;
+}
+// Parse one catalog entry into the normalized representation. Returns null
+// when the entry carries no usable model id.
+export function parseKiloModelEntry(entry) {
+    const id = entryId(entry);
+    if (!id)
+        return null;
+    const e = entryRecord(entry);
+    const slash = id.indexOf("/");
+    const info = {
+        id,
+        displayName: nonEmptyString(e?.["display_name"] ?? e?.["displayName"] ?? e?.["name"]) ?? id,
+        ...(slash > 0 ? { provider: id.slice(0, slash) } : {}),
+        free: isFreeKiloModel(id),
+    };
+    if (!e)
+        return info;
+    const contextLength = parseContextLength(e);
+    if (contextLength !== undefined)
+        info.contextLength = contextLength;
+    const capabilities = parseCapabilities(e);
+    if (capabilities !== undefined)
+        info.capabilities = capabilities;
+    const pricing = parsePricing(e);
+    if (pricing !== undefined) {
+        info.pricing = pricing.pricing;
+        if (pricing.zero)
+            info.free = true;
+    }
+    const toolsSupported = parseToolsSupported(e);
+    if (toolsSupported !== undefined)
+        info.toolsSupported = toolsSupported;
+    return info;
+}
+function catalogEntries(data) {
+    try {
+        const entries = Array.isArray(data)
+            ? data
+            : data?.data;
+        if (!Array.isArray(entries) || entries.length === 0)
+            return null;
+        return entries;
+    }
+    catch {
+        return null;
+    }
+}
+// Full normalized catalog parse. Malformed payloads yield an empty list
+// (callers fall back to KILO_FALLBACK_MODELS) — never throws.
+export function parseKiloModelInfos(data) {
+    const entries = catalogEntries(data);
+    if (!entries)
+        return [];
+    const out = [];
+    for (const entry of entries) {
+        try {
+            const info = parseKiloModelEntry(entry);
+            if (info)
+                out.push(info);
+        }
+        catch {
+            // One bad entry must not drop the whole catalog.
+        }
+    }
+    return out;
+}
+// Picker-compatible id list from a catalog payload. ANY failure (malformed
+// payload, zero usable ids) returns the fallback — never throws.
+export function parseKiloModelsList(data, fallback = KILO_FALLBACK_MODELS) {
+    const infos = parseKiloModelInfos(data);
+    if (infos.length === 0)
+        return [...fallback];
+    return infos.map((m) => m.id);
+}
+// Default pick for a fresh session without an API key: the exposed
+// `kilo-auto/free` routing model when present, else the first `:free` model,
+// else the first live id, else the offline fallback. Never assumes a
+// specific free model exists beyond what the catalog exposes.
+export function preferFreeKiloModel(models, fallback = KILO_AUTO_MODEL) {
+    if (models.length === 0)
+        return fallback;
+    const auto = models.find((m) => m === KILO_AUTO_MODEL);
+    if (auto)
+        return auto;
+    const free = models.find((m) => isFreeKiloModel(m));
+    if (free)
+        return free;
+    return models[0];
+}
+// ---- Headers (auth optional) ----
+// Free `:free` models work anonymously: no Authorization header is sent when
+// no key is configured (never an empty `Bearer `). No Kilo-specific,
+// identity-spoofing, or bypass headers are ever sent — plain
+// OpenAI-compatible auth only.
+export function kiloHeaders(apiKey) {
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    if (apiKey)
+        headers["Authorization"] = `Bearer ${apiKey}`;
+    return headers;
+}
+const kiloModelsCache = new Map();
+function cacheKey(hasKey) {
+    // Anonymous and authenticated catalogs can differ (paid models appear
+    // with a key), so they cache separately.
+    return hasKey ? "auth" : "anon";
+}
+function readKiloCache(hasKey, now = Date.now()) {
+    const slot = kiloModelsCache.get(cacheKey(hasKey));
+    if (!slot)
+        return undefined;
+    if (now - slot.at > KILO_MODELS_TTL_MS) {
+        kiloModelsCache.delete(cacheKey(hasKey));
+        return undefined;
+    }
+    return slot.status;
+}
+// Manual refresh path: clears the discovery cache so the next fetch hits
+// `/models` again (used by `/models refresh` and provider switches).
+export function clearKiloModelsCache() {
+    kiloModelsCache.clear();
+}
+// GET the live catalog. Anonymous when apiKey is "" (free models only);
+// authenticated otherwise. ANY failure returns the offline fallback with
+// ok:false (callers keep failures uncached) — never throws.
+export async function fetchKiloModelsWithStatus(apiKey) {
+    const hasKey = apiKey.length > 0;
+    const cached = readKiloCache(hasKey);
+    if (cached)
+        return cached;
+    const fallback = {
+        models: [...KILO_FALLBACK_MODELS],
+        infos: [],
+        ok: false,
+    };
+    try {
+        const res = await fetch(KILO_MODELS_URL, { headers: kiloHeaders(apiKey) });
+        if (!res.ok)
+            return fallback;
+        let data;
+        try {
+            data = await res.json();
+        }
+        catch {
+            return fallback;
+        }
+        const infos = parseKiloModelInfos(data);
+        if (infos.length === 0)
+            return fallback;
+        const status = {
+            models: infos.map((m) => m.id),
+            infos,
+            ok: true,
+        };
+        kiloModelsCache.set(cacheKey(hasKey), { at: Date.now(), status });
+        return status;
+    }
+    catch {
+        return fallback;
+    }
+}
+// ---- Error normalization ----
+// Concise, actionable TUI errors. Never includes the API key, raw bodies, or
+// HTTP dumps (callers truncate bodies before this point). `hasKey` selects
+// the anonymous vs authenticated wording for 429s.
+export function kiloErrorMessage(status, hasKey) {
+    switch (status) {
+        case 401:
+            return "Kilo: API key is invalid.";
+        case 403:
+            return "Kilo: access forbidden for this model or key.";
+        case 404:
+            return "Kilo: model is unavailable.";
+        case 429:
+            return hasKey
+                ? "Kilo: rate limit reached — wait a moment, then resend."
+                : "Kilo: anonymous free-model rate limit reached.";
+        case 500:
+        case 502:
+        case 503:
+        case 504:
+            return "Kilo: gateway temporarily unavailable.";
+        default:
+            return `Kilo: request failed (HTTP ${status}).`;
+    }
+}
+// Reframe a chat-POST failure thrown by the shared OpenAI-chat path
+// (`Kilo HTTP {status}: ...`) into the normalized message above, preserving
+// non-HTTP failures (network throws, truncation, empty replies) for their
+// own handling. Never throws; unknown shapes pass through untouched.
+export function normalizeKiloChatError(error, apiKey) {
+    if (!(error instanceof Error))
+        return error;
+    const m = /^Kilo HTTP (\d+):/.exec(error.message);
+    if (!m)
+        return error;
+    const status = Number(m[1]);
+    if (!Number.isFinite(status))
+        return error;
+    return new Error(kiloErrorMessage(status, apiKey.length > 0));
+}
+// Human drift-guard for the TUI: connection-level failures (no HTTP status
+// at all) get the gateway wording instead of a bare fetch throw.
+export function kiloNetworkErrorMessage() {
+    return "Kilo: gateway temporarily unavailable.";
+}

package/dist/local-discovery.js

@@ -0,0 +1,308 @@
+// Local LLM auto-discovery: Ollama, LM Studio, llama.cpp (llama-server).
+//
+// On startup ATOM probes the three standard local endpoints in parallel
+// with short timeouts, normalizes whatever models each runtime exposes,
+// and hands the lists to the existing provider/model registry — local
+// models then ride the normal openai-chat path (chatCompletionForProvider
+// + runLoopWithChat), never a parallel agent implementation.
+//
+// Endpoint facts (verified 2026-09-09 against ollama/ollama + llama.cpp docs):
+// - Ollama: native GET {base}/api/tags -> {models:[{name,model,size,digest,
+//   details:{format,family,families,parameter_size,quantization_level}}]};
+//   OpenAI-compatible {base}/v1/chat/completions (streaming, tools, vision,
+//   reasoning) + {base}/v1/models as fallback listing. api_key ignored.
+// - LM Studio: OpenAI-compatible {base}/v1/models -> {data:[{id,...}]}.
+// - llama-server: GET {base}/v1/models -> {object:"list",data:[{id,
+//   owned_by:"llamacpp",meta:{...n_ctx_train...}|null}]} — always a single
+//   element (the loaded model); id defaults to the model file path unless
+//   --alias is set. Bearer auth accepted-and-ignored.
+//
+// Honesty rules: capabilities stay unknown (undefined) unless a response
+// exposes them (llama-server meta.n_ctx_train -> contextLength). Nothing is
+// fabricated. Unreachable/malformed servers yield ok:false, never throw —
+// discovery failures are isolated per provider and silent by default (the
+// TUI surfaces them only via /models).
+//
+// Concurrency: createLocalDiscovery() owns one in-flight promise per scope
+// ("all" or one provider id), so overlapping refresh calls share work and
+// never race the snapshot. Results live in memory only — refresh
+// re-discovers, disappeared servers flip to ok:false with empty models.
+import { getProvider, LOCAL_PROVIDER_IDS, normalizeBaseURL, } from "./providers.js";
+// Short by design: a dead local server must not delay startup.
+export const DISCOVERY_TIMEOUT_MS = 2000;
+export function discoveryBaseURL(provider, override) {
+    const stored = (override ?? "").trim();
+    if (stored)
+        return normalizeBaseURL(stored);
+    const def = getProvider(provider);
+    const envVar = def?.local?.baseURLEnvVar;
+    const fromEnv = envVar ? (process.env[envVar] ?? "").trim() : "";
+    if (fromEnv)
+        return normalizeBaseURL(fromEnv);
+    return def?.local?.defaultBaseURL ?? "";
+}
+function initialResult(provider) {
+    return {
+        provider,
+        baseURL: discoveryBaseURL(provider),
+        ok: false,
+        models: [],
+    };
+}
+export function emptyLocalSnapshot() {
+    return {
+        results: {
+            ollama: initialResult("ollama"),
+            lmstudio: initialResult("lmstudio"),
+            llamacpp: initialResult("llamacpp"),
+        },
+        version: 0,
+    };
+}
+// One-line human summary for /models output (counts only, no transcript spam).
+export function summarizeLocalSnapshot(snap) {
+    const parts = LOCAL_PROVIDER_IDS.map((id) => {
+        const r = snap.results[id];
+        const name = getProvider(id)?.name ?? id;
+        if (!r.ok)
+            return `${name}: unavailable`;
+        return `${name}: ${r.models.length} model${r.models.length === 1 ? "" : "s"}`;
+    });
+    return `local models — ${parts.join(" · ")}`;
+}
+// ---- HTTP plumbing (short timeout, never hangs) ---------------------------
+function timeoutSignal(ms) {
+    try {
+        const withTimeout = AbortSignal;
+        if (typeof withTimeout.timeout === "function")
+            return withTimeout.timeout(ms);
+    }
+    catch {
+        // fall through: no timeout support, plain fetch
+    }
+    return undefined;
+}
+async function fetchJson(url, deps) {
+    const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+    const timeoutMs = deps.timeoutMs ?? DISCOVERY_TIMEOUT_MS;
+    const signal = timeoutSignal(timeoutMs);
+    let res;
+    try {
+        if (signal) {
+            res = await fetchImpl(url, {
+                method: "GET",
+                headers: { Accept: "application/json" },
+                signal,
+            });
+        }
+        else {
+            // No AbortSignal.timeout on this runtime: manual race so a dead
+            // server still cannot hang discovery past the timeout.
+            let timer;
+            try {
+                res = await Promise.race([
+                    fetchImpl(url, { method: "GET", headers: { Accept: "application/json" } }),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error("timeout")), timeoutMs);
+                    }),
+                ]);
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            }
+        }
+    }
+    catch (e) {
+        throw new Error(e instanceof Error ? e.message : "fetch failed");
+    }
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    try {
+        return (await res.json());
+    }
+    catch {
+        throw new Error("invalid JSON");
+    }
+}
+// ---- Pure response parsers (null = unusable shape) -------------------------
+function asRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v)
+        ? v
+        : null;
+}
+function finiteNumber(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+function modelIdOf(entry) {
+    if (typeof entry === "string")
+        return entry || null;
+    const o = asRecord(entry);
+    if (!o)
+        return null;
+    const id = o["id"] ?? o["name"];
+    return typeof id === "string" && id.length > 0 ? id : null;
+}
+// Ollama native listing: {models:[{name|model,size,details:{...}}]}.
+export function parseOllamaTagsPayload(data) {
+    try {
+        const o = asRecord(data);
+        const list = o?.["models"];
+        if (!Array.isArray(list))
+            return null;
+        const out = [];
+        for (const entry of list) {
+            const r = asRecord(entry);
+            const raw = r ? (r["name"] ?? r["model"]) : null;
+            if (typeof raw !== "string" || raw.length === 0)
+                continue;
+            const m = { id: raw, capabilities: {} };
+            const size = r ? finiteNumber(r["size"]) : undefined;
+            if (size !== undefined && size > 0)
+                m.sizeBytes = size;
+            const details = r ? asRecord(r["details"]) : null;
+            if (details) {
+                const family = details["family"];
+                if (typeof family === "string" && family.length > 0)
+                    m.family = family;
+                const params = details["parameter_size"];
+                if (typeof params === "string" && params.length > 0)
+                    m.parameterSize = params;
+            }
+            out.push(m);
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+// OpenAI-shape listing: {data:[{id,meta?}]}. Used by LM Studio, llama-server,
+// and as the Ollama fallback. llama-server meta.n_ctx_train (when a finite
+// number) becomes contextLength; everything else stays unknown.
+export function parseOpenAIModelsPayload(data) {
+    try {
+        const o = asRecord(data);
+        const list = o?.["data"];
+        if (!Array.isArray(list))
+            return null;
+        const out = [];
+        for (const entry of list) {
+            const id = modelIdOf(entry);
+            if (!id)
+                continue;
+            const m = { id, capabilities: {} };
+            const meta = asRecord(entry) ? asRecord(asRecord(entry)["meta"]) : null;
+            const nCtx = meta ? finiteNumber(meta["n_ctx_train"]) : undefined;
+            if (nCtx !== undefined && nCtx > 0) {
+                m.contextLength = Math.floor(nCtx);
+                m.capabilities = { ...m.capabilities, contextLength: Math.floor(nCtx) };
+            }
+            out.push(m);
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+// ---- Per-runtime discoverers (never throw) ----------------------------------
+function fail(provider, baseURL, error) {
+    return { provider, baseURL, ok: false, models: [], error };
+}
+export async function discoverOllama(deps = {}) {
+    const baseURL = discoveryBaseURL("ollama", deps.baseURL);
+    if (!baseURL)
+        return fail("ollama", "", "no base URL");
+    try {
+        const tags = await fetchJson(`${baseURL}/api/tags`, deps);
+        const parsed = parseOllamaTagsPayload(tags);
+        if (parsed !== null)
+            return { provider: "ollama", baseURL, ok: true, models: parsed };
+    }
+    catch {
+        // fall through to the OpenAI-compatible listing
+    }
+    try {
+        const compat = await fetchJson(`${baseURL}/v1/models`, deps);
+        const parsed = parseOpenAIModelsPayload(compat);
+        if (parsed !== null)
+            return { provider: "ollama", baseURL, ok: true, models: parsed };
+        return fail("ollama", baseURL, "malformed response");
+    }
+    catch (e) {
+        return fail("ollama", baseURL, e instanceof Error ? e.message : "fetch failed");
+    }
+}
+async function discoverOpenAICompatible(provider, deps = {}) {
+    const baseURL = discoveryBaseURL(provider, deps.baseURL);
+    if (!baseURL)
+        return fail(provider, "", "no base URL");
+    try {
+        const data = await fetchJson(`${baseURL}/v1/models`, deps);
+        const parsed = parseOpenAIModelsPayload(data);
+        if (parsed === null)
+            return fail(provider, baseURL, "malformed response");
+        return { provider, baseURL, ok: true, models: parsed };
+    }
+    catch (e) {
+        return fail(provider, baseURL, e instanceof Error ? e.message : "fetch failed");
+    }
+}
+export async function discoverLMStudio(deps = {}) {
+    return discoverOpenAICompatible("lmstudio", deps);
+}
+export async function discoverLlamaCpp(deps = {}) {
+    return discoverOpenAICompatible("llamacpp", deps);
+}
+export async function discoverLocalProvider(provider, deps = {}) {
+    try {
+        if (provider === "ollama")
+            return await discoverOllama(deps);
+        if (provider === "lmstudio")
+            return await discoverLMStudio(deps);
+        return await discoverLlamaCpp(deps);
+    }
+    catch (e) {
+        return fail(provider, discoveryBaseURL(provider, deps.baseURL), e instanceof Error ? e.message : "fetch failed");
+    }
+}
+export function createLocalDiscovery(deps = {}) {
+    let snap = emptyLocalSnapshot();
+    const inFlight = new Map();
+    const runAll = async () => {
+        const [ollama, lmstudio, llamacpp] = await Promise.all([
+            discoverLocalProvider("ollama", deps),
+            discoverLocalProvider("lmstudio", deps),
+            discoverLocalProvider("llamacpp", deps),
+        ]);
+        snap = {
+            results: { ollama, lmstudio, llamacpp },
+            version: snap.version + 1,
+        };
+        return snap;
+    };
+    const runOne = async (provider) => {
+        const res = await discoverLocalProvider(provider, deps);
+        snap = {
+            results: { ...snap.results, [provider]: res },
+            version: snap.version + 1,
+        };
+        return snap;
+    };
+    return {
+        snapshot: () => snap,
+        refresh: (provider) => {
+            const key = provider ?? "all";
+            const existing = inFlight.get(key);
+            if (existing)
+                return existing;
+            const p = (provider ? runOne(provider) : runAll()).finally(() => {
+                if (inFlight.get(key) === p)
+                    inFlight.delete(key);
+            });
+            inFlight.set(key, p);
+            return p;
+        },
+    };
+}