herm-tui 1.0.0-dev.1 → 1.0.0-dev.2

package/src/utils/hermes-home.ts

@@ -1,821 +0,0 @@
-/**
- * hermes-home.ts — Reader for the ~/.hermes/ directory.
- *
- * This is herm's window into the Hermes Agent's persistent state.
- * All reads are filesystem-based (Bun APIs), no HTTP needed.
- *
- * Every piece of extracted data carries a `source: Source` field so the
- * UI can generically render clickable file links without knowing paths.
- */
-
-import { Database } from "bun:sqlite";
-import { readdir, stat } from "node:fs/promises";
-import { openSync, readSync, closeSync, readdirSync, readFileSync } from "node:fs";
-import { homedir } from "os";
-import { parse as parseYaml } from "yaml";
-import { count as tokenCount } from "./tokens";
-
-// ─── Path Resolution ─────────────────────────────────────────────────
-
-const HOME = process.env.HOME || homedir();
-const HERMES_HOME = process.env.HERMES_HOME || `${HOME}/.hermes`;
-
-/** Resolve a path relative to ~/.hermes/ */
-export const hermesPath = (relative: string): string =>
-  `${HERMES_HOME}/${relative}`;
-
-/** Detect a package-manager-owned install. Two signals, matching
- *  hermes_cli/config.py:get_managed_system — HERMES_MANAGED env var
- *  (systemd service sets it) or the `.managed` marker file (NixOS
- *  activation script touches it so interactive shells see it too). */
-export const managedSystem = async (): Promise<string | null> => {
-  const env = (process.env.HERMES_MANAGED ?? "").trim()
-  if (env) {
-    const norm = env.toLowerCase()
-    if (norm === "1" || norm === "true" || norm === "yes" || norm === "on") return "NixOS"
-    const names: Record<string, string> = { homebrew: "Homebrew", nix: "NixOS", nixos: "NixOS" }
-    return names[norm] ?? env
-  }
-  return (await Bun.file(hermesPath(".managed")).exists()) ? "NixOS" : null
-}
-
-// ─── Source Provenance ────────────────────────────────────────────────
-
-/** Every piece of data extracted from ~/.hermes/ carries its origin file. */
-export interface Source {
-  file: string; // absolute path
-  relative: string; // relative to HERMES_HOME
-  label: string; // human-friendly display name
-}
-
-/** Build a Source for a file relative to HERMES_HOME */
-export const makeSource = (
-  relative: string,
-  label?: string,
-): Source => ({
-  file: hermesPath(relative),
-  relative,
-  label: label ?? relative.split("/").pop() ?? relative,
-});
-
-// ─── Types ───────────────────────────────────────────────────────────
-
-/** Subset of config.yaml we care about */
-export interface HermesConfig {
-  source: Source;
-  model: {
-    default: string;
-    provider: string;
-    base_url: string;
-  };
-  agent: {
-    max_turns: number;
-    reasoning_effort: string;
-  };
-  compression: {
-    enabled: boolean;
-    threshold: number;
-    target_ratio: number;
-    protect_last_n: number;
-    summary_model: string;
-  };
-  memory: {
-    memory_enabled: boolean;
-    user_profile_enabled: boolean;
-    memory_char_limit: number;
-    user_char_limit: number;
-    provider: string;
-    nudge_interval: number;
-    flush_min_turns: number;
-  };
-  display: {
-    personality: string;
-    skin: string;
-    show_cost: boolean;
-  };
-  curator: {
-    enabled: boolean;
-    interval_hours: number;
-    stale_after_days: number;
-    archive_after_days: number;
-  };
-  gateway: {
-    platforms: {
-      api_server?: {
-        enabled: boolean;
-        host: string;
-        port: number;
-      };
-    };
-  };
-}
-
-/** Memory file stats */
-export interface MemoryFileInfo {
-  source: Source;
-  content: string;
-  charCount: number;
-  charLimit: number;
-  usagePercent: number;
-  entryCount: number;
-}
-
-/** A row from the sessions table in state.db — see sessions-db.ts. */
-export type { SessionRow } from "./sessions-db"
-
-/** Live session entry from sessions/sessions.json */
-export interface LiveSession {
-  session_key: string;
-  session_id: string;
-  created_at: string;
-  updated_at: string;
-  display_name: string;
-  platform: string;
-  chat_type: string;
-  input_tokens: number;
-  output_tokens: number;
-  cache_read_tokens: number;
-  cache_write_tokens: number;
-  total_tokens: number;
-  last_prompt_tokens: number;
-  estimated_cost_usd: number;
-  cost_status: string;
-  memory_flushed: boolean;
-  origin?: {
-    platform: string;
-    chat_id: string;
-    chat_name: string;
-    user_id: string;
-    user_name: string;
-  };
-}
-
-/** A tool schema from the session JSON */
-export interface ToolInfo {
-  name: string;
-  descriptionLength: number;
-  paramsLength: number;
-}
-
-/** Skill info from the skills directory */
-export interface SkillInfo {
-  source: Source;
-  category: string;
-  name: string;
-  description: string;
-  tags: string[];
-  /**
-   * Token cost of this skill's index entry in the system prompt
-   * (name + description + tags). Body content is NOT included — it
-   * only loads on skill_view() and shows up as a tool result.
-   */
-  tokenEstimate: number;
-}
-
-/**
- * Read description/tags from a SKILL.md YAML frontmatter block.
- * Cheap — reads only the first ~2KB. Missing file / no `---` → empty.
- */
-export function readSkillFrontmatter(source: Source): { description: string; tags: string[] } {
-  try {
-    const fd = openSync(source.file, "r");
-    const buf = Buffer.alloc(2048);
-    const n = readSync(fd, buf, 0, 2048, 0);
-    closeSync(fd);
-    const head = buf.toString("utf-8", 0, n);
-    if (!head.startsWith("---")) return { description: "", tags: [] };
-    const end = head.indexOf("\n---", 3);
-    if (end < 0) return { description: "", tags: [] };
-    const fm = parseYaml(head.slice(3, end)) as Record<string, unknown>;
-    const tags = Array.isArray(fm.tags) ? fm.tags.map(String) : [];
-    return { description: String(fm.description ?? ""), tags };
-  } catch {
-    return { description: "", tags: [] };
-  }
-}
-
-/** Per-skill telemetry sidecar record (~/.hermes/skills/.usage.json). */
-export interface SkillUsage {
-  use_count: number;
-  view_count: number;
-  patch_count: number;
-  last_used_at: string | null;
-  last_viewed_at: string | null;
-  last_patched_at: string | null;
-  created_at: string | null;
-  archived_at: string | null;
-  state: "active" | "stale" | "archived";
-  pinned: boolean;
-}
-
-/**
- * Read ~/.hermes/skills/.usage.json. Keyed by skill name.
- * Returns empty record on any failure — absent sidecar is the default.
- */
-export async function readSkillUsage(): Promise<Record<string, SkillUsage>> {
-  try {
-    const f = Bun.file(hermesPath("skills/.usage.json"));
-    if (!(await f.exists())) return {};
-    const raw = await f.json() as Record<string, Partial<SkillUsage>>;
-    const out: Record<string, SkillUsage> = {};
-    for (const [k, v] of Object.entries(raw ?? {})) {
-      out[k] = {
-        use_count: Number(v.use_count ?? 0),
-        view_count: Number(v.view_count ?? 0),
-        patch_count: Number(v.patch_count ?? 0),
-        last_used_at: v.last_used_at ?? null,
-        last_viewed_at: v.last_viewed_at ?? null,
-        last_patched_at: v.last_patched_at ?? null,
-        created_at: v.created_at ?? null,
-        archived_at: v.archived_at ?? null,
-        state: (v.state as SkillUsage["state"]) ?? "active",
-        pinned: Boolean(v.pinned),
-      };
-    }
-    return out;
-  } catch {
-    return {};
-  }
-}
-
-/** Curator scheduler state (~/.hermes/skills/.curator_state). */
-export interface CuratorState {
-  last_run_at: string | null;
-  last_run_duration_seconds: number | null;
-  last_run_summary: string | null;
-  paused: boolean;
-  run_count: number;
-}
-
-export async function readCuratorState(): Promise<CuratorState | null> {
-  try {
-    const f = Bun.file(hermesPath("skills/.curator_state"));
-    if (!(await f.exists())) return null;
-    const raw = await f.json() as Partial<CuratorState>;
-    return {
-      last_run_at: raw.last_run_at ?? null,
-      last_run_duration_seconds: raw.last_run_duration_seconds ?? null,
-      last_run_summary: raw.last_run_summary ?? null,
-      paused: Boolean(raw.paused),
-      run_count: Number(raw.run_count ?? 0),
-    };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Locate the newest curator run report — returns {dir, mtime} of the
- * directory under ~/.hermes/logs/curator/ with the latest mtime.
- * Returns null if none exist.
- */
-export interface CuratorReportInfo {
-  /** Source to the REPORT.md inside the newest run dir. */
-  source: Source;
-  /** Raw REPORT.md body, trimmed. */
-  content: string;
-  /** Run dir name, e.g. "20260430-120030". */
-  runId: string;
-}
-
-export async function readLatestCuratorReport(): Promise<CuratorReportInfo | null> {
-  try {
-    const base = `${HERMES_HOME}/logs/curator`;
-    const entries = readdirSync(base, { withFileTypes: true }).filter(e => e.isDirectory());
-    if (entries.length === 0) return null;
-    // Run dirs are named YYYYMMDD-HHMMSS — lexicographic sort = chronological.
-    entries.sort((a, b) => b.name.localeCompare(a.name));
-    const runId = entries[0]!.name;
-    const rel = `logs/curator/${runId}/REPORT.md`;
-    const source = makeSource(rel);
-    const body = await Bun.file(source.file).text();
-    return { source, content: body.trim(), runId };
-  } catch {
-    return null;
-  }
-}
-
-/** One curator run — id is the YYYYMMDD-HHMMSS dir name; counts come
- *  from run.json.counts; REPORT.md is lazy-loaded on expand. */
-export type CuratorRun = {
-  id: string
-  at: number
-  archived: number; consolidated: number; added: number
-  before: number; after: number
-}
-
-export function listCuratorRuns(): CuratorRun[] {
-  try {
-    const base = `${HERMES_HOME}/logs/curator`;
-    return readdirSync(base, { withFileTypes: true })
-      .filter(e => e.isDirectory())
-      .sort((a, b) => b.name.localeCompare(a.name))
-      .flatMap(e => {
-        try {
-          const fd = openSync(`${base}/${e.name}/run.json`, "r");
-          const buf = Buffer.alloc(8192);
-          const n = readSync(fd, buf);
-          closeSync(fd);
-          const j = JSON.parse(buf.toString("utf8", 0, n));
-          const c = j.counts ?? {};
-          return [{
-            id: e.name,
-            at: Date.parse(j.started_at ?? "") / 1000 || 0,
-            archived: c.archived_this_run ?? 0,
-            consolidated: c.consolidated_this_run ?? 0,
-            added: c.added_this_run ?? 0,
-            before: c.before ?? 0, after: c.after ?? 0,
-          }];
-        } catch { return [] }
-      });
-  } catch { return [] }
-}
-
-export async function readCuratorReport(id: string): Promise<string> {
-  try {
-    return (await Bun.file(hermesPath(`logs/curator/${id}/REPORT.md`)).text()).trim();
-  } catch { return "" }
-}
-
-/** Per-skill curator event, projected out of run.json so DetailPanel
- *  can answer "what did curator do to *this* skill, and when". */
-export type LineageEvent =
-  | { kind: "transition"; run: string; at: number; from: string; to: string }
-  | { kind: "absorbed";   run: string; at: number; sources: string[] }
-  | { kind: "merged";     run: string; at: number; into: string; reason?: string }
-  | { kind: "pruned";     run: string; at: number; reason?: string }
-  | { kind: "added";      run: string; at: number }
-
-export type LineageIndex = Map<string, LineageEvent[]>
-
-type RunJson = {
-  started_at?: string
-  archived?: string[]
-  added?: string[]
-  consolidated?: { name: string; into: string; reason?: string }[]
-  pruned?: { name: string; reason?: string }[]
-  state_transitions?: { name: string; from: string; to: string }[]
-}
-
-/** Build a skill→events index across every run.json. Runs: dozens,
- *  payload: low-KB JSON each — call once per tab open. Newest-first. */
-export function indexCuratorLineage(): LineageIndex {
-  const out: LineageIndex = new Map()
-  const push = (name: string, ev: LineageEvent) => {
-    const a = out.get(name) ?? []
-    a.push(ev); out.set(name, a)
-  }
-  try {
-    const base = hermesPath("logs/curator")
-    for (const e of readdirSync(base, { withFileTypes: true })) {
-      if (!e.isDirectory()) continue
-      try {
-        const j = JSON.parse(readFileSync(`${base}/${e.name}/run.json`, "utf8")) as RunJson
-        const at = Date.parse(j.started_at ?? "") / 1000 || 0
-        const run = e.name
-        // targets absorbing 1+ sources
-        const into = new Map<string, string[]>()
-        for (const c of j.consolidated ?? []) {
-          push(c.name, { kind: "merged", run, at, into: c.into, reason: c.reason })
-          into.set(c.into, [...(into.get(c.into) ?? []), c.name])
-        }
-        for (const [tgt, srcs] of into)
-          push(tgt, { kind: "absorbed", run, at, sources: srcs })
-        for (const t of j.state_transitions ?? [])
-          push(t.name, { kind: "transition", run, at, from: t.from, to: t.to })
-        for (const p of j.pruned ?? [])
-          push(p.name, { kind: "pruned", run, at, reason: p.reason })
-        for (const n of j.added ?? [])
-          push(n, { kind: "added", run, at })
-      } catch {}
-    }
-  } catch {}
-  for (const a of out.values()) a.sort((x, y) => y.at - x.at)
-  return out
-}
-
-/**
- * Cron-generated hermes-agent changelog digest (tji.3). The cron job
- * writes ~/.hermes/herm/changelog.md as `# hermes-agent — N new
- * commits` + bullets. Splash shows the first bullet; the "N behind"
- * count already comes from session.info.update_behind, so this only
- * needs to surface the prose.
- */
-export type Changelog = { source: Source; headline: string; body: string }
-
-export function readChangelog(): Changelog | null {
-  try {
-    const source = makeSource("herm/changelog.md");
-    // Bun.file().text() is async; splash render is sync-first-frame,
-    // so openSync/readSync to keep the hot path synchronous.
-    const fd = openSync(source.file, "r");
-    const buf = Buffer.alloc(4096);
-    const n = readSync(fd, buf);
-    closeSync(fd);
-    const body = buf.toString("utf8", 0, n).trim();
-    const line = body.split("\n").find(l => /^[-*·]/.test(l.trim()));
-    return { source, headline: line?.replace(/^[-*·]\s*/, "").trim() ?? "", body };
-  } catch {
-    return null;
-  }
-}
-
-/** SOUL.md info */
-export interface SoulInfo {
-  source: Source;
-  charCount: number;
-  tokenEstimate: number;
-  /** Raw SOUL.md body. Consumed by the Context drill-down detail panel. */
-  content: string;
-}
-
-/** System prompt breakdown — full text for section parsing */
-export interface SystemPromptInfo {
-  source: Source;
-  sessionId: string;
-  text: string;
-  totalChars: number;
-  tokenEstimate: number;
-}
-
-/** Tool list with its source session file */
-export interface ToolsInfo {
-  source: Source;
-  tools: ToolInfo[];
-}
-
-// ─── Readers ─────────────────────────────────────────────────────────
-
-/** Read and parse config.yaml */
-export async function readConfig(): Promise<HermesConfig | null> {
-  try {
-    const file = Bun.file(hermesPath("config.yaml"));
-    const text = await file.text();
-    const raw = parseYaml(text);
-    return {
-      source: makeSource("config.yaml", "config.yaml"),
-      model: {
-        default: raw?.model?.default ?? "unknown",
-        provider: raw?.model?.provider ?? "auto",
-        base_url: raw?.model?.base_url ?? "",
-      },
-      agent: {
-        max_turns: raw?.agent?.max_turns ?? 60,
-        reasoning_effort: raw?.agent?.reasoning_effort ?? "medium",
-      },
-      compression: {
-        enabled: raw?.compression?.enabled ?? true,
-        threshold: raw?.compression?.threshold ?? 0.5,
-        target_ratio: raw?.compression?.target_ratio ?? 0.2,
-        protect_last_n: raw?.compression?.protect_last_n ?? 20,
-        summary_model: raw?.compression?.summary_model ?? "",
-      },
-      memory: {
-        memory_enabled: raw?.memory?.memory_enabled ?? true,
-        user_profile_enabled: raw?.memory?.user_profile_enabled ?? true,
-        memory_char_limit: raw?.memory?.memory_char_limit ?? 2200,
-        user_char_limit: raw?.memory?.user_char_limit ?? 1375,
-        provider: raw?.memory?.provider ?? "",
-        nudge_interval: raw?.memory?.nudge_interval ?? 10,
-        flush_min_turns: raw?.memory?.flush_min_turns ?? 6,
-      },
-      display: {
-        personality: raw?.display?.personality ?? "default",
-        skin: raw?.display?.skin ?? "default",
-        show_cost: raw?.display?.show_cost ?? false,
-      },
-      curator: {
-        enabled: raw?.curator?.enabled ?? true,
-        interval_hours: raw?.curator?.interval_hours ?? 168,
-        stale_after_days: raw?.curator?.stale_after_days ?? 30,
-        archive_after_days: raw?.curator?.archive_after_days ?? 90,
-      },
-      gateway: {
-        platforms: {
-          api_server: raw?.gateway?.platforms?.api_server ?? undefined,
-        },
-      },
-    };
-  } catch {
-    return null;
-  }
-}
-
-/** Read a memory file (MEMORY.md or USER.md) with limit context */
-export async function readMemoryFile(
-  filename: "MEMORY.md" | "USER.md",
-  charLimit: number,
-): Promise<MemoryFileInfo | null> {
-  try {
-    const relative = `memories/${filename}`;
-    const file = Bun.file(hermesPath(relative));
-    const content = await file.text();
-    const entryCount = content.split("§").filter((s) => s.trim()).length;
-    return {
-      source: makeSource(relative, filename),
-      content,
-      charCount: content.length,
-      charLimit,
-      usagePercent:
-        charLimit > 0 ? Math.round((content.length / charLimit) * 100) : 0,
-      entryCount,
-    };
-  } catch {
-    return null;
-  }
-}
-
-/** Read sessions/sessions.json (live session index) */
-export async function readLiveSessions(): Promise<
-  Record<string, LiveSession>
-> {
-  try {
-    const file = Bun.file(hermesPath("sessions/sessions.json"));
-    const text = await file.text();
-    return JSON.parse(text);
-  } catch {
-    return {};
-  }
-}
-
-// ─── Session store ───────────────────────────────────────────────────
-// Everything session-shaped lives in sessions-db.ts now — one readonly
-// handle, one parent→child classification rule, shared SQL. These
-// aliases preserve the old hermes-home API for home/store.ts and
-// test/hermes-home-sessions.test.ts; new code should import from
-// sessions-db directly.
-
-import {
-  roots as _roots, children as _children, lineage as _lineage,
-  search as _search,
-} from "./sessions-db"
-export type { LineageInfo, SessionHit } from "./sessions-db"
-export const queryRecentSessions = _roots
-export const querySubagents = _children
-export const queryLineage = _lineage
-export const searchSessions = _search
-
-/** Memory provider info — what's configured and available */
-export interface MemoryProviderInfo {
-  name: string;
-  active: boolean;
-  config: Record<string, string | number | boolean>;
-}
-
-// Per-provider local config/state file locations under HERMES_HOME.
-// This is lookup data, not an enumeration — discovery comes from
-// discoverMemoryProviders() below.
-const MEMORY_CFG_FILES: Record<string, string[]> = {
-  mem0: ["mem0.json"],
-  honcho: ["honcho.json"],
-  hindsight: ["hindsight/config.json"],
-  supermemory: ["supermemory.json"],
-  holographic: ["holographic.db"],
-};
-
-/** Scan the bundled hermes-agent memory-plugin dir for provider names
-    (mirrors plugins/memory/__init__.py discover's dir walk). User-
-    installed providers in $HERMES_HOME/plugins/ aren't distinguished
-    from non-memory plugins without importing them — wait for the
-    memory.providers RPC for those. */
-function discoverMemoryProviders(): string[] {
-  const names = new Set<string>(["builtin"]);
-  try {
-    for (const e of readdirSync(`${HERMES_HOME}/hermes-agent/plugins/memory`, { withFileTypes: true }))
-      if (e.isDirectory() && !e.name.startsWith("_")) names.add(e.name);
-  } catch {}
-  return [...names];
-}
-
-/** Read memory provider configs from ~/.hermes/ — one entry per
-    discovered provider, with any local config file parsed in. */
-export async function readMemoryProviders(
-  activeProvider: string,
-): Promise<MemoryProviderInfo[]> {
-  const out: MemoryProviderInfo[] = [];
-  for (const name of discoverMemoryProviders()) {
-    if (name === "builtin") { out.push({ name, active: true, config: {} }); continue; }
-    const cfg: Record<string, string | number | boolean> = {};
-    for (const f of MEMORY_CFG_FILES[name] ?? []) {
-      try {
-        const file = Bun.file(hermesPath(f));
-        if (f.endsWith(".json")) {
-          const raw = await file.json();
-          for (const [k, v] of Object.entries(raw)) {
-            if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
-              // Redact keys/tokens
-              const lower = k.toLowerCase();
-              if (lower.includes("key") || lower.includes("token") || lower.includes("secret")) {
-                cfg[k] = typeof v === "string" ? `${v.slice(0, 4)}...` : v;
-              } else {
-                cfg[k] = v;
-              }
-            }
-          }
-        } else {
-          const st = await file.stat();
-          if (st) cfg["db_size"] = `${Math.round(st.size / 1024)}KB`;
-        }
-      } catch {}
-    }
-    out.push({ name, active: name === activeProvider, config: cfg });
-  }
-  return out;
-}
-
-/** Read SOUL.md */
-export async function readSoul(): Promise<SoulInfo | null> {
-  try {
-    const file = Bun.file(hermesPath("SOUL.md"));
-    const text = await file.text();
-    return {
-      source: makeSource("SOUL.md"),
-      charCount: text.length,
-      tokenEstimate: tokenCount(text),
-      content: text,
-    };
-  } catch {
-    return null;
-  }
-}
-
-/** Read tool list from the most recent session JSON */
-export async function readToolsFromLatestSession(): Promise<ToolsInfo | null> {
-  try {
-    const glob = new Bun.Glob("session_*.json");
-    let latestPath = "";
-    let latestTime = 0;
-
-    for await (const path of glob.scan({ cwd: hermesPath("sessions") })) {
-      const file = Bun.file(hermesPath(`sessions/${path}`));
-      const stat = await file.stat();
-      if (stat && stat.mtimeMs > latestTime) {
-        latestTime = stat.mtimeMs;
-        latestPath = path;
-      }
-    }
-
-    if (!latestPath) return null;
-
-    const relative = `sessions/${latestPath}`;
-    const file = Bun.file(hermesPath(relative));
-    const data = await file.json();
-    type RawTool = { function?: { name?: string; description?: string; parameters?: unknown } };
-    const tools: ToolInfo[] = (data.tools || []).map((t: RawTool) => ({
-      name: t?.function?.name ?? "unknown",
-      descriptionLength: (t?.function?.description ?? "").length,
-      paramsLength: JSON.stringify(t?.function?.parameters ?? {}).length,
-    }));
-    return {
-      source: makeSource(relative, latestPath),
-      tools,
-    };
-  } catch {
-    return null;
-  }
-}
-
-/** Read system prompt from the most recent state.db session that has a full one */
-export function readSystemPromptInfo(): SystemPromptInfo | null {
-  try {
-    const db = new Database(hermesPath("state.db"), { readonly: true });
-    // Short prompts (~700 chars) are the generic fallback without SOUL/memory/skills.
-    const row = db
-      .query(
-        `SELECT id, system_prompt
-         FROM sessions
-         WHERE system_prompt IS NOT NULL AND length(system_prompt) > 1000
-         ORDER BY started_at DESC LIMIT 1`,
-      )
-      .get() as { id: string; system_prompt: string } | null;
-    db.close();
-    if (!row) return null;
-    return {
-      source: makeSource("state.db"),
-      sessionId: row.id,
-      text: row.system_prompt,
-      totalChars: row.system_prompt.length,
-      tokenEstimate: tokenCount(row.system_prompt),
-    };
-  } catch {
-    return null;
-  }
-}
-
-export interface CronOutput {
-  at: Date
-  path: string
-  text: string
-}
-
-/** Read the most recent cron output for a job, tail-truncated. */
-export async function readCronOutput(
-  jobId: string,
-  tailLines = 40,
-): Promise<CronOutput | null> {
-  const dir = hermesPath(`cron/output/${jobId}`);
-  let entries: string[];
-  try {
-    entries = await readdir(dir);
-  } catch {
-    return null;
-  }
-  const md = entries.filter(f => f.endsWith(".md")).sort().reverse();
-  if (md.length === 0) return null;
-  const path = `${dir}/${md[0]}`;
-  const full = await Bun.file(path).text();
-  const lines = full.trimEnd().split("\n");
-  const text =
-    lines.length > tailLines
-      ? `…(${lines.length - tailLines} earlier lines)\n` +
-        lines.slice(-tailLines).join("\n")
-      : full.trimEnd();
-  const st = await stat(path);
-  return { at: st.mtime, path, text };
-}
-
-// ─── Env File CRUD ──────────────────────────────────────────────────
-
-const ENV_PATH = hermesPath(".env");
-
-/** Parse ~/.hermes/.env into Record<string, string> */
-export async function readEnvFile(): Promise<Record<string, string>> {
-  try {
-    const text = await Bun.file(ENV_PATH).text();
-    const vars: Record<string, string> = {};
-    for (const line of text.split("\n")) {
-      const trimmed = line.trim();
-      if (!trimmed || trimmed.startsWith("#")) continue;
-      const eq = trimmed.indexOf("=");
-      if (eq < 1) continue;
-      vars[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
-    }
-    return vars;
-  } catch {
-    return {};
-  }
-}
-
-/** Update or append a KEY=VALUE in ~/.hermes/.env */
-export async function writeEnvVar(key: string, value: string): Promise<void> {
-  let text = "";
-  try {
-    text = await Bun.file(ENV_PATH).text();
-  } catch { /* file may not exist */ }
-
-  const lines = text.split("\n");
-  let found = false;
-  const updated = lines.map(line => {
-    if (line.startsWith(`${key}=`)) {
-      found = true;
-      return `${key}=${value}`;
-    }
-    return line;
-  });
-  if (!found) updated.push(`${key}=${value}`);
-
-  await Bun.write(ENV_PATH, updated.join("\n"));
-}
-
-/** Remove a key from ~/.hermes/.env */
-export async function removeEnvVar(key: string): Promise<void> {
-  let text = "";
-  try {
-    text = await Bun.file(ENV_PATH).text();
-  } catch { return; }
-
-  const lines = text.split("\n").filter(l => !l.startsWith(`${key}=`));
-  await Bun.write(ENV_PATH, lines.join("\n"));
-}
-
-// ─── Provider Catalog ───────────────────────────────────────────────
-
-export const ENV_CATALOG: ReadonlyArray<{ category: string; keys: string[] }> = [
-  {
-    category: "LLM Providers",
-    keys: [
-      "ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GOOGLE_API_KEY",
-      "DEEPSEEK_API_KEY", "OPENROUTER_API_KEY", "GROQ_API_KEY",
-      "MISTRAL_API_KEY", "XAI_API_KEY", "TOGETHER_API_KEY",
-      "FIREWORKS_API_KEY", "NOUS_API_KEY",
-    ],
-  },
-  {
-    category: "Tool API Keys",
-    keys: [
-      "FIRECRAWL_API_KEY", "BROWSERBASE_API_KEY", "BROWSERBASE_PROJECT_ID",
-      "TAVILY_API_KEY", "EXA_API_KEY", "ELEVENLABS_API_KEY",
-    ],
-  },
-  {
-    category: "Messaging",
-    keys: [
-      "TELEGRAM_BOT_TOKEN", "DISCORD_BOT_TOKEN",
-      "SLACK_BOT_TOKEN", "SLACK_APP_TOKEN",
-    ],
-  },
-  {
-    category: "Agent",
-    keys: ["API_SERVER_KEY", "MEM0_API_KEY"],
-  },
-];