@kal-elsam/kairo-runtime 0.1.4 → 0.2.0

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

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