@kal-elsam/kairo-runtime 0.1.4 → 0.2.0

package/src/global/intelligence/backends/custom-http.js

@@ -0,0 +1,175 @@
+import {
+  BACKEND_IDS,
+  COST_CLASSES,
+  PRIVACY_CLASSES,
+  createModelDescriptor
+} from "../types.js";
+import { fetchJson } from "../http.js";
+import { CAPABILITY_STATES } from "../../capability-states.js";
+import { classifyCustomBaseUrl, isValidEnvironmentName } from "../custom-url.js";
+
+/**
+ * OpenAI-compatible HTTP backend. API keys are read from env by name only —
+ * never from profile JSON or disk.
+ */
+export function createCustomHttpBackend({
+  id = BACKEND_IDS.CUSTOM,
+  label = "Custom provider",
+  baseUrl,
+  modelId,
+  apiKeyEnv = null,
+  local: _local = false,
+  fetchImpl = globalThis.fetch,
+  env = process.env
+} = {}) {
+  if (!baseUrl) {
+    throw new Error("Custom HTTP backend requires baseUrl.");
+  }
+
+  const location = classifyCustomBaseUrl(baseUrl);
+  const normalizedBase = location.normalizedBaseUrl;
+  if (apiKeyEnv != null && !isValidEnvironmentName(apiKeyEnv)) {
+    throw new Error("Custom provider apiKeyEnv must be a valid uppercase environment variable name.");
+  }
+  if (apiKeyEnv && !location.local) {
+    throw new Error(
+      "Remote custom providers cannot use apiKeyEnv in 0.2.0; use a built-in provider or a local endpoint."
+    );
+  }
+  const apiKey = apiKeyEnv ? (env[apiKeyEnv] ?? null) : null;
+
+  return {
+    id,
+    label,
+    local: location.local,
+
+    async detect() {
+      if (apiKeyEnv && !apiKey) {
+        return {
+          id,
+          label,
+          state: CAPABILITY_STATES.UNKNOWN,
+          detected: false,
+          available: false,
+          hasApiKey: false,
+          error: null,
+          recommendation: `Set ${apiKeyEnv} in the environment. Kairo never stores credentials.`
+        };
+      }
+
+      return {
+        id,
+        label,
+        state: CAPABILITY_STATES.DETECTED,
+        detected: true,
+        available: Boolean(modelId),
+        hasApiKey: apiKeyEnv ? Boolean(apiKey) : null,
+        error: null,
+        recommendation: modelId
+          ? `Custom provider configured (${modelId}).`
+          : "Custom provider baseUrl set; configure modelId in profile."
+      };
+    },
+
+    async listModels() {
+      if (!modelId) return [];
+      return [
+        createModelDescriptor({
+          provider: id,
+          modelId,
+          local: location.local,
+          costClass: location.local ? COST_CLASSES.LOCAL : COST_CLASSES.UNKNOWN,
+          privacyClass: location.local ? PRIVACY_CLASSES.LOCAL : PRIVACY_CLASSES.CLOUD,
+          opaque: true
+        })
+      ];
+    },
+
+    async capabilities() {
+      const detection = await this.detect();
+      return {
+        id,
+        local: location.local,
+        cloud: !location.local,
+        requiresApiKey: Boolean(apiKeyEnv),
+        requiresConsent: !location.local,
+        streaming: false,
+        tools: false,
+        state: detection.state,
+        baseUrl: normalizedBase,
+        modelId
+      };
+    },
+
+    async invoke(contextPack, request = {}) {
+      if (apiKeyEnv && !apiKey) {
+        return invokeError(id, `Missing ${apiKeyEnv}. Kairo never stores credentials.`);
+      }
+
+      const resolvedModel = request.modelId ?? modelId;
+      if (!resolvedModel) {
+        return invokeError(id, "Custom invoke requires modelId.");
+      }
+
+      const messages = [];
+      if (contextPack?.systemPrompt) {
+        messages.push({ role: "system", content: contextPack.systemPrompt });
+      }
+      if (Array.isArray(request.messages) && request.messages.length > 0) {
+        messages.push(...request.messages);
+      } else if (request.prompt) {
+        messages.push({ role: "user", content: request.prompt });
+      }
+
+      const headers = { "Content-Type": "application/json" };
+      if (apiKey && location.credentialSafe) headers.Authorization = `Bearer ${apiKey}`;
+
+      const result = await fetchJson(`${normalizedBase}/chat/completions`, {
+        method: "POST",
+        headers,
+        body: {
+          model: resolvedModel,
+          messages,
+          stream: false
+        },
+        timeoutMs: request.timeoutMs ?? 120000,
+        fetchImpl
+      });
+
+      if (!result.ok) {
+        return invokeError(id, result.error ?? "Custom provider chat failed.");
+      }
+
+      const content = result.data?.choices?.[0]?.message?.content ?? "";
+      const usage = result.data?.usage ?? {};
+
+      return {
+        ok: true,
+        backendId: id,
+        model: resolvedModel,
+        content,
+        usage: {
+          inputTokens: usage.prompt_tokens ?? null,
+          outputTokens: usage.completion_tokens ?? null,
+          cachedTokens: null,
+          estimatedCost: null,
+          model: resolvedModel,
+          backendId: id,
+          fallbackUsed: false
+        },
+        raw: result.data
+      };
+    }
+  };
+}
+
+function invokeError(backendId, message) {
+  return {
+    ok: false,
+    backendId,
+    model: null,
+    content: null,
+    error: message,
+    usage: null
+  };
+}

package/src/global/intelligence/backends/ollama.js

@@ -0,0 +1,164 @@
+import {
+  BACKEND_IDS,
+  COST_CLASSES,
+  DEFAULT_OLLAMA_HOST,
+  PRIVACY_CLASSES,
+  createModelDescriptor
+} from "../types.js";
+import { fetchJson } from "../http.js";
+import { CAPABILITY_STATES } from "../../capability-states.js";
+
+export function createOllamaBackend({
+  host = null,
+  fetchImpl = globalThis.fetch,
+  env = process.env
+} = {}) {
+  const baseUrl = normalizeOllamaHost(host ?? env.OLLAMA_HOST ?? DEFAULT_OLLAMA_HOST);
+
+  return {
+    id: BACKEND_IDS.OLLAMA,
+    label: "Ollama",
+    local: true,
+
+    async detect() {
+      const result = await fetchJson(`${baseUrl}/api/tags`, {
+        timeoutMs: 2000,
+        fetchImpl
+      });
+
+      if (!result.ok) {
+        return {
+          id: BACKEND_IDS.OLLAMA,
+          label: "Ollama",
+          state: CAPABILITY_STATES.UNKNOWN,
+          detected: false,
+          available: false,
+          host: baseUrl,
+          error: result.error,
+          recommendation: `Start Ollama locally (${DEFAULT_OLLAMA_HOST}) or set OLLAMA_HOST.`
+        };
+      }
+
+      const models = parseOllamaModels(result.data);
+      return {
+        id: BACKEND_IDS.OLLAMA,
+        label: "Ollama",
+        state: models.length > 0 ? CAPABILITY_STATES.AVAILABLE : CAPABILITY_STATES.DETECTED,
+        detected: true,
+        available: models.length > 0,
+        host: baseUrl,
+        modelCount: models.length,
+        error: null,
+        recommendation: models.length > 0
+          ? `Ollama ready with ${models.length} local model(s).`
+          : "Ollama is running but no models are pulled yet."
+      };
+    },
+
+    async listModels() {
+      const result = await fetchJson(`${baseUrl}/api/tags`, { fetchImpl });
+      if (!result.ok) return [];
+      return parseOllamaModels(result.data);
+    },
+
+    async capabilities() {
+      const detection = await this.detect();
+      return {
+        id: BACKEND_IDS.OLLAMA,
+        local: true,
+        cloud: false,
+        requiresApiKey: false,
+        requiresConsent: false,
+        streaming: true,
+        tools: false,
+        state: detection.state,
+        host: baseUrl
+      };
+    },
+
+    async invoke(contextPack, request = {}) {
+      const modelId = request.modelId;
+      if (!modelId) {
+        return invokeError("Ollama invoke requires modelId.");
+      }
+
+      const messages = buildChatMessages(contextPack, request);
+      const result = await fetchJson(`${baseUrl}/api/chat`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: {
+          model: modelId,
+          messages,
+          stream: false,
+          options: request.options ?? undefined
+        },
+        timeoutMs: request.timeoutMs ?? 120000,
+        fetchImpl
+      });
+
+      if (!result.ok) {
+        return invokeError(result.error ?? "Ollama chat failed.");
+      }
+
+      const content = result.data?.message?.content ?? "";
+      return {
+        ok: true,
+        backendId: BACKEND_IDS.OLLAMA,
+        model: modelId,
+        content,
+        usage: {
+          inputTokens: result.data?.prompt_eval_count ?? null,
+          outputTokens: result.data?.eval_count ?? null,
+          cachedTokens: null,
+          estimatedCost: 0,
+          model: modelId,
+          backendId: BACKEND_IDS.OLLAMA,
+          fallbackUsed: false
+        },
+        raw: result.data
+      };
+    }
+  };
+}
+
+function parseOllamaModels(data) {
+  const models = Array.isArray(data?.models) ? data.models : [];
+  return models.map((entry) => createModelDescriptor({
+    provider: BACKEND_IDS.OLLAMA,
+    modelId: entry.name ?? entry.model,
+    local: true,
+    costClass: COST_CLASSES.LOCAL,
+    privacyClass: PRIVACY_CLASSES.LOCAL,
+    contextLimit: null,
+    tools: false,
+    reasoning: false
+  })).filter((entry) => Boolean(entry.modelId));
+}
+
+function normalizeOllamaHost(host) {
+  return String(host).replace(/\/+$/, "");
+}
+
+function buildChatMessages(contextPack, request) {
+  const messages = [];
+  if (contextPack?.systemPrompt) {
+    messages.push({ role: "system", content: contextPack.systemPrompt });
+  }
+  if (Array.isArray(request.messages) && request.messages.length > 0) {
+    messages.push(...request.messages);
+  } else if (request.prompt) {
+    messages.push({ role: "user", content: request.prompt });
+  }
+  return messages;
+}
+
+function invokeError(message) {
+  return {
+    ok: false,
+    backendId: BACKEND_IDS.OLLAMA,
+    model: null,
+    content: null,
+    error: message,
+    usage: null
+  };
+}

package/src/global/intelligence/backends/openrouter.js

@@ -0,0 +1,198 @@
+import {
+  BACKEND_IDS,
+  COST_CLASSES,
+  OPENROUTER_FREE_MODEL,
+  PRIVACY_CLASSES,
+  createModelDescriptor
+} from "../types.js";
+import { fetchJson } from "../http.js";
+import { CAPABILITY_STATES } from "../../capability-states.js";
+
+const OPENROUTER_BASE = "https://openrouter.ai/api/v1";
+
+export function createOpenRouterBackend({
+  fetchImpl = globalThis.fetch,
+  env = process.env,
+  apiKey = null
+} = {}) {
+  const resolvedKey = apiKey ?? env.OPENROUTER_API_KEY ?? null;
+
+  return {
+    id: BACKEND_IDS.OPENROUTER,
+    label: "OpenRouter",
+    local: false,
+
+    async detect() {
+      if (!resolvedKey) {
+        return {
+          id: BACKEND_IDS.OPENROUTER,
+          label: "OpenRouter",
+          state: CAPABILITY_STATES.UNKNOWN,
+          detected: false,
+          available: false,
+          hasApiKey: false,
+          error: null,
+          recommendation: "Set OPENROUTER_API_KEY in the environment to enable OpenRouter (never stored by Kairo)."
+        };
+      }
+
+      return {
+        id: BACKEND_IDS.OPENROUTER,
+        label: "OpenRouter",
+        state: CAPABILITY_STATES.AUTHENTICATED,
+        detected: true,
+        available: true,
+        hasApiKey: true,
+        error: null,
+        recommendation: "OpenRouter API key detected in environment. Cloud use still requires explicit consent."
+      };
+    },
+
+    async listModels({ freeOnly = true } = {}) {
+      if (!resolvedKey) return [];
+
+      const result = await fetchJson(`${OPENROUTER_BASE}/models`, {
+        headers: {
+          Authorization: `Bearer ${resolvedKey}`,
+          "Content-Type": "application/json"
+        },
+        fetchImpl
+      });
+
+      if (!result.ok) {
+        return [
+          createModelDescriptor({
+            provider: BACKEND_IDS.OPENROUTER,
+            modelId: OPENROUTER_FREE_MODEL,
+            local: false,
+            costClass: COST_CLASSES.FREE,
+            privacyClass: PRIVACY_CLASSES.CLOUD,
+            opaque: true
+          })
+        ];
+      }
+
+      const models = Array.isArray(result.data?.data) ? result.data.data : [];
+      const mapped = models
+        .filter((entry) => {
+          if (!freeOnly) return true;
+          const id = entry.id ?? "";
+          return id.endsWith(":free") || id === OPENROUTER_FREE_MODEL;
+        })
+        .map((entry) => createModelDescriptor({
+          provider: BACKEND_IDS.OPENROUTER,
+          modelId: entry.id,
+          local: false,
+          costClass: COST_CLASSES.FREE,
+          privacyClass: PRIVACY_CLASSES.CLOUD,
+          contextLimit: entry.context_length ?? null,
+          tools: Boolean(entry.supported_parameters?.includes?.("tools")),
+          reasoning: false
+        }));
+
+      if (!mapped.some((entry) => entry.modelId === OPENROUTER_FREE_MODEL)) {
+        mapped.unshift(createModelDescriptor({
+          provider: BACKEND_IDS.OPENROUTER,
+          modelId: OPENROUTER_FREE_MODEL,
+          local: false,
+          costClass: COST_CLASSES.FREE,
+          privacyClass: PRIVACY_CLASSES.CLOUD,
+          opaque: true
+        }));
+      }
+
+      return mapped;
+    },
+
+    async capabilities() {
+      const detection = await this.detect();
+      return {
+        id: BACKEND_IDS.OPENROUTER,
+        local: false,
+        cloud: true,
+        requiresApiKey: true,
+        requiresConsent: true,
+        streaming: true,
+        tools: true,
+        freeRouterModel: OPENROUTER_FREE_MODEL,
+        state: detection.state,
+        hasApiKey: Boolean(resolvedKey)
+      };
+    },
+
+    async invoke(contextPack, request = {}) {
+      if (!resolvedKey) {
+        return invokeError("OPENROUTER_API_KEY is not set. Kairo never stores credentials.");
+      }
+
+      const modelId = request.modelId ?? OPENROUTER_FREE_MODEL;
+      const messages = buildChatMessages(contextPack, request);
+
+      const result = await fetchJson(`${OPENROUTER_BASE}/chat/completions`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${resolvedKey}`,
+          "Content-Type": "application/json",
+          "HTTP-Referer": "https://github.com/Kal-elSam/harness",
+          "X-OpenRouter-Title": "Kairo Runtime"
+        },
+        body: {
+          model: modelId,
+          messages,
+          stream: false
+        },
+        timeoutMs: request.timeoutMs ?? 120000,
+        fetchImpl
+      });
+
+      if (!result.ok) {
+        return invokeError(result.error ?? "OpenRouter chat failed.");
+      }
+
+      const content = result.data?.choices?.[0]?.message?.content ?? "";
+      const usedModel = result.data?.model ?? modelId;
+      const usage = result.data?.usage ?? {};
+
+      return {
+        ok: true,
+        backendId: BACKEND_IDS.OPENROUTER,
+        model: usedModel,
+        content,
+        usage: {
+          inputTokens: usage.prompt_tokens ?? null,
+          outputTokens: usage.completion_tokens ?? null,
+          cachedTokens: usage.prompt_tokens_details?.cached_tokens ?? null,
+          estimatedCost: null,
+          model: usedModel,
+          backendId: BACKEND_IDS.OPENROUTER,
+          fallbackUsed: usedModel !== modelId
+        },
+        raw: result.data
+      };
+    }
+  };
+}
+
+function buildChatMessages(contextPack, request) {
+  const messages = [];
+  if (contextPack?.systemPrompt) {
+    messages.push({ role: "system", content: contextPack.systemPrompt });
+  }
+  if (Array.isArray(request.messages) && request.messages.length > 0) {
+    messages.push(...request.messages);
+  } else if (request.prompt) {
+    messages.push({ role: "user", content: request.prompt });
+  }
+  return messages;
+}
+
+function invokeError(message) {
+  return {
+    ok: false,
+    backendId: BACKEND_IDS.OPENROUTER,
+    model: null,
+    content: null,
+    error: message,
+    usage: null
+  };
+}