@kal-elsam/kairo-runtime 0.14.0 → 0.16.0

package/src/global/next/work-snapshot.js

@@ -0,0 +1,216 @@
+/**
+ * kairo.work-snapshot/v1 — semantic work state for observability.
+ * Never stores prompts, transcripts, or agent-supplied workspace identity.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { harnessHomePaths } from "../paths.js";
+import { writeAtomicJson } from "../runtime/write-atomic-json.js";
+import { projectKeyForPath } from "./project-key.js";
+
+export const WORK_SNAPSHOT_SCHEMA = "kairo.work-snapshot/v1";
+
+/** Known smoke/fixture conversation ids — ignored on read, never auto-deleted. */
+export const IGNORED_SMOKE_CONVERSATION_IDS = Object.freeze([
+  "echopilot-visual-smoke"
+]);
+
+const PRIVATE_KEYS = Object.freeze([
+  "prompt", "prompts", "transcript", "transcripts", "response", "messages"
+]);
+
+const TECH_LEAK_RE =
+  /\bks_[a-f0-9]{8,}\b|kairo\.(?:work|next|session)\b|call kairo_|engramRef|schema\s*[:=]/i;
+
+export function isIgnoredSmokeConversationId(id) {
+  return Boolean(id) && IGNORED_SMOKE_CONVERSATION_IDS.includes(String(id));
+}
+
+export function looksLikeTechnicalLeak(text) {
+  return TECH_LEAK_RE.test(String(text ?? ""));
+}
+
+export function assertNoWorkPrivatePayload(input) {
+  if (!input || typeof input !== "object") return;
+  for (const key of PRIVATE_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(input, key)) {
+      throw new Error(`Private field "${key}" is not allowed on work payloads.`);
+    }
+  }
+}
+
+function snapshotsDir(homeDir, projectKey) {
+  return join(harnessHomePaths(homeDir).sessionsDir, projectKey, "snapshots");
+}
+
+/** Stable file id — avoids collisions from sanitized path characters. */
+export function snapshotFileId(conversationId) {
+  return createHash("sha256").update(String(conversationId)).digest("hex").slice(0, 32);
+}
+
+function snapshotFilePath(homeDir, projectKey, conversationId) {
+  return join(snapshotsDir(homeDir, projectKey), `${snapshotFileId(conversationId)}.json`);
+}
+
+function resolveConversationId(conversationId, snapshot) {
+  const raw = conversationId ?? snapshot?.conversationId ?? null;
+  if (typeof raw !== "string" || !raw.trim()) {
+    throw new Error("conversationId is required to save a work snapshot.");
+  }
+  return raw.trim().slice(0, 160);
+}
+
+function cleanText(value, max) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed || looksLikeTechnicalLeak(trimmed)) return null;
+  return trimmed.slice(0, max);
+}
+
+function cleanTextList(list, maxItem, maxItems) {
+  if (!Array.isArray(list)) return [];
+  return list.map((item) => cleanText(item, maxItem)).filter(Boolean).slice(0, maxItems);
+}
+
+function sanitizeDelegations(list) {
+  if (!Array.isArray(list)) return [];
+  return list
+    .map((row) => {
+      if (!row || typeof row !== "object") return null;
+      const title = cleanText(row.title ?? row.goal, 160);
+      const workId = typeof row.workId === "string" && /^kw_[a-f0-9]{32}$/i.test(row.workId)
+        ? row.workId
+        : null;
+      if (!title && !workId) return null;
+      const role = row.role === "orchestrator" || row.role === "worker" ? row.role : null;
+      const state = ["assigned", "working", "blocked", "completed", "failed"].includes(row.state)
+        ? row.state
+        : null;
+      return {
+        ...(workId ? { workId } : {}),
+        ...(title ? { title } : {}),
+        ...(role ? { role } : {}),
+        ...(state ? { state } : {})
+      };
+    })
+    .filter(Boolean)
+    .slice(0, 12);
+}
+
+export function isWorkSnapshotSchema(schema) {
+  return schema === WORK_SNAPSHOT_SCHEMA;
+}
+
+/** Build a sanitized v1 snapshot. Incomplete inputs keep nulls — never invent text. */
+export function createWorkSnapshot(input = {}) {
+  assertNoWorkPrivatePayload(input);
+  const goal = cleanText(input.goal, 160);
+  const now = cleanText(input.now, 240);
+  const next = cleanText(input.next, 240);
+  const progress = cleanTextList(input.progress, 160, 3);
+  const blockers = cleanTextList(input.blockers, 200, 12);
+  const delegations = sanitizeDelegations(input.delegations);
+  const conversationId = input.conversationId
+    ? String(input.conversationId).slice(0, 160)
+    : null;
+  const provider = input.provider ? String(input.provider).slice(0, 40) : null;
+
+  return {
+    schema: WORK_SNAPSHOT_SCHEMA,
+    goal,
+    progress,
+    now,
+    blockers,
+    next,
+    ...(delegations.length > 0 ? { delegations } : {}),
+    conversationId,
+    provider,
+    updatedAt: input.updatedAt ?? new Date().toISOString()
+  };
+}
+
+export function snapshotIsComplete(snapshot) {
+  return Boolean(
+    snapshot
+    && isWorkSnapshotSchema(snapshot.schema)
+    && snapshot.goal
+    && snapshot.now
+    && snapshot.next
+  );
+}
+
+function acceptStoredSnapshot(raw) {
+  if (!isWorkSnapshotSchema(raw?.schema)) return null;
+  if (isIgnoredSmokeConversationId(raw.conversationId)) return null;
+  return raw;
+}
+
+export async function saveWorkSnapshot(
+  homeDir,
+  projectPath,
+  conversationId,
+  snapshot,
+  deps = {}
+) {
+  const resolvedId = resolveConversationId(conversationId, snapshot);
+  const projectKey = projectKeyForPath(projectPath);
+  await mkdir(snapshotsDir(homeDir, projectKey), { recursive: true });
+  const nowIso = deps.now ? deps.now() : new Date().toISOString();
+  const payload = {
+    ...createWorkSnapshot({
+      ...snapshot,
+      conversationId: resolvedId,
+      updatedAt: nowIso
+    }),
+    projectKey,
+    updatedAt: nowIso
+  };
+  await (deps.writeAtomic ?? writeAtomicJson)(
+    snapshotFilePath(homeDir, projectKey, resolvedId),
+    payload
+  );
+  return payload;
+}
+
+export async function loadWorkSnapshot(homeDir, projectPath, conversationId) {
+  if (typeof conversationId !== "string" || !conversationId.trim()) return null;
+  const projectKey = projectKeyForPath(projectPath);
+  try {
+    const raw = JSON.parse(
+      await readFile(snapshotFilePath(homeDir, projectKey, conversationId.trim()), "utf8")
+    );
+    return acceptStoredSnapshot(raw);
+  } catch {
+    return null;
+  }
+}
+
+export async function listWorkSnapshots(homeDir, projectPath) {
+  const projectKey = projectKeyForPath(projectPath);
+  const dir = snapshotsDir(homeDir, projectKey);
+  let names = [];
+  try {
+    names = await readdir(dir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      const raw = JSON.parse(await readFile(join(dir, name), "utf8"));
+      const accepted = acceptStoredSnapshot(raw);
+      if (accepted) out.push(accepted);
+    } catch {
+      // corrupt files are skipped — callers see absence, not invented content
+    }
+  }
+  return out.sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+}
+
+/** Most recently updated real snapshot for this workspace. */
+export async function selectLatestWorkSnapshot(homeDir, projectPath) {
+  const [latest] = await listWorkSnapshots(homeDir, projectPath);
+  return latest ?? null;
+}

package/src/global/observability/fleet-activity.js

@@ -0,0 +1,197 @@
+/**
+ * Live OpenCode fleet activity from opencode.db (read-only).
+ * Parent→child sessions via session.parent_id — not token telemetry.
+ */
+import { access } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { join } from "node:path";
+import { resolveHomeDir } from "../paths.js";
+
+const DEFAULT_LIMIT = 40;
+const ACTIVE_WINDOW_MS = 15 * 60 * 1000;
+
+async function pathExists(path) {
+  try {
+    await access(path, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveOpenCodeDbPath(homeDir = resolveHomeDir()) {
+  return join(homeDir, ".local", "share", "opencode", "opencode.db");
+}
+
+export function parseSessionModel(raw) {
+  if (raw == null || raw === "") return { model: null, modelShort: null, providerId: null };
+  if (typeof raw === "object" && !Array.isArray(raw)) {
+    const id = typeof raw.id === "string" ? raw.id : null;
+    const providerID = typeof raw.providerID === "string" ? raw.providerID : null;
+    const model = id && providerID ? `${providerID}/${id}` : id;
+    return { model, modelShort: id, providerId: providerID };
+  }
+  if (typeof raw !== "string") return { model: null, modelShort: null, providerId: null };
+  try {
+    return parseSessionModel(JSON.parse(raw));
+  } catch {
+    const slash = raw.lastIndexOf("/");
+    return {
+      model: raw,
+      modelShort: slash >= 0 ? raw.slice(slash + 1) : raw,
+      providerId: slash >= 0 ? raw.slice(0, slash) : null
+    };
+  }
+}
+
+function sessionState(row, nowMs, activeWindowMs) {
+  if (row.time_archived) return "archived";
+  if (typeof row.time_updated === "number" && nowMs - row.time_updated <= activeWindowMs) {
+    return "active";
+  }
+  return "idle";
+}
+
+/**
+ * Pure mapper: DB rows → activity tree nodes.
+ */
+export function mapSessionRowsToActivity(rows = [], {
+  nowMs = Date.now(),
+  activeWindowMs = ACTIVE_WINDOW_MS
+} = {}) {
+  const sessions = rows.map((row) => {
+    const parsed = parseSessionModel(row.model);
+    return {
+      id: String(row.id),
+      parentId: row.parent_id ? String(row.parent_id) : null,
+      title: typeof row.title === "string" ? row.title : "",
+      agent: typeof row.agent === "string" ? row.agent : null,
+      model: parsed.model,
+      modelShort: parsed.modelShort,
+      providerId: parsed.providerId,
+      timeCreated: row.time_created ?? null,
+      timeUpdated: row.time_updated ?? null,
+      state: sessionState(row, nowMs, activeWindowMs),
+      platform: "opencode"
+    };
+  });
+
+  const byAgent = new Map();
+  for (const s of sessions) {
+    const key = s.agent ?? "unknown";
+    const prev = byAgent.get(key);
+    if (!prev || (s.timeUpdated ?? 0) > (prev.timeUpdated ?? 0)) {
+      byAgent.set(key, s);
+    }
+  }
+
+  const agents = [...byAgent.entries()]
+    .map(([id, session]) => ({
+      id,
+      state: session.state === "archived" ? "idle" : session.state,
+      model: session.model,
+      modelShort: session.modelShort,
+      sessionId: session.id,
+      parentId: session.parentId,
+      title: session.title,
+      timeUpdated: session.timeUpdated
+    }))
+    .sort((a, b) => {
+      if (a.state === "active" && b.state !== "active") return -1;
+      if (b.state === "active" && a.state !== "active") return 1;
+      return (b.timeUpdated ?? 0) - (a.timeUpdated ?? 0);
+    });
+
+  return {
+    platform: "opencode",
+    sessions,
+    agents,
+    activeCount: agents.filter((a) => a.state === "active").length,
+    source: "opencode.db"
+  };
+}
+
+function openReadonlyDb(dbPath, DatabaseSync) {
+  return new DatabaseSync(dbPath, { readOnly: true });
+}
+
+/**
+ * Read recent OpenCode sessions (read-only). Inject openDatabase for tests.
+ */
+export async function buildOpenCodeActivity({
+  homeDir = resolveHomeDir(),
+  limit = DEFAULT_LIMIT,
+  activeWindowMs = ACTIVE_WINDOW_MS,
+  nowMs = Date.now(),
+  exists = pathExists,
+  openDatabase = null,
+  DatabaseSync = null
+} = {}) {
+  const dbPath = resolveOpenCodeDbPath(homeDir);
+  if (!(await exists(dbPath))) {
+    return {
+      ok: true,
+      available: false,
+      note: "OpenCode session DB not found.",
+      dbPath,
+      platform: "opencode",
+      sessions: [],
+      agents: [],
+      activeCount: 0,
+      generatedAt: new Date(nowMs).toISOString()
+    };
+  }
+
+  let rows = [];
+  try {
+    let Database = DatabaseSync;
+    if (!Database) {
+      const prior = process.emitWarning;
+      process.emitWarning = function muted(warning, ...rest) {
+        const msg = typeof warning === "string" ? warning : (warning?.message ?? "");
+        if (/SQLite is an experimental feature/i.test(String(msg))) return;
+        return prior.apply(process, [warning, ...rest]);
+      };
+      try {
+        ({ DatabaseSync: Database } = await import("node:sqlite"));
+      } finally {
+        process.emitWarning = prior;
+      }
+    }
+    const open = openDatabase ?? ((path) => openReadonlyDb(path, Database));
+    const db = open(dbPath);
+    try {
+      const stmt = db.prepare(`
+        SELECT id, parent_id, title, agent, model, time_created, time_updated, time_archived
+        FROM session
+        ORDER BY time_updated DESC
+        LIMIT ?
+      `);
+      rows = stmt.all(Math.max(1, Math.min(Number(limit) || DEFAULT_LIMIT, 200)));
+    } finally {
+      db.close?.();
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      available: false,
+      note: `Could not read OpenCode DB: ${error?.message ?? error}`,
+      dbPath,
+      platform: "opencode",
+      sessions: [],
+      agents: [],
+      activeCount: 0,
+      generatedAt: new Date(nowMs).toISOString()
+    };
+  }
+
+  const mapped = mapSessionRowsToActivity(rows, { nowMs, activeWindowMs });
+  return {
+    ok: true,
+    available: true,
+    note: "Live OpenCode sessions (declared parent→child). Not Cursor/Claude live.",
+    dbPath,
+    ...mapped,
+    generatedAt: new Date(nowMs).toISOString()
+  };
+}

package/src/global/observability/fleet-models-catalog.js

@@ -0,0 +1,137 @@
+/**
+ * Declared / known model catalogs per platform (read-only discovery).
+ * Not a live marketplace scrape — what is configured or known-safe on disk.
+ */
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveHomeDir } from "../paths.js";
+import { parseCodexDefaultModel, parseFrontmatterModel } from "./fleet-platforms.js";
+
+export const CLAUDE_TIERS = Object.freeze(["opus", "sonnet", "haiku"]);
+
+export const CURSOR_AGENT_MODELS = Object.freeze(["inherit", "fast"]);
+
+async function readJson(path, read) {
+  try {
+    return JSON.parse(await read(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function collectOpenCodeModels(homeDir, read) {
+  const path = join(homeDir, ".config", "opencode", "opencode.json");
+  const config = await readJson(path, read);
+  const ids = new Set();
+  if (typeof config?.model === "string") ids.add(config.model);
+  for (const raw of Object.values(config?.agent ?? config?.agents ?? {})) {
+    if (typeof raw?.model === "string") ids.add(raw.model);
+  }
+  return {
+    platform: "opencode",
+    kind: "multi",
+    path,
+    available: [...ids].sort(),
+    enabled: typeof config?.model === "string" ? [config.model] : [],
+    note: "From opencode.json (declared agents + default)."
+  };
+}
+
+async function collectClaudeModels(homeDir, read, list = readdir) {
+  const settingsPath = join(homeDir, ".claude", "settings.json");
+  const settings = await readJson(settingsPath, read);
+  const enabled = [];
+  if (typeof settings?.model === "string") enabled.push(settings.model);
+  try {
+    const dir = join(homeDir, ".claude", "agents");
+    for (const name of await list(dir)) {
+      if (!name.endsWith(".md")) continue;
+      const meta = parseFrontmatterModel(await read(join(dir, name), "utf8"));
+      if (meta.model) enabled.push(meta.model);
+    }
+  } catch { /* missing */ }
+  return {
+    platform: "claude",
+    kind: "multi",
+    path: settingsPath,
+    available: [...CLAUDE_TIERS],
+    enabled: [...new Set(enabled)],
+    note: "Claude Code tiers (opus/sonnet/haiku) + agents frontmatter."
+  };
+}
+
+async function collectCodexModels(homeDir, read) {
+  const path = join(homeDir, ".codex", "config.toml");
+  let current = null;
+  try {
+    current = parseCodexDefaultModel(await read(path, "utf8"));
+  } catch { /* missing */ }
+  return {
+    platform: "codex",
+    kind: "single",
+    path,
+    available: current ? [current] : [],
+    enabled: current ? [current] : [],
+    note: "Single default model in config.toml (no per-phase minions)."
+  };
+}
+
+async function collectCursorModels(homeDir, read, list = readdir) {
+  const cliPath = join(homeDir, ".cursor", "cli-config.json");
+  const cli = await readJson(cliPath, read);
+  const cliModel = cli?.model?.modelId ?? cli?.model?.displayModelId ?? null;
+  const agentModels = new Set();
+  try {
+    const dir = join(homeDir, ".cursor", "agents");
+    for (const name of await list(dir)) {
+      if (!name.endsWith(".md")) continue;
+      const meta = parseFrontmatterModel(await read(join(dir, name), "utf8"));
+      if (meta.model) agentModels.add(meta.model);
+    }
+  } catch { /* missing */ }
+  return {
+    platform: "cursor",
+    kind: "multi",
+    path: join(homeDir, ".cursor", "agents"),
+    available: [...CURSOR_AGENT_MODELS, ...(cliModel ? [cliModel] : [])],
+    enabled: [...agentModels],
+    cliDefault: cliModel,
+    note: "Agent frontmatter usually inherit/fast. Auto chat model is IDE-managed (see cli-config)."
+  };
+}
+
+/**
+ * Catalog of available + enabled models for each tooling surface.
+ */
+export async function buildFleetModelsCatalog({
+  homeDir = resolveHomeDir(),
+  read = readFile,
+  list = readdir
+} = {}) {
+  const platforms = await Promise.all([
+    collectOpenCodeModels(homeDir, read),
+    collectClaudeModels(homeDir, read, list),
+    collectCodexModels(homeDir, read),
+    collectCursorModels(homeDir, read, list)
+  ]);
+  return {
+    ok: true,
+    kind: "catalog",
+    note: "Available = known/declared for that tool. Enabled = currently referenced on disk.",
+    platforms,
+    generatedAt: new Date().toISOString()
+  };
+}
+
+export function formatFleetModelsText(catalog) {
+  const lines = ["Fleet models (available · enabled)", ""];
+  for (const p of catalog.platforms ?? []) {
+    lines.push(`${p.platform} · ${p.kind}${p.cliDefault ? ` · cli ${p.cliDefault}` : ""}`);
+    lines.push(`  available · ${(p.available ?? []).join(", ") || "—"}`);
+    lines.push(`  enabled   · ${(p.enabled ?? []).join(", ") || "—"}`);
+    if (p.note) lines.push(`  ${p.note}`);
+    lines.push("");
+  }
+  lines.push(catalog.note ?? "");
+  return lines.join("\n").trimEnd();
+}