@kal-elsam/kairo-runtime 0.1.5 → 0.2.1

package/src/global/intelligence/custom-url.js

@@ -0,0 +1,82 @@
+import net from "node:net";
+
+const ALLOWED_PROTOCOLS = new Set(["http:", "https:"]);
+const LOCAL_HOSTNAMES = new Set(["localhost", "localhost.localdomain"]);
+const ENV_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
+
+export function classifyCustomBaseUrl(baseUrl) {
+  let parsed;
+  try {
+    parsed = new URL(String(baseUrl));
+  } catch {
+    throw new Error("Custom provider baseUrl must be an absolute http(s) URL.");
+  }
+
+  if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
+    throw new Error("Custom provider baseUrl must use http or https.");
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error("Custom provider baseUrl must not contain embedded credentials.");
+  }
+  if (parsed.search || parsed.hash) {
+    throw new Error("Custom provider baseUrl must not contain a query string or fragment.");
+  }
+
+  const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (!hostname) {
+    throw new Error("Custom provider baseUrl must include a host.");
+  }
+
+  const local = isLocalHostname(hostname);
+  if (!local && parsed.protocol !== "https:") {
+    throw new Error("Remote custom providers must use https; http is allowed only for local/private endpoints.");
+  }
+
+  return {
+    url: parsed,
+    normalizedBaseUrl: parsed.toString().replace(/\/+$/, ""),
+    hostname,
+    local,
+    credentialSafe: local || parsed.protocol === "https:"
+  };
+}
+
+export function isValidEnvironmentName(name) {
+  return typeof name === "string" && ENV_NAME_PATTERN.test(name);
+}
+
+function isLocalHostname(hostname) {
+  if (LOCAL_HOSTNAMES.has(hostname)) return true;
+
+  const version = net.isIP(hostname);
+  if (version === 4) return isPrivateIpv4(hostname);
+  if (version === 6) return isPrivateIpv6(hostname);
+  return false;
+}
+
+function isPrivateIpv4(hostname) {
+  const octets = hostname.split(".").map(Number);
+  if (octets.length !== 4 || octets.some((value) => !Number.isInteger(value) || value < 0 || value > 255)) {
+    return false;
+  }
+
+  const [first, second] = octets;
+  return first === 10
+    || (first === 172 && second >= 16 && second <= 31)
+    || (first === 192 && second === 168)
+    || (first === 169 && second === 254)
+    || first === 127
+    || first === 0;
+}
+
+function isPrivateIpv6(hostname) {
+  const normalized = hostname.toLowerCase();
+  return normalized === "::1"
+    || normalized === "::"
+    || normalized.startsWith("fc")
+    || normalized.startsWith("fd")
+    || normalized.startsWith("fe8")
+    || normalized.startsWith("fe9")
+    || normalized.startsWith("fea")
+    || normalized.startsWith("feb");
+}

package/src/global/intelligence/http.js

@@ -0,0 +1,63 @@
+const DEFAULT_TIMEOUT_MS = 5000;
+
+export async function fetchJson(url, {
+  method = "GET",
+  headers = {},
+  body = null,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  fetchImpl = globalThis.fetch
+} = {}) {
+  if (typeof fetchImpl !== "function") {
+    return {
+      ok: false,
+      status: 0,
+      data: null,
+      error: "fetch is not available in this runtime"
+    };
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetchImpl(url, {
+      method,
+      headers,
+      body: body == null ? undefined : JSON.stringify(body),
+      signal: controller.signal
+    });
+
+    const text = await response.text();
+    let data = null;
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = { raw: text };
+      }
+    }
+
+    return {
+      ok: response.ok,
+      status: response.status,
+      data,
+      error: response.ok ? null : summarizeHttpError(response.status, data, text)
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      status: 0,
+      data: null,
+      error: error?.name === "AbortError" ? "request timed out" : (error?.message ?? String(error))
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function summarizeHttpError(status, data, text) {
+  if (data?.error?.message) return data.error.message;
+  if (typeof data?.error === "string") return data.error;
+  if (text) return text.slice(0, 200);
+  return `HTTP ${status}`;
+}

package/src/global/intelligence/index.js

@@ -0,0 +1,38 @@
+export {
+  BACKEND_IDS,
+  COST_CLASSES,
+  PRIVACY_CLASSES,
+  ROUTING_MODES,
+  OPENROUTER_FREE_MODEL,
+  DEFAULT_OLLAMA_HOST,
+  createModelDescriptor,
+  createRoutingDecision,
+  createUsageTelemetry
+} from "./types.js";
+
+export { createOllamaBackend } from "./backends/ollama.js";
+export { createOpenRouterBackend } from "./backends/openrouter.js";
+export { createCustomHttpBackend } from "./backends/custom-http.js";
+
+export {
+  createDefaultBackends,
+  inspectIntelligenceBackends,
+  summarizeIntelligenceBackends,
+  resolveBackendById
+} from "./registry.js";
+
+export {
+  compileContextPack,
+  isPrivatePath,
+  estimateTokens
+} from "./context-compiler.js";
+
+export {
+  resolveRoutingDecision,
+  classifyTaskWeight
+} from "./router.js";
+
+export {
+  runIntelligenceRequest,
+  explainRouting
+} from "./orchestrate.js";

package/src/global/intelligence/orchestrate.js

@@ -0,0 +1,189 @@
+import { createDefaultBackends, inspectIntelligenceBackends, resolveBackendById } from "./registry.js";
+import { compileContextPack } from "./context-compiler.js";
+import { resolveRoutingDecision } from "./router.js";
+import { createUsageTelemetry, PRIVACY_CLASSES } from "./types.js";
+
+/**
+ * Orchestrates detect → context → route → privacy gate → invoke.
+ * Cloud transmission requires explicit consent. Credentials never touch disk.
+ */
+export async function runIntelligenceRequest({
+  workspaceRoot,
+  profile = {},
+  task = null,
+  prompt = null,
+  relevantPaths = [],
+  includePrivate = false,
+  cloudConsent = false,
+  confirmed = false,
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  backends = null,
+  tokenBudget = null
+} = {}) {
+  const customProviders = Array.isArray(profile.customProviders) ? profile.customProviders : [];
+  const backendInstances = backends ?? createDefaultBackends({ env, fetchImpl, customProviders });
+  const inspections = await inspectIntelligenceBackends({
+    env,
+    fetchImpl,
+    customProviders,
+    backends: backendInstances
+  });
+
+  const privateConfirmationRequired = includePrivate && !confirmed;
+  const contextPack = await compileContextPack({
+    workspaceRoot,
+    task: task ?? prompt,
+    relevantPaths,
+    includePrivate: includePrivate && confirmed,
+    stableBudgetTokens: profile.stableContextBudget ?? undefined,
+    requestBudgetTokens: profile.requestContextBudget ?? undefined
+  });
+
+  const routing = resolveRoutingDecision({
+    backends: inspections,
+    profile,
+    contextPack,
+    task: task ?? prompt,
+    cloudConsent: Boolean(cloudConsent),
+    tokenBudget: tokenBudget ?? profile.tokenBudget ?? null
+  });
+
+  const explanation = explainRouting(routing, contextPack, inspections);
+  const base = {
+    routing,
+    explanation,
+    contextPack: summarizeContextPack(contextPack),
+    backends: inspections
+  };
+
+  if (privateConfirmationRequired) {
+    return {
+      ...base,
+      ok: false,
+      mode: routing.mode,
+      diagnosticsOnly: true,
+      result: null,
+      telemetry: null,
+      error: "Including private context requires explicit confirmation (--include-private --yes / --confirm)."
+    };
+  }
+
+  if (!routing.canInvoke) {
+    return {
+      ...base,
+      ok: false,
+      mode: routing.mode,
+      diagnosticsOnly: true,
+      result: null,
+      telemetry: null,
+      error: routing.reason
+    };
+  }
+
+  if (routing.privacyImpact === PRIVACY_CLASSES.CLOUD) {
+    if (!cloudConsent) {
+      return {
+        ...base,
+        ok: false,
+        mode: routing.mode,
+        diagnosticsOnly: true,
+        result: null,
+        telemetry: null,
+        error: "Cloud transmission requires explicit consent."
+      };
+    }
+    if (!confirmed) {
+      return {
+        ...base,
+        ok: false,
+        mode: routing.mode,
+        diagnosticsOnly: true,
+        result: null,
+        telemetry: null,
+        error: "Confirm cloud context transmission before invoke (--yes / --confirm)."
+      };
+    }
+  }
+
+  const backend = resolveBackendById(backendInstances, routing.backendId);
+  if (!backend) {
+    return {
+      ...base,
+      ok: false,
+      mode: routing.mode,
+      diagnosticsOnly: true,
+      result: null,
+      telemetry: null,
+      error: `Backend ${routing.backendId} is not loaded.`
+    };
+  }
+
+  const result = await backend.invoke(contextPack, {
+    modelId: routing.model?.modelId,
+    prompt: prompt ?? task,
+    timeoutMs: profile.invokeTimeoutMs ?? undefined
+  });
+
+  const telemetry = createUsageTelemetry({
+    ...(result.usage ?? {}),
+    model: result.model ?? routing.model?.modelId,
+    backendId: routing.backendId,
+    fallbackUsed: Boolean(result.usage?.fallbackUsed)
+  });
+
+  return {
+    ...base,
+    ok: Boolean(result.ok),
+    mode: routing.mode,
+    diagnosticsOnly: false,
+    result,
+    telemetry,
+    error: result.ok ? null : (result.error ?? "Invoke failed.")
+  };
+}
+
+export function explainRouting(routing, contextPack, backends = []) {
+  const evidencePaths = (contextPack?.evidence ?? [])
+    .filter((entry) => entry.kind === "file")
+    .map((entry) => entry.path);
+
+  return {
+    selectedBackend: routing.backendId,
+    selectedModel: routing.model?.modelId ?? null,
+    reason: routing.reason,
+    mode: routing.mode,
+    estimatedTokens: routing.estimatedTokens,
+    privacyImpact: routing.privacyImpact,
+    requiresCloudConsent: routing.requiresCloudConsent,
+    canInvoke: routing.canInvoke,
+    evidenceUsed: evidencePaths,
+    excludedPrivate: contextPack?.privacy?.excludedPrivate ?? [],
+    availableBackends: backends.map((entry) => ({
+      id: entry.id,
+      state: entry.state,
+      available: entry.available,
+      modelCount: entry.models?.length ?? 0
+    })),
+    fallback: routing.fallback
+  };
+}
+
+function summarizeContextPack(contextPack) {
+  if (!contextPack) return null;
+  return {
+    workspaceRoot: contextPack.workspaceRoot,
+    estimatedTokens: contextPack.estimatedTokens,
+    project: contextPack.stable?.project ?? null,
+    evidenceCount: contextPack.evidence?.length ?? 0,
+    evidence: contextPack.evidence,
+    privacy: contextPack.privacy,
+    budgets: contextPack.budgets,
+    skills: contextPack.stable?.skills ?? [],
+    sdd: contextPack.stable?.sdd ?? false,
+    tdd: contextPack.stable?.tdd ?? false,
+    graphify: contextPack.stable?.graphify ?? null,
+    hasAgentsMd: Boolean(contextPack.stable?.agentsMd),
+    relevantFiles: (contextPack.perRequest?.files ?? []).map((file) => file.path)
+  };
+}

package/src/global/intelligence/registry.js

@@ -0,0 +1,77 @@
+import { BACKEND_IDS } from "./types.js";
+import { createOllamaBackend } from "./backends/ollama.js";
+import { createOpenRouterBackend } from "./backends/openrouter.js";
+import { createCustomHttpBackend } from "./backends/custom-http.js";
+import { CAPABILITY_STATES } from "../capability-states.js";
+
+export function createDefaultBackends({
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  customProviders = []
+} = {}) {
+  const backends = [
+    createOllamaBackend({ env, fetchImpl }),
+    createOpenRouterBackend({ env, fetchImpl })
+  ];
+
+  for (const provider of customProviders) {
+    backends.push(createCustomHttpBackend({
+      ...provider,
+      env,
+      fetchImpl
+    }));
+  }
+
+  return backends;
+}
+
+export async function inspectIntelligenceBackends({
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  customProviders = [],
+  backends = null
+} = {}) {
+  const resolved = backends ?? createDefaultBackends({ env, fetchImpl, customProviders });
+  return Promise.all(resolved.map(async (backend) => {
+    const detection = await backend.detect();
+    const models = detection.detected || detection.available
+      ? await backend.listModels()
+      : [];
+    const capabilities = await backend.capabilities();
+
+    return {
+      ...detection,
+      models,
+      capabilities
+    };
+  }));
+}
+
+export function summarizeIntelligenceBackends(inspections) {
+  const byState = {};
+  for (const state of Object.values(CAPABILITY_STATES)) {
+    byState[state] = 0;
+  }
+
+  for (const entry of inspections) {
+    if (byState[entry.state] != null) {
+      byState[entry.state] += 1;
+    }
+  }
+
+  return {
+    total: inspections.length,
+    available: inspections.filter((entry) => entry.available).length,
+    localAvailable: inspections.some(
+      (entry) => entry.id === BACKEND_IDS.OLLAMA && entry.available
+    ),
+    cloudAuthenticated: inspections.some(
+      (entry) => entry.id === BACKEND_IDS.OPENROUTER && entry.hasApiKey
+    ),
+    byState
+  };
+}
+
+export function resolveBackendById(backends, backendId) {
+  return backends.find((backend) => backend.id === backendId) ?? null;
+}

package/src/global/intelligence/router.js

@@ -0,0 +1,191 @@
+import {
+  BACKEND_IDS,
+  OPENROUTER_FREE_MODEL,
+  PRIVACY_CLASSES,
+  ROUTING_MODES,
+  createRoutingDecision
+} from "./types.js";
+import { estimateTokens } from "./context-compiler.js";
+
+const TASK_WEIGHTS = {
+  architecture: "heavy",
+  security: "heavy",
+  review: "heavy",
+  diagnose: "light",
+  explain: "light",
+  scaffold: "light",
+  test: "light",
+  default: "light"
+};
+
+export function classifyTaskWeight(task = "") {
+  const text = String(task).toLowerCase();
+  if (/architect|adr|design system|security|threat/.test(text)) return "heavy";
+  if (/review|refactor complex|debug complex/.test(text)) return "heavy";
+  if (/test|scaffold|explain|status|diagnose|lint|format/.test(text)) return "light";
+  return TASK_WEIGHTS.default;
+}
+
+/**
+ * Resolve which backend/model to use.
+ * Precedence: user override > Ollama local > OpenRouter free (consent) > diagnostics.
+ */
+export function resolveRoutingDecision({
+  backends = [],
+  profile = {},
+  contextPack = null,
+  task = null,
+  cloudConsent = false,
+  tokenBudget = null
+} = {}) {
+  const estimatedTokens = contextPack?.estimatedTokens
+    ?? estimateTokens(contextPack?.systemPrompt ?? "")
+    + estimateTokens(task ?? "");
+
+  const budget = tokenBudget ?? profile.tokenBudget ?? null;
+  if (budget != null && estimatedTokens > budget) {
+    return createRoutingDecision({
+      backendId: null,
+      model: null,
+      reason: `Estimated tokens (${estimatedTokens}) exceed budget (${budget}). Compact context or raise tokenBudget.`,
+      estimatedTokens,
+      privacyImpact: PRIVACY_CLASSES.UNKNOWN,
+      mode: ROUTING_MODES.DIAGNOSTICS,
+      requiresCloudConsent: false,
+      canInvoke: false
+    });
+  }
+
+  const override = resolveUserOverride(profile, backends);
+  if (override) {
+    return createRoutingDecision({
+      backendId: override.backend.id,
+      model: override.model,
+      reason: `User override: ${override.backend.id}/${override.model.modelId}`,
+      estimatedTokens,
+      privacyImpact: override.model.privacyClass,
+      mode: ROUTING_MODES.USER_OVERRIDE,
+      requiresCloudConsent: !override.model.local,
+      canInvoke: override.model.local || cloudConsent,
+      fallback: buildLocalFallback(backends)
+    });
+  }
+
+  const ollama = backends.find((entry) => entry.id === BACKEND_IDS.OLLAMA);
+  if (ollama?.available && Array.isArray(ollama.models) && ollama.models.length > 0) {
+    const model = selectLocalModel(ollama.models, task);
+    return createRoutingDecision({
+      backendId: BACKEND_IDS.OLLAMA,
+      model,
+      reason: `Local-first: Ollama model ${model.modelId}`,
+      estimatedTokens,
+      privacyImpact: PRIVACY_CLASSES.LOCAL,
+      mode: ROUTING_MODES.LOCAL,
+      requiresCloudConsent: false,
+      canInvoke: true,
+      fallback: buildCloudFallback(backends, cloudConsent)
+    });
+  }
+
+  const openrouter = backends.find((entry) => entry.id === BACKEND_IDS.OPENROUTER);
+  if (openrouter?.hasApiKey) {
+    const model = openrouter.models?.find((entry) => entry.modelId === OPENROUTER_FREE_MODEL)
+      ?? openrouter.models?.[0]
+      ?? {
+        provider: BACKEND_IDS.OPENROUTER,
+        modelId: OPENROUTER_FREE_MODEL,
+        local: false,
+        privacyClass: PRIVACY_CLASSES.CLOUD,
+        costClass: "free",
+        opaque: true
+      };
+
+    return createRoutingDecision({
+      backendId: BACKEND_IDS.OPENROUTER,
+      model,
+      reason: cloudConsent
+        ? `Cloud fallback approved: ${model.modelId}`
+        : `OpenRouter available (${model.modelId}) but cloud consent required before invoke`,
+      estimatedTokens,
+      privacyImpact: PRIVACY_CLASSES.CLOUD,
+      mode: ROUTING_MODES.CLOUD_CONSENT,
+      requiresCloudConsent: true,
+      canInvoke: cloudConsent,
+      fallback: null
+    });
+  }
+
+  return createRoutingDecision({
+    backendId: null,
+    model: null,
+    reason: "No intelligence backend available. Remaining in diagnostics/configuration mode.",
+    estimatedTokens,
+    privacyImpact: PRIVACY_CLASSES.UNKNOWN,
+    mode: ROUTING_MODES.DIAGNOSTICS,
+    requiresCloudConsent: false,
+    canInvoke: false
+  });
+}
+
+function resolveUserOverride(profile, backends) {
+  const preferredBackend = profile.preferredBackend ?? null;
+  const preferredModel = profile.preferredModel ?? null;
+  if (!preferredBackend && !preferredModel) return null;
+
+  if (preferredBackend) {
+    const backend = backends.find((entry) => entry.id === preferredBackend);
+    if (!backend || (!backend.available && !backend.hasApiKey && !backend.detected)) {
+      return null;
+    }
+    const model = (backend.models ?? []).find((entry) => entry.modelId === preferredModel)
+      ?? backend.models?.[0]
+      ?? (preferredModel
+        ? {
+          provider: preferredBackend,
+          modelId: preferredModel,
+          local: backend.id === BACKEND_IDS.OLLAMA,
+          privacyClass: backend.id === BACKEND_IDS.OLLAMA ? PRIVACY_CLASSES.LOCAL : PRIVACY_CLASSES.CLOUD,
+          costClass: "unknown",
+          opaque: true
+        }
+        : null);
+    if (!model) return null;
+    return { backend, model };
+  }
+
+  if (preferredModel) {
+    for (const backend of backends) {
+      const model = (backend.models ?? []).find((entry) => entry.modelId === preferredModel);
+      if (model) return { backend, model };
+    }
+  }
+
+  return null;
+}
+
+function selectLocalModel(models, task) {
+  const weight = classifyTaskWeight(task);
+  if (weight === "heavy" && models.length > 1) {
+    return [...models].sort((a, b) => String(b.modelId).localeCompare(String(a.modelId)))[0];
+  }
+  return models[0];
+}
+
+function buildLocalFallback(backends) {
+  const ollama = backends.find((entry) => entry.id === BACKEND_IDS.OLLAMA && entry.available);
+  if (!ollama?.models?.length) return null;
+  return {
+    backendId: BACKEND_IDS.OLLAMA,
+    modelId: ollama.models[0].modelId
+  };
+}
+
+function buildCloudFallback(backends, cloudConsent) {
+  const openrouter = backends.find((entry) => entry.id === BACKEND_IDS.OPENROUTER && entry.hasApiKey);
+  if (!openrouter) return null;
+  return {
+    backendId: BACKEND_IDS.OPENROUTER,
+    modelId: OPENROUTER_FREE_MODEL,
+    requiresConsent: !cloudConsent
+  };
+}