@kal-elsam/kairo-runtime 0.4.2 → 0.5.0

package/src/global/intelligence/backends/opencode-cli.js

@@ -0,0 +1,247 @@
+import { spawn } from "node:child_process";
+
+const EXECUTABLE = "opencode";
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_TERMINATION_GRACE_MS = 1000;
+const DEFAULT_KILL_GRACE_MS = 1000;
+const STDERR_LIMIT = 480;
+const STDOUT_BUFFER_LIMIT = 1_048_576;
+const STDERR_BUFFER_LIMIT = STDERR_LIMIT;
+
+function isSensitiveEnvName(name) {
+  return /(?:KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL)/i.test(String(name ?? ""));
+}
+
+function appendLimited(current, chunk, limit) {
+  if (current.length >= limit) return current;
+  const next = current + String(chunk);
+  return next.length > limit ? next.slice(0, limit) : next;
+}
+
+/**
+ * Supervised, non-mutating OpenCode CLI invocation.
+ * Always uses `opencode run --format json --model` — never `--auto`.
+ * Timeout: SIGTERM → grace → SIGKILL → grace → unref + terminationFailed.
+ */
+export function runOpencodeJson({
+  modelRef,
+  prompt,
+  cwd,
+  env,
+  spawnImpl = spawn,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  terminationGraceMs = DEFAULT_TERMINATION_GRACE_MS,
+  killGraceMs = DEFAULT_KILL_GRACE_MS
+} = {}) {
+  if (!modelRef || typeof modelRef !== "string") {
+    return Promise.reject(new Error("runOpencodeJson requires modelRef."));
+  }
+  if (prompt == null) {
+    return Promise.reject(new Error("runOpencodeJson requires prompt."));
+  }
+
+  const args = ["run", "--format", "json", "--model", modelRef, String(prompt)];
+
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(EXECUTABLE, args, {
+      cwd,
+      env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timedOut = false;
+    let timers = [];
+
+    const clearTimers = () => {
+      for (const timer of timers) clearTimeout(timer);
+      timers = [];
+    };
+
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      detachIo();
+      resolve(result);
+    };
+
+    const schedule = (fn, ms) => {
+      const timer = setTimeout(fn, ms);
+      timers.push(timer);
+      return timer;
+    };
+
+    const finish = ({ status = null, signal = null, terminationFailed = false } = {}) => {
+      settle({
+        stdout,
+        stderr,
+        status,
+        signal,
+        timedOut,
+        terminationFailed
+      });
+    };
+
+    const forceUnref = () => {
+      try {
+        child.unref?.();
+      } catch {
+        /* ignore unref failures */
+      }
+    };
+
+    const onStdout = (chunk) => {
+      stdout = appendLimited(stdout, chunk, STDOUT_BUFFER_LIMIT);
+    };
+    const onStderr = (chunk) => {
+      stderr = appendLimited(stderr, chunk, STDERR_BUFFER_LIMIT);
+    };
+    // Keep listening after settle so late errors never crash Node.
+    const onError = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      detachIo();
+      reject(error);
+    };
+    const onClose = (status, signal) => {
+      finish({
+        status: status ?? null,
+        signal: signal ?? null,
+        terminationFailed: false
+      });
+    };
+
+    const detachIo = () => {
+      child.stdout?.off?.("data", onStdout);
+      child.stderr?.off?.("data", onStderr);
+      child.off?.("close", onClose);
+    };
+
+    const onTimeout = () => {
+      if (settled) return;
+      timedOut = true;
+      safeKill(child, "SIGTERM");
+      schedule(() => {
+        if (settled) return;
+        safeKill(child, "SIGKILL");
+        schedule(() => {
+          if (settled) return;
+          forceUnref();
+          finish({ terminationFailed: true });
+        }, killGraceMs);
+      }, terminationGraceMs);
+    };
+
+    schedule(onTimeout, timeoutMs);
+
+    child.stdout?.on("data", onStdout);
+    child.stderr?.on("data", onStderr);
+    child.on("error", onError);
+    child.on("close", onClose);
+  });
+}
+
+export function sanitizeCliStderr(text, { limit = STDERR_LIMIT } = {}) {
+  let out = String(text ?? "").replace(/\s+/g, " ").trim();
+  out = out.replace(/\bBearer\s+\S+/gi, "Bearer [REDACTED]");
+  out = out.replace(
+    /\b([A-Z][A-Z0-9_]*)\s*[:=]\s*(["'])(?:\\.|(?!\2).)*\2/g,
+    (match, name) => (isSensitiveEnvName(name) ? `${name}=[REDACTED]` : match)
+  );
+  out = out.replace(/\b([A-Z][A-Z0-9_]*)\s*[:=]\s*\S+/g, (match, name) => (
+    isSensitiveEnvName(name) ? `${name}=[REDACTED]` : match
+  ));
+  if (out.length > limit) {
+    if (limit <= 0) return "";
+    if (limit === 1) return "…";
+    out = `${out.slice(0, limit - 1)}…`;
+  }
+  return out;
+}
+
+function safeKill(child, signal) {
+  try {
+    if (typeof child.kill !== "function") return false;
+    return child.kill(signal) !== false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Parse NDJSON OpenCode `--format json` events into text, usage, and errors.
+ * Rejects malformed stdout explicitly (any non-empty line that is not JSON).
+ */
+export function parseOpencodeJsonEvents(stdout) {
+  const events = [];
+  const texts = [];
+  let error = null;
+  const usage = {
+    inputTokens: null,
+    outputTokens: null,
+    cachedTokens: null,
+    estimatedCost: null
+  };
+
+  const lines = String(stdout ?? "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  for (const line of lines) {
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      return {
+        content: null,
+        error: "OpenCode CLI returned malformed JSON events.",
+        events,
+        usage
+      };
+    }
+
+    events.push(event);
+
+    if (event.type === "error" || event.error) {
+      error =
+        event.error?.message ??
+        event.message ??
+        "OpenCode CLI error event";
+      continue;
+    }
+
+    if (event.type === "text") {
+      if (typeof event.part?.text === "string") texts.push(event.part.text);
+      else if (typeof event.text === "string") texts.push(event.text);
+    }
+
+    if (event.type === "step_finish" && event.part) {
+      applyStepFinishUsage(usage, event.part);
+    }
+  }
+
+  return {
+    content: texts.length > 0 ? texts.join("") : null,
+    error,
+    events,
+    usage
+  };
+}
+
+function applyStepFinishUsage(usage, part) {
+  const tokens = part.tokens ?? part.usage ?? {};
+  if (tokens.input != null || tokens.prompt != null) {
+    usage.inputTokens = tokens.input ?? tokens.prompt;
+  }
+  if (tokens.output != null || tokens.completion != null) {
+    usage.outputTokens = tokens.output ?? tokens.completion;
+  }
+  const cached = tokens.cache?.read ?? tokens.cached;
+  if (cached != null) usage.cachedTokens = cached;
+  if (typeof part.cost === "number") usage.estimatedCost = part.cost;
+}

package/src/global/intelligence/backends/opencode-evidence.js

@@ -0,0 +1,129 @@
+import { probeCommand, isExecutableAvailable } from "../../cli-probe.js";
+
+export const ENTITLEMENT_STATES = Object.freeze({
+  UNKNOWN: "unknown",
+  UNVERIFIED: "entitlement_unverified",
+  LIMIT_REACHED: "limit_reached"
+});
+
+export const BILLING_MODELS = Object.freeze({
+  GO_PLAN: "go_plan",
+  ZEN_CREDITS: "zen_credits",
+  CLI_RUNTIME: "cli_runtime"
+});
+
+/**
+ * Safe OpenCode evidence: CLI presence + `opencode auth list` + env key.
+ * Never reads auth.json. Never claims subscription/balance without HTTP evidence.
+ */
+export function collectOpencodeCliEvidence({
+  env = process.env,
+  whichImpl = isExecutableAvailable,
+  probeImpl = probeCommand
+} = {}) {
+  const cliInstalled = whichImpl("opencode", { env });
+  if (!cliInstalled) {
+    return {
+      cliInstalled: false,
+      authListOk: false,
+      authProviders: [],
+      error: null
+    };
+  }
+
+  const result = probeImpl("opencode", ["auth", "list"], {
+    env,
+    timeoutMs: 8000
+  });
+
+  if (!result.ok) {
+    return {
+      cliInstalled: true,
+      authListOk: false,
+      authProviders: [],
+      error: result.error ?? result.stderr ?? "opencode auth list failed"
+    };
+  }
+
+  return {
+    cliInstalled: true,
+    authListOk: true,
+    authProviders: parseAuthListProviders(result.stdout),
+    error: null
+  };
+}
+
+export function parseAuthListProviders(rawOutput) {
+  const plain = String(rawOutput ?? "").replace(/\u001b\[[0-9;]*m/g, "");
+  const found = new Set();
+
+  for (const line of plain.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || /credentials|environment|outro|intro/i.test(trimmed)) continue;
+
+    const match = trimmed.match(/^(?:[●*•]\s*)?(.+?)\s+(oauth|api)\s*$/i);
+    if (match) {
+      found.add(normalizeProviderLabel(match[1]));
+      continue;
+    }
+
+    if (/opencode\s+go/i.test(trimmed)) found.add("OpenCode Go");
+    if (/opencode\s+zen/i.test(trimmed)) found.add("OpenCode Zen");
+  }
+
+  return [...found].sort((a, b) => a.localeCompare(b));
+}
+
+export function hasAuthProvider(providers, product) {
+  const list = Array.isArray(providers) ? providers : [];
+  if (product === "go") {
+    return list.some((entry) => /opencode\s*go/i.test(entry) || /^go$/i.test(entry));
+  }
+  if (product === "zen") {
+    return list.some((entry) => /opencode\s*zen/i.test(entry) || /^zen$/i.test(entry));
+  }
+  return list.length > 0;
+}
+
+export function classifyModelsProbeStatus(status) {
+  if (status === 429) return ENTITLEMENT_STATES.LIMIT_REACHED;
+  if (status === 401 || status === 403) return ENTITLEMENT_STATES.UNKNOWN;
+  if (status >= 200 && status < 300) return ENTITLEMENT_STATES.UNVERIFIED;
+  return ENTITLEMENT_STATES.UNKNOWN;
+}
+
+export function buildDirectEvidenceBase({
+  product,
+  hasApiKey,
+  cliEvidence = null,
+  modelsHttpStatus = null,
+  modelsOk = false
+}) {
+  const authProviders = cliEvidence?.authProviders ?? [];
+  const configuredViaCli = hasAuthProvider(authProviders, product);
+  const configured = Boolean(hasApiKey) || configuredViaCli;
+  const authenticated = Boolean(hasApiKey) && modelsOk;
+  const entitlement = modelsHttpStatus === 429
+    ? ENTITLEMENT_STATES.LIMIT_REACHED
+    : (authenticated || configured
+      ? ENTITLEMENT_STATES.UNVERIFIED
+      : ENTITLEMENT_STATES.UNKNOWN);
+
+  return {
+    configured,
+    authenticated,
+    entitlement,
+    billingModel: product === "go" ? BILLING_MODELS.GO_PLAN : BILLING_MODELS.ZEN_CREDITS,
+    evidence: {
+      hasApiKey: Boolean(hasApiKey),
+      cliInstalled: Boolean(cliEvidence?.cliInstalled),
+      authListOk: Boolean(cliEvidence?.authListOk),
+      authProviders,
+      modelsHttpStatus
+    }
+  };
+}
+
+function normalizeProviderLabel(value) {
+  return String(value ?? "").replace(/\s+/g, " ").trim();
+}

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

@@ -0,0 +1,152 @@
+import { TRANSPORT_KINDS } from "../types.js";
+import { fetchJson } from "../http.js";
+
+export async function invokeChatCompletions({
+  baseUrl,
+  apiKey,
+  modelId,
+  contextPack,
+  request,
+  fetchImpl
+}) {
+  const result = await fetchJson(`${baseUrl}/chat/completions`, {
+    method: "POST",
+    headers: bearerHeaders(apiKey),
+    body: {
+      model: modelId,
+      messages: buildChatMessages(contextPack, request),
+      stream: false
+    },
+    timeoutMs: request.timeoutMs ?? 120000,
+    fetchImpl
+  });
+
+  if (!result.ok) {
+    return {
+      ok: false,
+      error: redactSecret(result.error ?? "chat completions failed", apiKey)
+    };
+  }
+
+  const usage = result.data?.usage ?? {};
+  return {
+    ok: true,
+    model: result.data?.model ?? modelId,
+    content: result.data?.choices?.[0]?.message?.content ?? "",
+    usage: {
+      inputTokens: usage.prompt_tokens ?? null,
+      outputTokens: usage.completion_tokens ?? null,
+      cachedTokens: usage.prompt_tokens_details?.cached_tokens ?? null,
+      estimatedCost: null
+    },
+    raw: result.data
+  };
+}
+
+export async function invokeResponses({
+  baseUrl,
+  apiKey,
+  modelId,
+  contextPack,
+  request,
+  fetchImpl
+}) {
+  const result = await fetchJson(`${baseUrl}/responses`, {
+    method: "POST",
+    headers: bearerHeaders(apiKey),
+    body: {
+      model: modelId,
+      input: buildResponsesInput(contextPack, request)
+    },
+    timeoutMs: request.timeoutMs ?? 120000,
+    fetchImpl
+  });
+
+  if (!result.ok) {
+    return {
+      ok: false,
+      error: redactSecret(result.error ?? "responses request failed", apiKey)
+    };
+  }
+
+  const usage = result.data?.usage ?? {};
+  return {
+    ok: true,
+    model: result.data?.model ?? modelId,
+    content: extractResponsesContent(result.data),
+    usage: {
+      inputTokens: usage.input_tokens ?? usage.prompt_tokens ?? null,
+      outputTokens: usage.output_tokens ?? usage.completion_tokens ?? null,
+      cachedTokens: usage.input_tokens_details?.cached_tokens ?? null,
+      estimatedCost: null
+    },
+    raw: result.data
+  };
+}
+
+export function invokeViaTransport(transport, options) {
+  if (transport === TRANSPORT_KINDS.RESPONSES) {
+    return invokeResponses(options);
+  }
+  return invokeChatCompletions(options);
+}
+
+function bearerHeaders(apiKey) {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+    "Content-Type": "application/json"
+  };
+}
+
+function redactSecret(message, secret) {
+  if (!message || !secret) return message ?? null;
+  return String(message).split(String(secret)).join("[REDACTED]");
+}
+
+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 buildResponsesInput(contextPack, request) {
+  const parts = [];
+  if (contextPack?.systemPrompt) {
+    parts.push({ role: "system", content: contextPack.systemPrompt });
+  }
+  if (Array.isArray(request.messages) && request.messages.length > 0) {
+    parts.push(...request.messages);
+  } else if (request.prompt) {
+    parts.push({ role: "user", content: request.prompt });
+  }
+  return parts;
+}
+
+function extractResponsesContent(data) {
+  if (!data) return "";
+  if (typeof data.output_text === "string") return data.output_text;
+
+  if (Array.isArray(data.output)) {
+    const texts = [];
+    for (const item of data.output) {
+      if (item?.type === "message" && Array.isArray(item.content)) {
+        for (const part of item.content) {
+          if (part?.type === "output_text" && part.text) texts.push(part.text);
+          else if (typeof part?.text === "string") texts.push(part.text);
+        }
+      } else if (typeof item?.text === "string") {
+        texts.push(item.text);
+      }
+    }
+    if (texts.length > 0) return texts.join("");
+  }
+
+  return data?.choices?.[0]?.message?.content ?? "";
+}

package/src/global/intelligence/backends/opencode-invoke.js

@@ -0,0 +1,83 @@
+import { OPENCODE_API_KEY_ENV } from "../types.js";
+import {
+  isDirectTransport,
+  normalizeModelId,
+  resolveOpencodeTransport,
+  toRuntimeModelRef
+} from "../transport-registry.js";
+import { invokeViaTransport } from "./opencode-http.js";
+import { resolveOpencodeApiKey, redactSecret } from "./opencode-catalog.js";
+
+/**
+ * Compose direct HTTP invoke onto an OpenCode catalog backend.
+ * No Go→Zen fallback here — routing owns that policy.
+ */
+export function withOpencodeDirectInvoke(catalog, {
+  env = process.env,
+  apiKey = null,
+  fetchImpl = globalThis.fetch,
+  defaultModelId = null
+} = {}) {
+  const resolvedKey = resolveOpencodeApiKey({ env, apiKey });
+  const { id, label, product, baseUrl } = catalog;
+
+  return {
+    ...catalog,
+
+    async invoke(contextPack, request = {}) {
+      if (!resolvedKey) {
+        return invokeError(id, `${OPENCODE_API_KEY_ENV} is not set. Kairo never stores credentials.`);
+      }
+
+      const modelId = normalizeModelId(request.modelId) ?? defaultModelId;
+      const transport = resolveOpencodeTransport(product, modelId);
+
+      if (!isDirectTransport(transport)) {
+        const runtimeRef = toRuntimeModelRef(product, modelId) ?? modelId;
+        return invokeError(
+          id,
+          `Model ${modelId} has no direct ${label} transport. Use --backend opencode --model ${runtimeRef} with OpenCode CLI installed and authenticated.`,
+          modelId
+        );
+      }
+
+      const result = await invokeViaTransport(transport, {
+        baseUrl,
+        apiKey: resolvedKey,
+        modelId,
+        contextPack,
+        request,
+        fetchImpl
+      });
+
+      if (!result.ok) {
+        return invokeError(id, redactSecret(result.error, resolvedKey), modelId);
+      }
+
+      return {
+        ok: true,
+        backendId: id,
+        model: result.model,
+        content: result.content,
+        usage: {
+          ...result.usage,
+          model: result.model,
+          backendId: id,
+          fallbackUsed: false
+        },
+        raw: result.raw
+      };
+    }
+  };
+}
+
+function invokeError(backendId, message, model = null) {
+  return {
+    ok: false,
+    backendId,
+    model,
+    content: null,
+    error: message,
+    usage: null
+  };
+}

package/src/global/intelligence/backends/opencode-providers.js

@@ -0,0 +1,67 @@
+import {
+  BACKEND_IDS,
+  OPENCODE_GO_BASE_URL,
+  OPENCODE_GO_DEFAULT_MODEL,
+  OPENCODE_ZEN_BASE_URL,
+  OPENCODE_ZEN_DEFAULT_FREE_MODEL
+} from "../types.js";
+import {
+  createOpencodeCatalogBackend,
+  goCostClassForModel,
+  zenCostClassForModel
+} from "./opencode-catalog.js";
+import { withOpencodeDirectInvoke } from "./opencode-invoke.js";
+
+export function createOpencodeGoBackend({
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  apiKey = null,
+  baseUrl = OPENCODE_GO_BASE_URL,
+  collectCliEvidence
+} = {}) {
+  const catalog = createOpencodeCatalogBackend({
+    id: BACKEND_IDS.OPENCODE_GO,
+    label: "OpenCode Go",
+    product: "go",
+    baseUrl,
+    defaultModelId: OPENCODE_GO_DEFAULT_MODEL,
+    costClassForModel: goCostClassForModel,
+    env,
+    fetchImpl,
+    apiKey,
+    collectCliEvidence
+  });
+  return withOpencodeDirectInvoke(catalog, {
+    env,
+    apiKey,
+    fetchImpl,
+    defaultModelId: OPENCODE_GO_DEFAULT_MODEL
+  });
+}
+
+export function createOpencodeZenBackend({
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  apiKey = null,
+  baseUrl = OPENCODE_ZEN_BASE_URL,
+  collectCliEvidence
+} = {}) {
+  const catalog = createOpencodeCatalogBackend({
+    id: BACKEND_IDS.OPENCODE_ZEN,
+    label: "OpenCode Zen",
+    product: "zen",
+    baseUrl,
+    defaultModelId: OPENCODE_ZEN_DEFAULT_FREE_MODEL,
+    costClassForModel: zenCostClassForModel,
+    env,
+    fetchImpl,
+    apiKey,
+    collectCliEvidence
+  });
+  return withOpencodeDirectInvoke(catalog, {
+    env,
+    apiKey,
+    fetchImpl,
+    defaultModelId: OPENCODE_ZEN_DEFAULT_FREE_MODEL
+  });
+}