@oracle-agent/oracle 0.8.0 → 0.9.0

package/src/cli/commands/bootstrap.mjs

@@ -0,0 +1,87 @@
+import {
+  HERMES_PYPI,
+  installManagedHermes,
+  runtimeStatus,
+  runtimeVenvDir,
+} from "../runtime.mjs";
+
+function usage() {
+  return [
+    "oracle bootstrap - install the local agent runtime oracle chat needs",
+    "",
+    "  oracle bootstrap            install into ~/.config/oracle/runtime/venv",
+    "  oracle bootstrap --upgrade  upgrade the managed runtime",
+    "  oracle bootstrap --status   show what runtime oracle would use",
+    "  oracle bootstrap --json     machine-readable status",
+    "",
+    "notes:",
+    "  a hermes on PATH always wins; bootstrap never touches system python",
+    "  read/prepare commands (chain, scan, route, data) never need this",
+  ].join("\n");
+}
+
+export default {
+  name: "bootstrap",
+  summary: "install the local agent runtime for oracle chat",
+  group: "read",
+  usage: usage(),
+  async run(ctx) {
+    const args = ctx.argv;
+    if (args.includes("-h") || args.includes("--help")) {
+      process.stdout.write(usage() + "\n");
+      return 0;
+    }
+
+    const json = args.includes("--json");
+    const status = runtimeStatus();
+
+    if (args.includes("--status") || json) {
+      if (json) {
+        process.stdout.write(JSON.stringify(status, null, 2) + "\n");
+        return 0;
+      }
+      process.stdout.write(
+        [
+          `hermes:        ${status.hermes.ok ? `${status.hermes.bin} (${status.hermes.source})` : "not installed"}`,
+          `managed venv:  ${status.managedVenv}`,
+          `managed built: ${status.managedInstalled ? "yes" : "no"}`,
+          `host python:   ${status.hostPython ? `${status.hostPython.bin} (${status.hostPython.version})` : "none supported (need 3.11-3.13)"}`,
+          `uv:            ${status.uv || "not installed (oracle will install it locally)"}`,
+          "",
+        ].join("\n"),
+      );
+      return 0;
+    }
+
+    const upgrade = args.includes("--upgrade");
+
+    if (status.hermes.ok && status.hermes.source === "path" && !upgrade) {
+      process.stdout.write(
+        `hermes already on PATH: ${status.hermes.bin}\nnothing to do. run: oracle\n`,
+      );
+      return 0;
+    }
+
+    process.stdout.write(
+      `installing ${HERMES_PYPI} into ${runtimeVenvDir()}\n` +
+        (status.hostPython
+          ? `using python ${status.hostPython.version} (${status.hostPython.bin})\n`
+          : "provisioning an isolated python 3.13 with uv\n") +
+        "this takes a few minutes on first run\n\n",
+    );
+
+    const r = installManagedHermes({ upgrade });
+    if (!r.ok) {
+      process.stderr.write(`oracle bootstrap failed: ${r.reason}\n`);
+      if (r.stderr) process.stderr.write(`${r.stderr}\n`);
+      return 1;
+    }
+
+    process.stdout.write(
+      r.reused
+        ? `runtime already present: ${r.bin}\n`
+        : `\nruntime ready: ${r.bin}\nrun: oracle\n`,
+    );
+    return 0;
+  },
+};

package/src/cli/commands/chat.mjs

@@ -4,13 +4,15 @@ import { spawnSync } from "node:child_process";
 import { PACKAGE_ROOT, hermesRoot, ensureDir } from "../paths.mjs";
 import { activeChainEnv } from "../chain-state.mjs";
 import { spawnChild } from "../spawn-child.mjs";
+import { installManagedHermes, resolveHermes } from "../runtime.mjs";
 
 const PROFILE = "oracle";
 const SKIN_NAME = "oracle";
 
 function which(bin) {
-  if (bin === "hermes" && process.env.ORACLE_HERMES_BIN) {
-    return process.env.ORACLE_HERMES_BIN;
+  if (bin === "hermes") {
+    const r = resolveHermes();
+    return r.ok ? r.bin : null;
   }
   for (const dir of (process.env.PATH || "").split(path.delimiter)) {
     const c = path.join(dir, bin);
@@ -21,6 +23,30 @@ function which(bin) {
   return null;
 }
 
+/**
+ * First-run bootstrap. Only fires for a real interactive TTY so scripts,
+ * pipes, and CI never trigger a multi-minute install.
+ */
+function ensureRuntime() {
+  const found = resolveHermes();
+  if (found.ok) return found.bin;
+  if (process.env.ORACLE_NO_BOOTSTRAP === "1") return null;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return null;
+
+  process.stdout.write(
+    "oracle needs a local agent runtime for chat (one-time setup).\n" +
+      "installing into ~/.config/oracle/runtime/venv, a few minutes.\n\n",
+  );
+  const r = installManagedHermes();
+  if (!r.ok) {
+    process.stderr.write(`oracle: runtime setup failed: ${r.reason}\n`);
+    if (r.stderr) process.stderr.write(`${r.stderr}\n`);
+    return null;
+  }
+  process.stdout.write("\nruntime ready.\n\n");
+  return r.bin;
+}
+
 function pythonShebang(file) {
   try {
     const first = fs.readFileSync(file, "utf8").split(/\r?\n/, 1)[0];
@@ -47,14 +73,43 @@ export function resolveHermesPython(hermes) {
   return null;
 }
 
-function harnessSourcePath() {
+export function harnessSourcePath() {
   return path.join(PACKAGE_ROOT, "src", "cli", "oracle-harness.py");
 }
 
+export function oracleHarnessInvocation(hermes, args) {
+  const harness = harnessSourcePath();
+  const runtime = process.env.ORACLE_PLAIN_HARNESS === "0"
+    ? null
+    : resolveHermesPython(hermes);
+  if (runtime && fs.existsSync(harness)) {
+    return {
+      command: runtime.command,
+      args: [...runtime.prefix, harness, ...args],
+    };
+  }
+  return { command: hermes, args };
+}
+
 function skinSourcePath() {
   return path.join(PACKAGE_ROOT, "skins", "oracle.yaml");
 }
 
+function ensureOracleProfile(profile = PROFILE) {
+  const src = path.join(PACKAGE_ROOT, "profiles", "oracle", "SOUL.md");
+  if (!fs.existsSync(src)) return { ok: false, reason: "oracle persona missing from package" };
+  const dest = path.join(hermesRoot(), "profiles", profile, "SOUL.md");
+  if (fs.existsSync(dest)) {
+    const current = fs.readFileSync(dest, "utf8");
+    if (!current.startsWith("You are Hermes Agent, an intelligent AI assistant created by Nous Research.")) {
+      return { ok: true, reused: true };
+    }
+  }
+  ensureDir(path.dirname(dest));
+  fs.copyFileSync(src, dest);
+  return { ok: true, reused: false };
+}
+
 function ensureOracleSkin(profile = PROFILE) {
   const src = skinSourcePath();
   if (!fs.existsSync(src)) return { ok: false, reason: "skin missing from package" };
@@ -141,31 +196,78 @@ function setDisplaySkin(profile = PROFILE) {
   return { ok: true };
 }
 
+function hasModelConfig(file) {
+  if (!fs.existsSync(file)) return false;
+  const text = fs.readFileSync(file, "utf8");
+  if (/^model:\s*\S+/m.test(text)) return true;
+  const block = text.match(/^model:\s*\n((?:[ \t]+.*(?:\n|$))*)/m)?.[1] || "";
+  return /^\s+(?:default|provider):\s*\S+/m.test(block);
+}
+
+function hasProviderCredentials(profile = PROFILE) {
+  const root = hermesRoot();
+  if (fs.existsSync(path.join(root, "auth.json"))) return true;
+  if (fs.existsSync(path.join(root, "profiles", profile, "auth.json"))) return true;
+  const keys = [
+    "OPENROUTER_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "XAI_API_KEY",
+    "GOOGLE_API_KEY",
+    "GEMINI_API_KEY",
+    "DEEPSEEK_API_KEY",
+    "HF_TOKEN",
+    "GLM_API_KEY",
+    "KIMI_API_KEY",
+    "MINIMAX_API_KEY",
+  ];
+  if (keys.some((key) => process.env[key])) return true;
+  for (const file of [path.join(root, ".env"), path.join(root, "profiles", profile, ".env")]) {
+    if (!fs.existsSync(file)) continue;
+    const text = fs.readFileSync(file, "utf8");
+    if (keys.some((key) => new RegExp(`^${key}=.+`, "m").test(text))) return true;
+  }
+  return false;
+}
+
+function modelReady(profile = PROFILE) {
+  const root = hermesRoot();
+  return (
+    hasModelConfig(path.join(root, "config.yaml")) ||
+    hasModelConfig(path.join(root, "profiles", profile, "config.yaml")) ||
+    hasProviderCredentials(profile)
+  );
+}
+
 function usage() {
   return [
-    "oracle chat — one lowercase oracle surface",
+    "oracle chat — filled lowercase oracle chat",
     "",
     "  oracle chat                 open interactive oracle chat",
     "  oracle chat -q \"...\"        one-shot query",
-    "  oracle chat --model <m>     pass model to hermes for this session",
-    "  oracle chat --print-banner  show plain ascii banner only",
+    "  oracle chat --model <m>     use a model for this session",
+    "  oracle chat --print-banner  show filled oracle banner only",
     "",
     "inside chat:",
     "  /chain                      list/select chains",
     "  /setup                      messaging setup menu",
     "  /model                      switch models (still one oracle persona)",
     "",
-    "brand: plain lowercase ascii oracle",
+    "brand: filled lowercase oracle / classic boxed layout",
   ].join("\n");
 }
 
 function printBanner() {
   const lines = [
     "",
-    "                 _",
-    " ___ _ _ __ _ __| |___",
-    "/ _ \\ '_/ _` / _| / -_)",
-    "\\___/_| \\__,_\\__|_\\___|",
+    "                                       ████",
+    "                                      ░░███",
+    "  ██████  ████████   ██████    ██████  ░███   ██████",
+    " ███░░███░░███░░███ ░░░░░███  ███░░███ ░███  ███░░███",
+    "░███ ░███ ░███ ░░░   ███████ ░███ ░░░  ░███ ░███████",
+    "░███ ░███ ░███      ███░░███ ░███  ███ ░███ ░███░░░",
+    "░░██████  █████    ░░████████░░██████  █████░░██████",
+    " ░░░░░░  ░░░░░      ░░░░░░░░  ░░░░░░  ░░░░░  ░░░░░░",
     "",
   ];
   process.stdout.write(lines.join("\n") + "\n");
@@ -187,23 +289,41 @@ export default {
       return 0;
     }
 
-    const hermes = which("hermes");
+    const hermes = which("hermes") || ensureRuntime();
     if (!hermes) {
       process.stderr.write(
-        "oracle chat needs hermes on PATH\n" +
-          "install: https://hermes-agent.nousresearch.com/docs\n",
+        "oracle chat needs a local agent runtime\n" +
+          "run: oracle bootstrap\n",
       );
       return 1;
     }
 
+    ensureOracleProfile(PROFILE);
     ensureOracleSkin(PROFILE);
-    ensureQuickCommands(PROFILE);
     ensureSkillCommands(PROFILE);
     const skinSet = setDisplaySkin(PROFILE);
+    ensureQuickCommands(PROFILE);
     if (!skinSet.ok && process.env.ORACLE_CLI_DEBUG) {
       process.stderr.write(`oracle chat: skin note: ${skinSet.reason}\n`);
     }
 
+    const explicitModel = args.includes("--model") || args.includes("-m") || args.includes("--provider");
+    if (!modelReady(PROFILE) && !explicitModel) {
+      if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        process.stderr.write("oracle chat needs a configured model\nrun: oracle model\n");
+        return 1;
+      }
+      process.stdout.write("choose oracle's model before first chat\n\n");
+      const modelLaunch = oracleHarnessInvocation(hermes, ["-p", PROFILE, "model"]);
+      const selected = await spawnChild(
+        modelLaunch.command,
+        modelLaunch.args,
+        { stdio: "inherit", env: process.env },
+        "oracle-model",
+      );
+      if (selected !== 0 || !modelReady(PROFILE)) return selected || 1;
+    }
+
     // Parse a few passthrough flags.
     const hermesArgs = ["-p", PROFILE, "chat"];
     const pass = [];
@@ -244,20 +364,15 @@ export default {
     const cleanEnv = activeChainEnv({
       ORACLE_CHAT_SURFACE: "1",
       ORACLE_PROFILE: PROFILE,
+      ORACLE_NODE_BIN: process.execPath,
+      ORACLE_CLI_ENTRY: path.join(PACKAGE_ROOT, "bin", "oracle.mjs"),
     });
 
-    const harness = harnessSourcePath();
-    const runtime = process.env.ORACLE_PLAIN_HARNESS === "0"
-      ? null
-      : resolveHermesPython(hermes);
-    const command = runtime && fs.existsSync(harness) ? runtime.command : hermes;
-    const launchArgs = runtime && fs.existsSync(harness)
-      ? [...runtime.prefix, harness, ...hermesArgs, ...pass]
-      : [...hermesArgs, ...pass];
+    const launch = oracleHarnessInvocation(hermes, [...hermesArgs, ...pass]);
 
     return spawnChild(
-      command,
-      launchArgs,
+      launch.command,
+      launch.args,
       {
         stdio: "inherit",
         env: cleanEnv,

package/src/cli/commands/doctor.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { DOCTOR_SIGNING_OPTIONAL } from "../first-run.mjs";
+import { resolveHermes } from "../runtime.mjs";
 
 function nodeVersionOk() {
   const [maj, min] = process.versions.node.split(".").map(Number);
@@ -17,13 +18,6 @@ function loadExecEnv(p) {
   return out;
 }
 
-function which(bin) {
-  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
-    const c = path.join(dir, bin);
-    try { if (fs.existsSync(c)) return c; } catch {}
-  }
-  return null;
-}
 
 async function probeDataServer(url) {
   try {
@@ -66,9 +60,10 @@ export default {
     push("data_server", dataUp ? "ok" : "warn", dataUp ? `reachable ${dataUrl}` : `down ${dataUrl}`,
       dataUp ? null : "oracle data serve");
 
-    const hermes = which("hermes");
-    push("hermes_cli", hermes ? "ok" : "warn", hermes ? `present ${hermes}` : "not on PATH",
-      hermes ? null : "install Hermes if you want agent lanes");
+    const runtime = resolveHermes();
+    push("agent_runtime", runtime.ok ? "ok" : "warn",
+      runtime.ok ? `present ${runtime.bin} (${runtime.source})` : "not installed",
+      runtime.ok ? null : "oracle bootstrap");
 
     const profilesDir = path.join(ctx.paths.hermesRoot(), "profiles");
     let laneCount = 0;

package/src/cli/commands/model.mjs

@@ -1,14 +1,19 @@
-import fs from "node:fs";
-import path from "node:path";
 import { spawnChild } from "../spawn-child.mjs";
+import { installManagedHermes, resolveHermes } from "../runtime.mjs";
+import { oracleHarnessInvocation } from "./chat.mjs";
 
-function hermesBin() {
-  if (process.env.ORACLE_HERMES_BIN) return process.env.ORACLE_HERMES_BIN;
-  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
-    const candidate = path.join(dir, "hermes");
-    if (fs.existsSync(candidate)) return candidate;
+function runtimeBin() {
+  const found = resolveHermes();
+  if (found.ok) return found.bin;
+  if (process.env.ORACLE_NO_BOOTSTRAP === "1") return null;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return null;
+  process.stdout.write("setting up oracle's local model runtime (one time)\n\n");
+  const installed = installManagedHermes();
+  if (!installed.ok) {
+    process.stderr.write(`oracle model: runtime setup failed: ${installed.reason}\n`);
+    return null;
   }
-  return null;
+  return installed.bin;
 }
 
 export default {
@@ -16,20 +21,21 @@ export default {
   summary: "choose the oracle profile's model/provider",
   group: "read",
   usage: [
-    "oracle model — interactive provider/model picker for the oracle profile",
+    "oracle model - interactive provider/model picker for the oracle profile",
     "",
     "inside chat: /model",
     "one oracle persona stays loaded when the model changes.",
   ].join("\n"),
   async run(ctx) {
-    const hermes = hermesBin();
+    const hermes = runtimeBin();
     if (!hermes) {
-      process.stderr.write("oracle model needs hermes on PATH\n");
+      process.stderr.write("oracle model needs the local runtime\nrun: oracle bootstrap\n");
       return 1;
     }
+    const launch = oracleHarnessInvocation(hermes, ["-p", "oracle", "model", ...ctx.argv]);
     return spawnChild(
-      hermes,
-      ["-p", "oracle", "model", ...ctx.argv],
+      launch.command,
+      launch.args,
       { stdio: "inherit", env: process.env },
       "oracle-model",
     );

package/src/cli/commands/setup.mjs

@@ -1,6 +1,4 @@
 import { spawnSync } from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import {
@@ -15,16 +13,7 @@ import {
   touchSetupState,
 } from "../setup-state.mjs";
 import { hermesRoot } from "../paths.mjs";
-
-function which(bin) {
-  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
-    const c = path.join(dir, bin);
-    try {
-      if (fs.existsSync(c)) return c;
-    } catch {}
-  }
-  return null;
-}
+import { installManagedHermes, resolveHermes } from "../runtime.mjs";
 
 function usage() {
   return [
@@ -71,14 +60,17 @@ function stripProfileArgs(args) {
 }
 
 function runHermes(argv, { inherit = true, env = process.env } = {}) {
-  const hermes = which("hermes");
-  if (!hermes) {
-    process.stderr.write(
-      "oracle setup: hermes not on PATH\ninstall hermes, then re-run\n",
-    );
+  let resolved = resolveHermes();
+  if (!resolved.ok && process.stdin.isTTY && process.stdout.isTTY && process.env.ORACLE_NO_BOOTSTRAP !== "1") {
+    process.stdout.write("setting up oracle's local messaging runtime (one time)\n\n");
+    const installed = installManagedHermes();
+    if (installed.ok) resolved = { ok: true, bin: installed.bin };
+  }
+  if (!resolved.ok) {
+    process.stderr.write("oracle setup needs the local runtime\nrun: oracle bootstrap\n");
     return 1;
   }
-  const r = spawnSync(hermes, argv, {
+  const r = spawnSync(resolved.bin, argv, {
     stdio: inherit ? "inherit" : "pipe",
     encoding: "utf8",
     env,
@@ -214,7 +206,7 @@ async function configurePlatform(profile, platformKey, inlineArgs = []) {
 
 export default {
   name: "setup",
-  summary: "configure telegram/discord/slack and other hermes messaging platforms",
+  summary: "configure telegram/discord/slack messaging platforms",
   group: "read",
   usage: usage(),
   async run(ctx) {

package/src/cli/first-run.mjs

@@ -1,9 +1,9 @@
 export const NEXT_STEPS_AFTER_INIT = [
   "oracle data serve          # loopback read/prepare plane on 127.0.0.1:8787",
   "oracle doctor              # verify",
-  "oracle chat                # one lowercase oracle surface",
+  "oracle chat                # premium oracle chat surface",
   "oracle chain list          # pick hyperliquid/base/solana/...",
-  "oracle setup               # telegram/discord/slack + hermes messaging",
+  "oracle setup               # telegram/discord/slack messaging",
   "oracle mcp install claude-code",
   "# optional, explicit second step — signing stays a separate local package:",
   "npm i -g @oracle-agent/operator",

package/src/cli/kernel.mjs

@@ -13,12 +13,13 @@ const HELP_HEADER = `oracle — self-custody multichain agent control plane`;
 
 const STATIC_HELP = `READ / RESEARCH (no keys, this package)
   oracle                      open the plain oracle chat harness (TTY)
+  oracle bootstrap            install the local agent runtime chat needs
   oracle init                 install agent lanes + read plane (dry-run by default)
   oracle doctor               check read plane; checks signer too when installed
-  oracle chat                 one lowercase oracle chat surface (multi-model)
+  oracle chat                 premium boxed oracle chat (multi-model)
   oracle model                choose the profile's default model/provider
   oracle chain                list/select working chains (hyperliquid, base, ...)
-  oracle setup                telegram/discord/slack + hermes messaging menu
+  oracle setup                telegram/discord/slack messaging menu
   oracle data serve|call|catalog|health
   oracle data-mcp             start the read-only MCP server
   oracle scan chains|head|token|pools|risk|quote|sell
@@ -26,7 +27,7 @@ const STATIC_HELP = `READ / RESEARCH (no keys, this package)
   oracle prepare              build an unsigned swap (alias of route prepare)
   oracle public serve         secret-free public HTTP surface
   oracle mcp install <t>      wire Oracle into claude-code|claude-desktop|codex|chatgpt
-  oracle upgrade              upgrade installed Hermes lanes
+  oracle upgrade              upgrade installed agent lanes
 
 SIGNING (dispatches to @oracle-agent/operator on THIS machine; never in this package)
   oracle sign init|doctor     provision / check the local signer (opt-in)
@@ -90,7 +91,7 @@ export function renderHelp(version, commands) {
   for (const cmd of commands.values()) {
     if (["help", "version"].includes(cmd.name)) continue;
     const known = new Set([
-      "init","doctor","chat","model","chain","setup","data","data-mcp","scan","route","prepare","public","mcp","upgrade",
+      "init","doctor","chat","model","chain","setup","data","data-mcp","scan","route","prepare","public","mcp","upgrade","bootstrap",
       "sign","vault","signer","runner","credential",
     ]);
     if (!known.has(cmd.name) && cmd.summary) {

package/src/cli/messaging-platforms.mjs

@@ -174,7 +174,7 @@ export function renderSetupMenu({ profile = "oracle", statuses = {} } = {}) {
   const lines = [
     "oracle setup",
     "",
-    "one oracle. many models. hermes messaging underneath.",
+    "one oracle. many models. every connected channel.",
     `profile: ${profile}`,
     "",
     "messaging platforms:",