@kal-elsam/kairo-runtime 0.1.5 → 0.2.1

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
+  };
+}

package/src/global/intelligence/context-compiler.js

@@ -0,0 +1,338 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile, realpath } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { detectProject } from "../../project-detection.js";
+
+const PRIVATE_PATH_PATTERNS = [
+  /^\.env(\.|$)/i,
+  /(^|\/)\.env(\.|$)/i,
+  /(^|\/)secrets?\//i,
+  /(^|\/)credentials?\./i,
+  /\.pem$/i,
+  /\.key$/i,
+  /(^|\/)id_rsa/i,
+  /(^|\/)\.npmrc$/i,
+  /(^|\/)\.netrc$/i
+];
+
+const STABLE_DOC_CANDIDATES = [
+  "AGENTS.md",
+  "docs/ai/harness.md",
+  "docs/ai/architecture.md",
+  "docs/ai/conventions.md",
+  "docs/ai/testing.md",
+  "docs/ai/spec-driven-development.md",
+  "docs/ai/test-driven-development.md",
+  "docs/ai/provider-routing.md",
+  "docs/ai/model-policy.md",
+  "docs/ai/context-budget.md"
+];
+
+const DEFAULT_STABLE_BUDGET = 6000;
+const DEFAULT_REQUEST_BUDGET = 4000;
+
+export async function compileContextPack({
+  workspaceRoot,
+  task = null,
+  relevantPaths = [],
+  includePrivate = false,
+  stableBudgetTokens = DEFAULT_STABLE_BUDGET,
+  requestBudgetTokens = DEFAULT_REQUEST_BUDGET
+} = {}) {
+  const root = resolve(workspaceRoot ?? process.cwd());
+  const workspaceRealRoot = await resolveWorkspaceRoot(root);
+  const project = await detectProject(root);
+  const evidence = [];
+
+  const agentsMd = await readEvidenceFile(
+    root,
+    workspaceRealRoot,
+    "AGENTS.md",
+    evidence,
+    2000,
+    { includePrivate }
+  );
+  const stableDocs = await collectStableDocs(root, workspaceRealRoot, evidence, stableBudgetTokens, includePrivate);
+  const skills = await listSkillIds(root, evidence);
+  const graphify = await detectGraphify(root, evidence);
+  const engram = await detectEngramHints(root, evidence);
+
+  const requestFiles = [];
+  for (const filePath of relevantPaths) {
+    const rel = relative(root, resolve(root, filePath));
+    const content = await readEvidenceFile(
+      root,
+      workspaceRealRoot,
+      rel,
+      evidence,
+      requestBudgetTokens,
+      { includePrivate }
+    );
+    if (content) {
+      requestFiles.push({ path: rel, content: content.text, truncated: content.truncated });
+    }
+  }
+
+  const stable = {
+    project: {
+      name: project.name,
+      purpose: project.purpose,
+      stack: project.stack,
+      architecturePattern: project.architecturePattern,
+      packageManager: project.packageManager,
+      commands: project.commands,
+      detectedAdapters: project.detectedAdapters
+    },
+    agentsMd: agentsMd?.text ?? null,
+    docs: stableDocs,
+    skills,
+    sdd: Boolean(stableDocs.find((doc) => doc.path.includes("spec-driven"))),
+    tdd: Boolean(stableDocs.find((doc) => doc.path.includes("test-driven"))),
+    graphify,
+    engram
+  };
+
+  const perRequest = {
+    task,
+    files: requestFiles
+  };
+
+  const systemPrompt = buildSystemPrompt(stable, perRequest);
+  const estimatedTokens = estimateTokens(systemPrompt);
+
+  return {
+    version: 1,
+    workspaceRoot: root,
+    stable,
+    perRequest,
+    evidence,
+    systemPrompt,
+    estimatedTokens,
+    budgets: {
+      stableBudgetTokens,
+      requestBudgetTokens
+    },
+    privacy: {
+      includePrivate,
+      excludedPrivate: evidence
+        .filter((entry) => entry.kind === "excluded_private")
+        .map((entry) => entry.path)
+    }
+  };
+}
+
+export function isPrivatePath(relativePath) {
+  const normalized = relativePath.replace(/\\/g, "/");
+  return PRIVATE_PATH_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+
+export function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(text.length / 4);
+}
+
+async function collectStableDocs(root, workspaceRealRoot, evidence, budgetTokens, includePrivate) {
+  const docs = [];
+  let used = 0;
+
+  for (const candidate of STABLE_DOC_CANDIDATES) {
+    if (candidate === "AGENTS.md") continue;
+    const remaining = Math.max(500, budgetTokens - used);
+    const content = await readEvidenceFile(
+      root,
+      workspaceRealRoot,
+      candidate,
+      evidence,
+      remaining,
+      { includePrivate }
+    );
+    if (!content) continue;
+    docs.push({ path: candidate, content: content.text, truncated: content.truncated });
+    used += estimateTokens(content.text);
+    if (used >= budgetTokens) break;
+  }
+
+  return docs;
+}
+
+async function listSkillIds(root, evidence) {
+  const skillRoots = [
+    join(root, "docs", "skills"),
+    join(root, ".cursor", "skills"),
+    join(root, ".codex", "skills"),
+    join(root, ".claude", "skills")
+  ];
+
+  const ids = new Set();
+  for (const skillRoot of skillRoots) {
+    if (!existsSync(skillRoot)) continue;
+    evidence.push({ kind: "skills_root", path: relative(root, skillRoot) });
+    try {
+      const entries = await readdir(skillRoot, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) ids.add(entry.name);
+      }
+    } catch {
+      // ignore unreadable skill roots
+    }
+  }
+
+  return [...ids].sort();
+}
+
+async function detectGraphify(root, evidence) {
+  const reportPath = join(root, "graphify-out", "GRAPH_REPORT.md");
+  const graphPath = join(root, "graphify-out", "graph.json");
+  const present = existsSync(reportPath) || existsSync(graphPath);
+  if (present) {
+    evidence.push({ kind: "graphify", path: "graphify-out" });
+  }
+  return { present, report: existsSync(reportPath), graph: existsSync(graphPath) };
+}
+
+async function detectEngramHints(root, evidence) {
+  const memoryDoc = join(root, "docs", "ai", "memory.md");
+  const present = existsSync(memoryDoc);
+  if (present) {
+    evidence.push({ kind: "engram_doc", path: "docs/ai/memory.md" });
+  }
+  return { documented: present };
+}
+
+async function readEvidenceFile(
+  root,
+  workspaceRealRoot,
+  relativePath,
+  evidence,
+  maxTokens = 2000,
+  { includePrivate = false } = {}
+) {
+  const requested = resolve(root, relativePath);
+  const requestedRelative = relative(root, requested) || ".";
+  if (!isPathInside(root, requested)) {
+    evidence.push({
+      kind: "rejected_outside_workspace",
+      path: requestedRelative,
+      reason: "Path is outside workspaceRoot"
+    });
+    return null;
+  }
+
+  if (!existsSync(requested)) return null;
+
+  let target;
+  try {
+    target = await realpath(requested);
+  } catch {
+    evidence.push({ kind: "unreadable", path: requestedRelative });
+    return null;
+  }
+
+  if (!isPathInside(workspaceRealRoot, target)) {
+    evidence.push({
+      kind: "rejected_outside_workspace",
+      path: requestedRelative,
+      reason: "Symlink target is outside workspaceRoot"
+    });
+    return null;
+  }
+
+  const targetRelative = relative(workspaceRealRoot, target) || ".";
+  if ((isPrivatePath(requestedRelative) || isPrivatePath(targetRelative)) && !includePrivate) {
+    evidence.push({
+      kind: "excluded_private",
+      path: requestedRelative,
+      reason: "Private path excluded without consent"
+    });
+    return null;
+  }
+
+  try {
+    const raw = await readFile(target, "utf8");
+    const maxChars = maxTokens * 4;
+    const truncated = raw.length > maxChars;
+    const text = truncated ? `${raw.slice(0, maxChars)}\n…[truncated]` : raw;
+    evidence.push({
+      kind: "file",
+      path: requestedRelative,
+      truncated,
+      chars: text.length
+    });
+    return { text, truncated };
+  } catch {
+    evidence.push({ kind: "unreadable", path: requestedRelative });
+    return null;
+  }
+}
+
+async function resolveWorkspaceRoot(root) {
+  try {
+    return await realpath(root);
+  } catch {
+    return root;
+  }
+}
+
+function isPathInside(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${requirePathSeparator()}`));
+}
+
+function requirePathSeparator() {
+  return process.platform === "win32" ? "\\" : "/";
+}
+
+function buildSystemPrompt(stable, perRequest) {
+  const lines = [
+    "You are assisting inside Kairo Runtime harness governance.",
+    "Prefer architecture before implementation, existing patterns, minimal diffs, tests/specs.",
+    "Do not invent speculative code, unnecessary dependencies, or duplicate abstractions.",
+    "Never request or echo secrets. Private files require explicit human consent.",
+    "",
+    "## Project",
+    `Name: ${stable.project.name}`,
+    `Purpose: ${stable.project.purpose}`,
+    `Stack: ${stable.project.stack}`,
+    `Architecture: ${stable.project.architecturePattern}`,
+    `Package manager: ${stable.project.packageManager}`,
+    `Commands: ${JSON.stringify(stable.project.commands)}`,
+    `Adapters: ${(stable.project.detectedAdapters ?? []).join(", ") || "none"}`,
+    ""
+  ];
+
+  if (stable.agentsMd) {
+    lines.push("## AGENTS.md", stable.agentsMd, "");
+  }
+
+  if (stable.docs.length > 0) {
+    lines.push("## Stable docs");
+    for (const doc of stable.docs) {
+      lines.push(`### ${doc.path}`, doc.content, "");
+    }
+  }
+
+  if (stable.skills.length > 0) {
+    lines.push(`## Skills available: ${stable.skills.join(", ")}`, "");
+  }
+
+  lines.push(
+    `## SDD: ${stable.sdd ? "documented" : "not detected"}`,
+    `## TDD: ${stable.tdd ? "documented" : "not detected"}`,
+    `## Graphify: ${stable.graphify.present ? "present" : "absent"}`,
+    `## Engram docs: ${stable.engram.documented ? "present" : "absent"}`,
+    ""
+  );
+
+  if (perRequest.task) {
+    lines.push("## Task", perRequest.task, "");
+  }
+
+  if (perRequest.files.length > 0) {
+    lines.push("## Relevant files");
+    for (const file of perRequest.files) {
+      lines.push(`### ${file.path}`, file.content, "");
+    }
+  }
+
+  return lines.join("\n");
+}