@kal-elsam/kairo-runtime 0.1.5 → 0.2.1

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

package/src/global/orchestrator.js

@@ -119,6 +119,17 @@ export async function runOrchestratorDiagnostics({
     );
   }
 
+  if (diagnostics.intelligence) {
+    console.log("");
+    console.log("Intelligence backends:");
+    for (const backend of diagnostics.intelligence.backends) {
+      console.log(
+        `  ${backend.label.padEnd(14)} ${backend.state.padEnd(14)} models=${backend.models?.length ?? 0}`
+      );
+    }
+    console.log(`  Routing: ${diagnostics.intelligence.routingPreview?.reason ?? "n/a"}`);
+  }
+
   console.log("");
   console.log("Recommendations:");
   for (const recommendation of diagnostics.recommendations) {

package/src/global/profile.js

@@ -3,19 +3,34 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { harnessHomePaths } from "./paths.js";
 import { AGENT_CAPABILITY_IDS } from "./agent-capabilities/index.js";
+import { classifyCustomBaseUrl, isValidEnvironmentName } from "./intelligence/custom-url.js";
 
 export const PROFILE_KEYS = new Set([
   "coordinator",
   "defaultAgents",
   "defaultComponents",
-  "applyMode"
+  "applyMode",
+  "preferredBackend",
+  "preferredModel",
+  "cloudConsent",
+  "tokenBudget",
+  "stableContextBudget",
+  "requestContextBudget",
+  "customProviders"
 ]);
 
 export const DEFAULT_PROFILE = {
   coordinator: null,
   defaultAgents: "detected",
   defaultComponents: null,
-  applyMode: "prompt"
+  applyMode: "prompt",
+  preferredBackend: null,
+  preferredModel: null,
+  cloudConsent: false,
+  tokenBudget: null,
+  stableContextBudget: null,
+  requestContextBudget: null,
+  customProviders: []
 };
 
 const APPLY_MODES = new Set(["prompt", "confirm"]);
@@ -64,6 +79,7 @@ export async function resolveProfile({ homeDir, workspaceRoot }) {
   };
 
   validateProfile(merged);
+  merged.customProviders = sanitizeCustomProviders(merged.customProviders);
 
   return {
     profile: merged,
@@ -82,6 +98,13 @@ export function buildProfileJson(resolved) {
     defaultAgents: profile.defaultAgents,
     defaultComponents: profile.defaultComponents,
     applyMode: profile.applyMode,
+    preferredBackend: profile.preferredBackend,
+    preferredModel: profile.preferredModel,
+    cloudConsent: profile.cloudConsent,
+    tokenBudget: profile.tokenBudget,
+    stableContextBudget: profile.stableContextBudget,
+    requestContextBudget: profile.requestContextBudget,
+    customProviders: sanitizeCustomProviders(profile.customProviders),
     sources: {
       global: sources.global,
       project: sources.project,
@@ -143,4 +166,132 @@ function validateProfile(profile) {
   if (profile.defaultComponents != null && !Array.isArray(profile.defaultComponents)) {
     throw new Error("Profile defaultComponents must be an array or null.");
   }
+
+  if (profile.cloudConsent != null && typeof profile.cloudConsent !== "boolean") {
+    throw new Error("Profile cloudConsent must be a boolean.");
+  }
+
+  for (const key of ["tokenBudget", "stableContextBudget", "requestContextBudget"]) {
+    if (profile[key] != null && (!Number.isFinite(profile[key]) || profile[key] < 1)) {
+      throw new Error(`Profile ${key} must be a positive number or null.`);
+    }
+  }
+
+  if (profile.preferredBackend != null && typeof profile.preferredBackend !== "string") {
+    throw new Error("Profile preferredBackend must be a string or null.");
+  }
+
+  if (profile.preferredModel != null && typeof profile.preferredModel !== "string") {
+    throw new Error("Profile preferredModel must be a string or null.");
+  }
+
+  validateNoSecrets(profile);
+  validateCustomProviders(profile.customProviders);
+}
+
+/**
+ * Secret-looking key segments after camelCase → snake_case normalization.
+ * `api_key_env` is the only credential-related key allowed (env var name, not a secret).
+ */
+const SECRET_KEY_PATTERN = /(^|_)(api_?key|api_?token|access_?token|auth_?token|client_?secret|private_?key|authorization(_header)?|password|secrets?|credentials?|bearer|token)(_|$)/;
+const SECRET_KEY_ALLOWLIST = new Set([
+  "api_key_env",
+  "token_budget",
+  "stable_context_budget",
+  "request_context_budget"
+]);
+const SECRET_VALUE_PATTERN = /^(sk-[A-Za-z0-9]|sk-or-|gh[pousr]_|xox[baprs]-|AKIA[0-9A-Z]{16}\b|Bearer\s+\S+|eyJ[A-Za-z0-9_-]+\.)|-----BEGIN [A-Z ]*PRIVATE KEY-----/i;
+
+export function normalizeProfileKey(key) {
+  return String(key)
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+    .replace(/-/g, "_")
+    .toLowerCase();
+}
+
+export function isForbiddenSecretKey(key) {
+  const normalized = normalizeProfileKey(key);
+  if (SECRET_KEY_ALLOWLIST.has(normalized)) return false;
+  return SECRET_KEY_PATTERN.test(normalized);
+}
+
+function validateNoSecrets(profile) {
+  walkForSecrets(profile);
+}
+
+function walkForSecrets(value) {
+  if (typeof value === "string") {
+    if (SECRET_VALUE_PATTERN.test(value)) {
+      throw new Error("Profile must not store credential-like values. Use environment variables.");
+    }
+    return;
+  }
+  if (value == null || typeof value !== "object") return;
+
+  for (const [key, nested] of Object.entries(value)) {
+    const normalizedKey = normalizeProfileKey(key);
+
+    // apiKeyEnv is the only allowed credential-related key: it names an env var.
+    if (normalizedKey === "api_key_env") {
+      if (typeof nested === "string" && SECRET_VALUE_PATTERN.test(nested)) {
+        throw new Error("Profile must not store credential-like values. Use environment variables.");
+      }
+      continue;
+    }
+
+    if (isForbiddenSecretKey(key)) {
+      throw new Error(`Profile must not store credentials (rejected key "${key}"). Use environment variables.`);
+    }
+    if (typeof nested === "string" && SECRET_VALUE_PATTERN.test(nested)) {
+      throw new Error("Profile must not store credential-like values. Use environment variables.");
+    }
+    walkForSecrets(nested);
+  }
+}
+
+function validateCustomProviders(providers) {
+  if (providers == null) return;
+  if (!Array.isArray(providers)) {
+    throw new Error("Profile customProviders must be an array.");
+  }
+
+  for (const provider of providers) {
+    if (provider == null || typeof provider !== "object" || Array.isArray(provider)) {
+      throw new Error("Each customProviders entry must be an object.");
+    }
+    if (!provider.baseUrl || typeof provider.baseUrl !== "string") {
+      throw new Error("customProviders entries require baseUrl.");
+    }
+    for (const key of Object.keys(provider)) {
+      if (normalizeProfileKey(key) === "api_key_env") continue;
+      if (isForbiddenSecretKey(key)) {
+        throw new Error(`customProviders must not include "${key}". Use apiKeyEnv to name an environment variable.`);
+      }
+    }
+    if (provider.apiKey != null || provider.token != null || provider.secret != null) {
+      throw new Error("customProviders must not embed secrets. Set apiKeyEnv to an environment variable name.");
+    }
+    if (provider.apiKeyEnv != null && !isValidEnvironmentName(provider.apiKeyEnv)) {
+      throw new Error("customProviders apiKeyEnv must be a valid uppercase environment variable name.");
+    }
+    const location = classifyCustomBaseUrl(provider.baseUrl);
+    if (provider.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."
+      );
+    }
+  }
+}
+
+function sanitizeCustomProviders(providers) {
+  if (!Array.isArray(providers)) return [];
+  return providers.map((provider) => ({
+    id: provider.id ?? "custom",
+    label: provider.label ?? "Custom provider",
+    baseUrl: provider.baseUrl,
+    modelId: provider.modelId ?? null,
+    apiKeyEnv: provider.apiKeyEnv ?? null,
+    local: classifyCustomBaseUrl(provider.baseUrl).local
+  }));
 }