@kal-elsam/kairo-runtime 0.1.4 → 0.2.0

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

package/src/global/intelligence/types.js

@@ -0,0 +1,99 @@
+export const BACKEND_IDS = {
+  OLLAMA: "ollama",
+  OPENROUTER: "openrouter",
+  CUSTOM: "custom"
+};
+
+export const COST_CLASSES = {
+  FREE: "free",
+  LOCAL: "local",
+  PAID: "paid",
+  UNKNOWN: "unknown"
+};
+
+export const PRIVACY_CLASSES = {
+  LOCAL: "local",
+  CLOUD: "cloud",
+  UNKNOWN: "unknown"
+};
+
+export const ROUTING_MODES = {
+  DIAGNOSTICS: "diagnostics",
+  LOCAL: "local",
+  CLOUD_CONSENT: "cloud_consent",
+  USER_OVERRIDE: "user_override"
+};
+
+export const OPENROUTER_FREE_MODEL = "openrouter/free";
+
+export const DEFAULT_OLLAMA_HOST = "http://127.0.0.1:11434";
+
+export function createModelDescriptor({
+  provider,
+  modelId,
+  local = false,
+  costClass = COST_CLASSES.UNKNOWN,
+  privacyClass = PRIVACY_CLASSES.UNKNOWN,
+  contextLimit = null,
+  tools = false,
+  reasoning = false,
+  rateLimits = null,
+  opaque = false
+}) {
+  return {
+    provider,
+    modelId,
+    local,
+    costClass,
+    privacyClass,
+    contextLimit,
+    tools,
+    reasoning,
+    rateLimits,
+    opaque
+  };
+}
+
+export function createRoutingDecision({
+  backendId,
+  model,
+  reason,
+  estimatedTokens = null,
+  privacyImpact = PRIVACY_CLASSES.UNKNOWN,
+  fallback = null,
+  mode = ROUTING_MODES.DIAGNOSTICS,
+  requiresCloudConsent = false,
+  canInvoke = false
+}) {
+  return {
+    backendId,
+    model,
+    reason,
+    estimatedTokens,
+    privacyImpact,
+    fallback,
+    mode,
+    requiresCloudConsent,
+    canInvoke
+  };
+}
+
+export function createUsageTelemetry({
+  inputTokens = null,
+  outputTokens = null,
+  cachedTokens = null,
+  estimatedCost = null,
+  model = null,
+  backendId = null,
+  fallbackUsed = false
+} = {}) {
+  return {
+    inputTokens,
+    outputTokens,
+    cachedTokens,
+    estimatedCost,
+    model,
+    backendId,
+    fallbackUsed
+  };
+}

package/src/global/intelligence-cli.js

@@ -0,0 +1,323 @@
+import { resolveHomeDir } from "./paths.js";
+import { resolveProfile, buildProfileJson } from "./profile.js";
+import {
+  compileContextPack,
+  inspectIntelligenceBackends,
+  resolveRoutingDecision,
+  runIntelligenceRequest,
+  summarizeIntelligenceBackends
+} from "./intelligence/index.js";
+import { BRAND } from "./brand/index.js";
+import { formatCliCommand } from "./brand/cli.js";
+
+export async function runIntelligenceCli(options, packageManifest) {
+  const action = options.intelligenceAction ?? "status";
+  const homeDir = resolveHomeDir();
+  const workspaceRoot = options.cwd;
+  const { profile, sources } = await resolveProfile({ homeDir, workspaceRoot });
+
+  switch (action) {
+    case "status":
+      return printIntelligenceStatus({
+        homeDir,
+        workspaceRoot,
+        profile,
+        sources,
+        json: options.json,
+        env: process.env
+      });
+    case "models":
+      return printIntelligenceModels({
+        profile,
+        json: options.json,
+        env: process.env
+      });
+    case "context":
+      return printIntelligenceContext({
+        workspaceRoot,
+        profile,
+        task: options.intelligenceTask,
+        relevantPaths: options.intelligencePaths ?? [],
+        includePrivate: options.includePrivate,
+        confirmed: options.yes || options.confirm,
+        json: options.json
+      });
+    case "route":
+      return printIntelligenceRoute({
+        workspaceRoot,
+        profile,
+        task: options.intelligenceTask,
+        cloudConsent: options.cloudConsent,
+        json: options.json,
+        env: process.env
+      });
+    case "ask":
+      return runIntelligenceAsk({
+        workspaceRoot,
+        profile,
+        task: options.intelligenceTask,
+        prompt: options.intelligencePrompt,
+        relevantPaths: options.intelligencePaths ?? [],
+        includePrivate: options.includePrivate,
+        cloudConsent: options.cloudConsent,
+        confirmed: options.yes || options.confirm,
+        json: options.json,
+        env: process.env,
+        packageManifest
+      });
+    default:
+      throw new Error(
+        `Unknown intelligence action "${action}". Use status, models, context, route, or ask.`
+      );
+  }
+}
+
+async function printIntelligenceStatus({ homeDir, workspaceRoot, profile, sources, json, env }) {
+  const backends = await inspectIntelligenceBackends({
+    env,
+    customProviders: profile.customProviders
+  });
+  const summary = summarizeIntelligenceBackends(backends);
+  const routing = resolveRoutingDecision({
+    backends,
+    profile,
+    cloudConsent: false
+  });
+
+  const payload = {
+    readOnly: true,
+    homeDir,
+    workspaceRoot,
+    profile: buildProfileJson({ profile, sources }),
+    backends,
+    summary,
+    routing
+  };
+
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return payload;
+  }
+
+  console.log(`${BRAND.displayName} intelligence — status`);
+  console.log(`Home: ${homeDir}`);
+  console.log(`Workspace: ${workspaceRoot}`);
+  console.log("");
+  for (const backend of backends) {
+    const models = backend.models?.length ?? 0;
+    console.log(
+      `  ${backend.label.padEnd(14)} ${backend.state.padEnd(14)} models=${models}`
+    );
+  }
+  console.log("");
+  console.log(`Routing: ${routing.reason}`);
+  console.log(`Can invoke: ${routing.canInvoke ? "yes" : "no"}`);
+  if (!summary.localAvailable && !summary.cloudAuthenticated) {
+    console.log("");
+    console.log("Diagnostics mode: configure Ollama or OPENROUTER_API_KEY to enable inference.");
+  }
+  return payload;
+}
+
+async function printIntelligenceModels({ profile, json, env }) {
+  const backends = await inspectIntelligenceBackends({
+    env,
+    customProviders: profile.customProviders
+  });
+
+  const models = backends.flatMap((backend) =>
+    (backend.models ?? []).map((model) => ({
+      ...model,
+      backendState: backend.state,
+      available: backend.available
+    }))
+  );
+
+  const payload = { readOnly: true, models, backends: backends.map((entry) => ({
+    id: entry.id,
+    state: entry.state,
+    available: entry.available
+  })) };
+
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return payload;
+  }
+
+  console.log(`${BRAND.displayName} intelligence — models`);
+  if (models.length === 0) {
+    console.log("  No models detected. Start Ollama or set OPENROUTER_API_KEY.");
+  } else {
+    for (const model of models) {
+      console.log(
+        `  ${model.provider.padEnd(12)} ${model.modelId.padEnd(32)} ${model.privacyClass}/${model.costClass}`
+      );
+    }
+  }
+  return payload;
+}
+
+async function printIntelligenceContext({
+  workspaceRoot,
+  profile,
+  task,
+  relevantPaths,
+  includePrivate,
+  confirmed,
+  json
+}) {
+  const privateConfirmationRequired = includePrivate && !confirmed;
+  const pack = await compileContextPack({
+    workspaceRoot,
+    task,
+    relevantPaths,
+    includePrivate: includePrivate && confirmed,
+    stableBudgetTokens: profile.stableContextBudget ?? undefined,
+    requestBudgetTokens: profile.requestContextBudget ?? undefined
+  });
+
+  const payload = {
+    readOnly: true,
+    estimatedTokens: pack.estimatedTokens,
+    project: pack.stable.project,
+    evidence: pack.evidence,
+    privacy: pack.privacy,
+    skills: pack.stable.skills,
+    sdd: pack.stable.sdd,
+    tdd: pack.stable.tdd,
+    graphify: pack.stable.graphify,
+    hasAgentsMd: Boolean(pack.stable.agentsMd),
+    relevantFiles: pack.perRequest.files.map((file) => file.path)
+  };
+
+  if (privateConfirmationRequired) {
+    payload.privateConfirmationRequired = true;
+    payload.error = "Including private context requires explicit confirmation (--include-private --yes / --confirm).";
+  }
+
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return payload;
+  }
+
+  console.log(`${BRAND.displayName} intelligence — context`);
+  console.log(`Estimated tokens: ${pack.estimatedTokens}`);
+  console.log(`Project: ${pack.stable.project.name} (${pack.stable.project.stack})`);
+  console.log(`Evidence files: ${pack.evidence.filter((entry) => entry.kind === "file").length}`);
+  if (privateConfirmationRequired) {
+    console.log(`Blocked: ${payload.error}`);
+  }
+  if (pack.privacy.excludedPrivate.length > 0) {
+    console.log(`Excluded private: ${pack.privacy.excludedPrivate.join(", ")}`);
+  }
+  return payload;
+}
+
+async function printIntelligenceRoute({
+  workspaceRoot,
+  profile,
+  task,
+  cloudConsent,
+  json,
+  env
+}) {
+  const backends = await inspectIntelligenceBackends({
+    env,
+    customProviders: profile.customProviders
+  });
+  const pack = await compileContextPack({ workspaceRoot, task });
+  const routing = resolveRoutingDecision({
+    backends,
+    profile,
+    contextPack: pack,
+    task,
+    cloudConsent: Boolean(cloudConsent)
+  });
+
+  const payload = {
+    readOnly: true,
+    routing,
+    estimatedTokens: pack.estimatedTokens,
+    evidenceUsed: pack.evidence.filter((entry) => entry.kind === "file").map((entry) => entry.path)
+  };
+
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return payload;
+  }
+
+  console.log(`${BRAND.displayName} intelligence — routing`);
+  console.log(`Backend: ${routing.backendId ?? "none"}`);
+  console.log(`Model: ${routing.model?.modelId ?? "none"}`);
+  console.log(`Reason: ${routing.reason}`);
+  console.log(`Estimated tokens: ${routing.estimatedTokens}`);
+  console.log(`Privacy: ${routing.privacyImpact}`);
+  console.log(`Can invoke: ${routing.canInvoke ? "yes" : "no"}`);
+  return payload;
+}
+
+async function runIntelligenceAsk({
+  workspaceRoot,
+  profile,
+  task,
+  prompt,
+  relevantPaths,
+  includePrivate,
+  cloudConsent,
+  confirmed,
+  json,
+  env
+}) {
+  if (!prompt && !task) {
+    throw new Error(`Missing prompt. Use: ${formatCliCommand("intelligence ask --prompt \"...\"")}`);
+  }
+
+  const outcome = await runIntelligenceRequest({
+    workspaceRoot,
+    profile,
+    task,
+    prompt: prompt ?? task,
+    relevantPaths,
+    includePrivate,
+    cloudConsent,
+    confirmed,
+    env
+  });
+
+  if (json) {
+    console.log(JSON.stringify({
+      ok: outcome.ok,
+      mode: outcome.mode,
+      diagnosticsOnly: outcome.diagnosticsOnly,
+      routing: outcome.routing,
+      explanation: outcome.explanation,
+      telemetry: outcome.telemetry,
+      content: outcome.result?.content ?? null,
+      error: outcome.error
+    }, null, 2));
+    return outcome;
+  }
+
+  console.log(`${BRAND.displayName} intelligence — ask`);
+  console.log(`Routing: ${outcome.explanation.reason}`);
+  console.log(`Estimated tokens: ${outcome.explanation.estimatedTokens}`);
+  console.log(`Privacy: ${outcome.explanation.privacyImpact}`);
+  console.log("");
+
+  if (!outcome.ok) {
+    console.log(`Blocked: ${outcome.error}`);
+    if (outcome.routing?.requiresCloudConsent) {
+      console.log(`Retry with --cloud-consent --yes after reviewing context (${formatCliCommand("intelligence context")}).`);
+    }
+    return outcome;
+  }
+
+  console.log(outcome.result.content);
+  if (outcome.telemetry) {
+    console.log("");
+    console.log(
+      `Usage: in=${outcome.telemetry.inputTokens ?? "?"} out=${outcome.telemetry.outputTokens ?? "?"} model=${outcome.telemetry.model}`
+    );
+  }
+  return outcome;
+}