@kal-elsam/kairo-runtime 0.1.5 → 0.2.0

package/README.md

@@ -161,6 +161,14 @@ kairo install --agents all
 kairo install --agents cursor,codex --components orchestrator,sdd-core
 kairo doctor
 kairo doctor --json
+kairo orchestrator --json
+kairo intelligence status
+kairo intelligence models
+kairo intelligence context --json
+kairo intelligence route --task "explain architecture"
+kairo intelligence ask --prompt "Summarize project risks" --json
+# Cloud (OpenRouter/free) only after explicit consent + confirm:
+# OPENROUTER_API_KEY=... kairo intelligence ask --prompt "..." --cloud-consent --yes
 kairo update   # technical alias; prefer sync
 kairo detect
 kairo components
@@ -180,6 +188,21 @@ kairo uninstall
 kairo install --scope=workspace   # opt-in / legacy
 ```
 
+### Intelligence layer (0.2.0)
+
+Kairo owns **Harness Engineering** governance: compile relevant project context, route to a backend, and require human confirmation for cloud transmission. It does not store credentials.
+
+| Backend | Detection | Invoke |
+|---|---|---|
+| Ollama | `GET $OLLAMA_HOST/api/tags` (default `http://127.0.0.1:11434`) | Local chat |
+| OpenRouter | `OPENROUTER_API_KEY` in env | `openrouter/free` after `--cloud-consent` + `--yes` |
+| Custom HTTP | Profile `customProviders` (`baseUrl`, `modelId`, optional local-only `apiKeyEnv`) | OpenAI-compatible `/chat/completions` |
+
+Routing order: user override → Ollama → OpenRouter free (consent) → diagnostics mode.
+
+Private paths (`.env`, secrets, keys) are excluded from context packs unless `--include-private`.
+Remote custom providers require explicit cloud consent and cannot receive an `apiKeyEnv` credential in 0.2.0; use a built-in provider or a local custom endpoint for env-backed authentication.
+
 Legacy CLI aliases (backward compatible): `harness`, `agentic-harness`, `sgs-harness`, `harness-sgs`
 
 `kairo help` lists commands and JSON support; longer examples live in this README.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Gemini, Copilot, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",

package/src/cli.js

@@ -31,6 +31,7 @@ import { applyPolicyToOptions, loadPolicyFile } from "./global/policy.js";
 import { resolveHomeDir } from "./global/paths.js";
 import { runWorkspaceDetect, runWorkspaceDoctor, runWorkspaceInit, runWorkspaceUpdate } from "./workspace-cli.js";
 import { runOrchestratorDiagnostics, runOrchestratorShell } from "./global/orchestrator.js";
+import { runIntelligenceCli } from "./global/intelligence-cli.js";
 import {
   LEGACY_PACKAGE_NAME,
   PACKAGE_NAME,
@@ -85,6 +86,9 @@ export async function runCli(argv) {
         json: optionsWithPolicy.json
       });
       return;
+    case "intelligence":
+      await runIntelligenceCli(optionsWithPolicy, packageManifest);
+      return;
     case "setup":
       await runGlobalSetup(optionsWithPolicy, packageManifest, packageRoot);
       return;
@@ -324,7 +328,13 @@ export function parseArgs(argv) {
     simple: false,
     help: false,
     version: false,
-    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY)
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    intelligenceAction: null,
+    intelligenceTask: null,
+    intelligencePrompt: null,
+    intelligencePaths: [],
+    includePrivate: false,
+    cloudConsent: false
   };
 
   if (command === "components") {
@@ -339,6 +349,10 @@ export function parseArgs(argv) {
     parseHistoryAction(args, options);
   }
 
+  if (command === "intelligence") {
+    parseIntelligenceAction(args, options);
+  }
+
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
 
@@ -400,6 +414,14 @@ export function parseArgs(argv) {
     else if (arg === "--out") options.outPath = resolve(args[++index]);
     else if (arg.startsWith("--out=")) options.outPath = resolve(arg.slice("--out=".length));
     else if (arg === "--simple") options.simple = true;
+    else if (arg === "--task") options.intelligenceTask = args[++index];
+    else if (arg.startsWith("--task=")) options.intelligenceTask = arg.slice("--task=".length);
+    else if (arg === "--prompt") options.intelligencePrompt = args[++index];
+    else if (arg.startsWith("--prompt=")) options.intelligencePrompt = arg.slice("--prompt=".length);
+    else if (arg === "--paths") options.intelligencePaths = parsePathList(args[++index]);
+    else if (arg.startsWith("--paths=")) options.intelligencePaths = parsePathList(arg.slice("--paths=".length));
+    else if (arg === "--include-private") options.includePrivate = true;
+    else if (arg === "--cloud-consent") options.cloudConsent = true;
     else if (arg === "--help" || arg === "-h") options.help = true;
     else if (arg === "--version" || arg === "-v") options.version = true;
     else throw new Error(`Unknown option "${arg}".`);
@@ -490,6 +512,31 @@ function parseHistoryAction(args, options) {
   throw new Error(`Unknown history action "${action}". Use last or omit for the full log.`);
 }
 
+function parseIntelligenceAction(args, options) {
+  const action = args[0];
+  if (!action || action.startsWith("-")) {
+    options.intelligenceAction = "status";
+    return;
+  }
+
+  args.shift();
+  const allowed = new Set(["status", "models", "context", "route", "ask"]);
+  if (!allowed.has(action)) {
+    throw new Error(`Unknown intelligence action "${action}". Use status, models, context, route, or ask.`);
+  }
+  options.intelligenceAction = action;
+}
+
+function parsePathList(value) {
+  if (!value) return [];
+  return [...new Set(
+    value
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean)
+  )];
+}
+
 function parsePositiveInt(value, label) {
   const parsed = Number.parseInt(value, 10);
   if (!Number.isFinite(parsed) || parsed < 1) {
@@ -512,6 +559,7 @@ function normalizeCommand(command) {
   if (command === "install" || command === "i") return "install";
   if (command === "shell") return "shell";
   if (command === "orchestrator") return "orchestrator";
+  if (command === "intelligence" || command === "intel") return "intelligence";
   if (command === "setup") return "setup";
   if (command === "status") return "status";
   if (command === "sync") return "sync";
@@ -573,6 +621,8 @@ Usage:
   ${cli} --version
   ${cli} shell                          Interactive orchestrator shell (TTY)
   ${cli} orchestrator [--json]          Read-only agent capability diagnostics
+  ${cli} intelligence [status|models|context|route|ask] [--json]
+  ${cli} intelligence ask --prompt "..." [--cloud-consent] [--yes] [--paths a,b]
   ${cli} setup [--dry-run] [--yes] [--confirm] [--simple] [--no-preflight] [--agents <list|all>] [--components <list>]
   ${cli} status [--json]
   ${cli} sync [--dry-run] [--yes] [--confirm] [--json] [--no-preflight]
@@ -608,6 +658,9 @@ Scopes:
 Commands:
   shell      Interactive Ink orchestrator (TTY). Bare ${cli} opens this in TTY sessions.
   orchestrator  Read-only capability registry diagnostics (--json supported).
+  intelligence  Harness Engineering layer: backends, context packs, routing, budgets.
+             Local-first (Ollama). Cloud (OpenRouter/free) only with --cloud-consent.
+             Credentials via env only (OPENROUTER_API_KEY, OLLAMA_HOST). Never stored.
   setup      Managed ecosystem setup. Interactive Ink UI (TTY). Use --simple for Clack prompts.
   status     Control panel: agents, components, drift, backups, next action.
   sync       Converge managed content (repair drift), then show status.

package/src/global/action-planner.js

@@ -2,6 +2,11 @@ import { CAPABILITY_STATES } from "./capability-states.js";
 import { inspectAllCapabilities } from "./capability-registry.js";
 import { resolveProfile, resolveProfileAgents } from "./profile.js";
 import { formatCliCommand } from "./brand/cli.js";
+import {
+  inspectIntelligenceBackends,
+  summarizeIntelligenceBackends,
+  resolveRoutingDecision
+} from "./intelligence/index.js";
 
 export const PLAN_ACTIONS = {
   DIAGNOSE: "diagnose",
@@ -16,16 +21,32 @@ export async function buildReadOnlyDiagnostics({
   workspaceRoot,
   packageName,
   packageRoot,
-  cliVersion
+  cliVersion,
+  env = process.env,
+  fetchImpl = globalThis.fetch
 }) {
   const [{ profile, sources }, capabilities] = await Promise.all([
     resolveProfile({ homeDir, workspaceRoot }),
     inspectAllCapabilities({ homeDir, workspaceRoot, packageName })
   ]);
 
+  const intelligence = await inspectIntelligenceBackends({
+    env,
+    fetchImpl,
+    customProviders: profile.customProviders ?? []
+  });
+
   const detectedIds = capabilities.filter((entry) => entry.detected).map((entry) => entry.id);
   const profileAgents = resolveProfileAgents(profile, detectedIds);
   const diagnostics = summarizeDiagnostics(capabilities);
+  const intelligenceSummary = summarizeIntelligenceBackends(intelligence);
+  const routingPreview = resolveRoutingDecision({
+    backends: intelligence,
+    profile,
+    // Session consent only — profile.cloudConsent is a preference, never live authorization.
+    cloudConsent: false,
+    tokenBudget: profile.tokenBudget
+  });
 
   return {
     readOnly: true,
@@ -34,7 +55,18 @@ export async function buildReadOnlyDiagnostics({
     capabilities,
     profileAgents,
     diagnostics,
-    recommendations: buildDiagnosticRecommendations({ capabilities, profile, diagnostics })
+    intelligence: {
+      backends: intelligence,
+      summary: intelligenceSummary,
+      routingPreview
+    },
+    recommendations: buildDiagnosticRecommendations({
+      capabilities,
+      profile,
+      diagnostics,
+      intelligenceSummary,
+      routingPreview
+    })
   };
 }
 
@@ -148,7 +180,13 @@ function summarizeDiagnostics(capabilities) {
   };
 }
 
-function buildDiagnosticRecommendations({ capabilities, profile, diagnostics }) {
+function buildDiagnosticRecommendations({
+  capabilities,
+  profile,
+  diagnostics,
+  intelligenceSummary,
+  routingPreview
+}) {
   const recommendations = [];
 
   if (diagnostics.detected === 0) {
@@ -168,6 +206,20 @@ function buildDiagnosticRecommendations({ capabilities, profile, diagnostics })
     }
   }
 
+  if (!intelligenceSummary?.localAvailable && !intelligenceSummary?.cloudAuthenticated) {
+    recommendations.push(
+      "No intelligence backend available. Start Ollama or set OPENROUTER_API_KEY (env only). Diagnostics mode remains available."
+    );
+  } else if (!intelligenceSummary?.localAvailable && intelligenceSummary?.cloudAuthenticated) {
+    recommendations.push(
+      `OpenRouter is authenticated. Cloud invoke still requires session flags: ${formatCliCommand("intelligence ask --cloud-consent --yes")}.`
+    );
+  }
+
+  if (routingPreview && !routingPreview.canInvoke) {
+    recommendations.push(`Routing: ${routingPreview.reason}`);
+  }
+
   return [...new Set(recommendations)];
 }
 

package/src/global/ink/orchestrator-app.js

@@ -7,6 +7,7 @@ import {
   ORCHESTRATOR_MENU,
   ORCHESTRATOR_VIEWS,
   formatAgentStatusLines,
+  formatIntelligenceLines,
   formatPlanLines,
   formatProfileLines
 } from "./orchestrator-state.js";
@@ -143,7 +144,7 @@ export function OrchestratorApp({
 
   return React.createElement(Box, { flexDirection: "column" },
     React.createElement(Text, { bold: true, color: COLORS.accent }, `${BRAND.displayName} orchestrator`),
-    React.createElement(Text, { color: COLORS.muted }, "Provider-neutral agent coordinator · no model imposed"),
+    React.createElement(Text, { color: COLORS.muted }, "Harness Engineering · local-first · cloud opt-in"),
     React.createElement(Text, null, ""),
     renderView({ view, diagnostics, profileJson, plan, menuIndex }),
     React.createElement(Text, null, ""),
@@ -166,7 +167,12 @@ function renderView({ view, diagnostics, profileJson, plan, menuIndex }) {
         React.createElement(Text, null, ""),
         React.createElement(Text, { bold: true }, "Snapshot"),
         React.createElement(Text, null, `Agents detected: ${diagnostics.diagnostics.detected}/${diagnostics.capabilities.length}`),
-        React.createElement(Text, null, `Available: ${diagnostics.diagnostics.available}`)
+        React.createElement(Text, null, `Available: ${diagnostics.diagnostics.available}`),
+        diagnostics.intelligence && React.createElement(
+          Text,
+          null,
+          `Intelligence: local=${diagnostics.intelligence.summary.localAvailable ? "yes" : "no"} cloud=${diagnostics.intelligence.summary.cloudAuthenticated ? "yes" : "no"}`
+        )
       );
     case ORCHESTRATOR_VIEWS.AGENTS:
       return React.createElement(Box, { flexDirection: "column" },
@@ -174,6 +180,14 @@ function renderView({ view, diagnostics, profileJson, plan, menuIndex }) {
         formatAgentStatusLines(diagnostics.capabilities)
           .map((line) => React.createElement(Text, { key: line }, line))
       );
+    case ORCHESTRATOR_VIEWS.INTELLIGENCE:
+      return React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Text, { bold: true }, "Intelligence backends"),
+        formatIntelligenceLines(diagnostics)
+          .map((line) => React.createElement(Text, { key: line }, line)),
+        React.createElement(Text, null, ""),
+        React.createElement(Text, { dimColor: true }, "CLI: kairo intelligence status|models|context|route|ask")
+      );
     case ORCHESTRATOR_VIEWS.PROFILE:
       return React.createElement(Box, { flexDirection: "column" },
         React.createElement(Text, { bold: true }, "Profile"),
@@ -190,10 +204,11 @@ function renderView({ view, diagnostics, profileJson, plan, menuIndex }) {
     case ORCHESTRATOR_VIEWS.HELP:
       return React.createElement(Box, { flexDirection: "column" },
         React.createElement(Text, { bold: true }, "Help"),
-        React.createElement(Text, null, "Kairo coordinates installed agent CLIs — it is not a coding model."),
-        React.createElement(Text, null, "Use explicit commands for scripts: setup, install, status, doctor, sync."),
+        React.createElement(Text, null, "Kairo coordinates installed agent CLIs and governs project intelligence."),
+        React.createElement(Text, null, "Local-first: Ollama when available. Cloud (OpenRouter/free) needs consent."),
+        React.createElement(Text, null, "Use: intelligence status|models|context|route|ask"),
         React.createElement(Text, null, "Profiles: ~/.harness/profile.json and .harness/kairo.json (project wins)."),
-        React.createElement(Text, null, "Credentials are never stored by Kairo.")
+        React.createElement(Text, null, "Credentials are never stored by Kairo — use environment variables.")
       );
     default: {
       const _exhaustive = view;

package/src/global/ink/orchestrator-state.js

@@ -16,12 +16,14 @@ export const ORCHESTRATOR_VIEWS = {
   PROFILE: "profile",
   PLAN: "plan",
   CONFIRM: "confirm",
-  HELP: "help"
+  HELP: "help",
+  INTELLIGENCE: "intelligence"
 };
 
 export const ORCHESTRATOR_MENU = [
   { id: "status", label: "Diagnostics", view: ORCHESTRATOR_VIEWS.HOME },
   { id: "agents", label: "Agents", view: ORCHESTRATOR_VIEWS.AGENTS },
+  { id: "intelligence", label: "Intelligence", view: ORCHESTRATOR_VIEWS.INTELLIGENCE },
   { id: "profile", label: "Profile", view: ORCHESTRATOR_VIEWS.PROFILE },
   { id: "plan-setup", label: "Plan setup", view: ORCHESTRATOR_VIEWS.PLAN, action: "setup" },
   { id: "help", label: "Help", view: ORCHESTRATOR_VIEWS.HELP }
@@ -39,7 +41,11 @@ export function formatProfileLines(profileJson) {
   const lines = [
     `Coordinator: ${profileJson.coordinator ?? "none"}`,
     `Default agents: ${formatAgentsLabel(profileJson.defaultAgents)}`,
-    `Apply mode: ${profileJson.applyMode}`
+    `Apply mode: ${profileJson.applyMode}`,
+    `Preferred backend: ${profileJson.preferredBackend ?? "auto"}`,
+    `Preferred model: ${profileJson.preferredModel ?? "auto"}`,
+    `Cloud consent preference: ${profileJson.cloudConsent ? "recorded (session --cloud-consent still required)" : "no"}`,
+    `Token budget: ${profileJson.tokenBudget ?? "none"}`
   ];
 
   if (profileJson.sources.global) {
@@ -54,6 +60,29 @@ export function formatProfileLines(profileJson) {
   return lines;
 }
 
+export function formatIntelligenceLines(diagnostics) {
+  const intelligence = diagnostics?.intelligence;
+  if (!intelligence) {
+    return ["Intelligence layer unavailable."];
+  }
+
+  const lines = [
+    `Local available: ${intelligence.summary.localAvailable ? "yes" : "no"}`,
+    `Cloud authenticated: ${intelligence.summary.cloudAuthenticated ? "yes" : "no"}`,
+    `Routing: ${intelligence.routingPreview?.reason ?? "n/a"}`,
+    `Can invoke: ${intelligence.routingPreview?.canInvoke ? "yes" : "no"}`,
+    ""
+  ];
+
+  for (const backend of intelligence.backends ?? []) {
+    lines.push(
+      `${backend.label.padEnd(14)} ${backend.state.padEnd(14)} models=${backend.models?.length ?? 0}`
+    );
+  }
+
+  return lines;
+}
+
 export function formatPlanLines(plan) {
   const lines = [`Action: ${plan.action}`, ""];
   for (const step of plan.steps) {

package/src/global/intelligence/backends/custom-http.js

@@ -0,0 +1,175 @@
+import {
+  BACKEND_IDS,
+  COST_CLASSES,
+  PRIVACY_CLASSES,
+  createModelDescriptor
+} from "../types.js";
+import { fetchJson } from "../http.js";
+import { CAPABILITY_STATES } from "../../capability-states.js";
+import { classifyCustomBaseUrl, isValidEnvironmentName } from "../custom-url.js";
+
+/**
+ * OpenAI-compatible HTTP backend. API keys are read from env by name only —
+ * never from profile JSON or disk.
+ */
+export function createCustomHttpBackend({
+  id = BACKEND_IDS.CUSTOM,
+  label = "Custom provider",
+  baseUrl,
+  modelId,
+  apiKeyEnv = null,
+  local: _local = false,
+  fetchImpl = globalThis.fetch,
+  env = process.env
+} = {}) {
+  if (!baseUrl) {
+    throw new Error("Custom HTTP backend requires baseUrl.");
+  }
+
+  const location = classifyCustomBaseUrl(baseUrl);
+  const normalizedBase = location.normalizedBaseUrl;
+  if (apiKeyEnv != null && !isValidEnvironmentName(apiKeyEnv)) {
+    throw new Error("Custom provider apiKeyEnv must be a valid uppercase environment variable name.");
+  }
+  if (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."
+    );
+  }
+  const apiKey = apiKeyEnv ? (env[apiKeyEnv] ?? null) : null;
+
+  return {
+    id,
+    label,
+    local: location.local,
+
+    async detect() {
+      if (apiKeyEnv && !apiKey) {
+        return {
+          id,
+          label,
+          state: CAPABILITY_STATES.UNKNOWN,
+          detected: false,
+          available: false,
+          hasApiKey: false,
+          error: null,
+          recommendation: `Set ${apiKeyEnv} in the environment. Kairo never stores credentials.`
+        };
+      }
+
+      return {
+        id,
+        label,
+        state: CAPABILITY_STATES.DETECTED,
+        detected: true,
+        available: Boolean(modelId),
+        hasApiKey: apiKeyEnv ? Boolean(apiKey) : null,
+        error: null,
+        recommendation: modelId
+          ? `Custom provider configured (${modelId}).`
+          : "Custom provider baseUrl set; configure modelId in profile."
+      };
+    },
+
+    async listModels() {
+      if (!modelId) return [];
+      return [
+        createModelDescriptor({
+          provider: id,
+          modelId,
+          local: location.local,
+          costClass: location.local ? COST_CLASSES.LOCAL : COST_CLASSES.UNKNOWN,
+          privacyClass: location.local ? PRIVACY_CLASSES.LOCAL : PRIVACY_CLASSES.CLOUD,
+          opaque: true
+        })
+      ];
+    },
+
+    async capabilities() {
+      const detection = await this.detect();
+      return {
+        id,
+        local: location.local,
+        cloud: !location.local,
+        requiresApiKey: Boolean(apiKeyEnv),
+        requiresConsent: !location.local,
+        streaming: false,
+        tools: false,
+        state: detection.state,
+        baseUrl: normalizedBase,
+        modelId
+      };
+    },
+
+    async invoke(contextPack, request = {}) {
+      if (apiKeyEnv && !apiKey) {
+        return invokeError(id, `Missing ${apiKeyEnv}. Kairo never stores credentials.`);
+      }
+
+      const resolvedModel = request.modelId ?? modelId;
+      if (!resolvedModel) {
+        return invokeError(id, "Custom invoke requires modelId.");
+      }
+
+      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 });
+      }
+
+      const headers = { "Content-Type": "application/json" };
+      if (apiKey && location.credentialSafe) headers.Authorization = `Bearer ${apiKey}`;
+
+      const result = await fetchJson(`${normalizedBase}/chat/completions`, {
+        method: "POST",
+        headers,
+        body: {
+          model: resolvedModel,
+          messages,
+          stream: false
+        },
+        timeoutMs: request.timeoutMs ?? 120000,
+        fetchImpl
+      });
+
+      if (!result.ok) {
+        return invokeError(id, result.error ?? "Custom provider chat failed.");
+      }
+
+      const content = result.data?.choices?.[0]?.message?.content ?? "";
+      const usage = result.data?.usage ?? {};
+
+      return {
+        ok: true,
+        backendId: id,
+        model: resolvedModel,
+        content,
+        usage: {
+          inputTokens: usage.prompt_tokens ?? null,
+          outputTokens: usage.completion_tokens ?? null,
+          cachedTokens: null,
+          estimatedCost: null,
+          model: resolvedModel,
+          backendId: id,
+          fallbackUsed: false
+        },
+        raw: result.data
+      };
+    }
+  };
+}
+
+function invokeError(backendId, message) {
+  return {
+    ok: false,
+    backendId,
+    model: null,
+    content: null,
+    error: message,
+    usage: null
+  };
+}