@oracle-agent/oracle 0.5.0 → 0.6.0

package/src/cli/commands/chat.mjs

@@ -0,0 +1,268 @@
+import fs from "node:fs";
+import path from "node:path";
+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";
+
+const PROFILE = "oracle";
+const SKIN_NAME = "oracle";
+
+function which(bin) {
+  if (bin === "hermes" && process.env.ORACLE_HERMES_BIN) {
+    return process.env.ORACLE_HERMES_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;
+}
+
+function pythonShebang(file) {
+  try {
+    const first = fs.readFileSync(file, "utf8").split(/\r?\n/, 1)[0];
+    if (!first.startsWith("#!")) return null;
+    const parts = first.slice(2).trim().split(/\s+/);
+    if (parts[0]?.endsWith("/env") && parts[1]?.startsWith("python")) {
+      return { command: parts[0], prefix: [parts[1]] };
+    }
+    if (path.basename(parts[0] || "").startsWith("python")) {
+      return { command: parts[0], prefix: parts.slice(1) };
+    }
+  } catch {}
+  return null;
+}
+
+export function resolveHermesPython(hermes) {
+  const direct = pythonShebang(hermes);
+  if (direct) return direct;
+  try {
+    const body = fs.readFileSync(hermes, "utf8");
+    const match = body.match(/["']([^"'\r\n]+\/bin\/hermes)["']/);
+    if (match) return pythonShebang(match[1]);
+  } catch {}
+  return null;
+}
+
+function harnessSourcePath() {
+  return path.join(PACKAGE_ROOT, "src", "cli", "oracle-harness.py");
+}
+
+function skinSourcePath() {
+  return path.join(PACKAGE_ROOT, "skins", "oracle.yaml");
+}
+
+function ensureOracleSkin(profile = PROFILE) {
+  const src = skinSourcePath();
+  if (!fs.existsSync(src)) return { ok: false, reason: "skin missing from package" };
+  const rootSkins = path.join(hermesRoot(), "skins");
+  const profileSkins = path.join(hermesRoot(), "profiles", profile, "skins");
+  ensureDir(rootSkins);
+  ensureDir(profileSkins);
+  const body = fs.readFileSync(src, "utf8");
+  fs.writeFileSync(path.join(rootSkins, `${SKIN_NAME}.yaml`), body);
+  fs.writeFileSync(path.join(profileSkins, `${SKIN_NAME}.yaml`), body);
+  return { ok: true, skin: SKIN_NAME };
+}
+
+function ensureQuickCommands(profile = PROFILE) {
+  // Install /chain and /setup as hermes quick commands that call oracle.
+  const cfgPath = path.join(hermesRoot(), "profiles", profile, "config.yaml");
+  if (!fs.existsSync(cfgPath)) return { ok: false, reason: "profile config missing" };
+
+  // Prefer a tiny sidecar json the chat skill can also read; hermes quick_commands
+  // live in config.yaml which we must not corrupt with naive YAML mutation.
+  // We install a hermes-facing skill command instead (see skills/oracle-chat).
+  const oracleBin = which("oracle") || path.join(PACKAGE_ROOT, "bin", "oracle.mjs");
+  const markerDir = path.join(hermesRoot(), "profiles", profile, "oracle");
+  ensureDir(markerDir);
+  const marker = {
+    profile,
+    skin: SKIN_NAME,
+    oracleBin,
+    commands: {
+      chain: [oracleBin, "chain"],
+      setup: [oracleBin, "setup"],
+    },
+    updatedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(
+    path.join(markerDir, "chat-surface.json"),
+    JSON.stringify(marker, null, 2) + "\n",
+    { mode: 0o600 },
+  );
+  return { ok: true, marker };
+}
+
+function ensureSkillCommands(profile = PROFILE) {
+  const srcDir = path.join(PACKAGE_ROOT, "skills", "oracle-chat");
+  if (!fs.existsSync(srcDir)) return { ok: false, reason: "oracle-chat skill missing" };
+  const destRoot = path.join(hermesRoot(), "profiles", profile, "skills", "oracle-chat");
+  ensureDir(destRoot);
+  for (const name of fs.readdirSync(srcDir)) {
+    const from = path.join(srcDir, name);
+    const to = path.join(destRoot, name);
+    if (fs.statSync(from).isFile()) {
+      fs.copyFileSync(from, to);
+    }
+  }
+  // Also install under profile skills root aliases for /chain and /setup.
+  for (const slug of ["chain", "setup"]) {
+    const aliasDir = path.join(hermesRoot(), "profiles", profile, "skills", slug);
+    ensureDir(aliasDir);
+    const skillMd = path.join(srcDir, `${slug}.SKILL.md`);
+    const fallback = path.join(srcDir, "SKILL.md");
+    const body = fs.existsSync(skillMd)
+      ? fs.readFileSync(skillMd, "utf8")
+      : fs.readFileSync(fallback, "utf8");
+    fs.writeFileSync(path.join(aliasDir, "SKILL.md"), body);
+  }
+  return { ok: true };
+}
+
+function setDisplaySkin(profile = PROFILE) {
+  const hermes = which("hermes");
+  if (!hermes) return { ok: false, reason: "hermes missing" };
+  // hermes config set is safe; avoids hand-editing yaml.
+  const r = spawnSync(
+    hermes,
+    ["-p", profile, "config", "set", "display.skin", SKIN_NAME],
+    { encoding: "utf8", timeout: 30_000 },
+  );
+  if (r.status !== 0) {
+    return {
+      ok: false,
+      reason: (r.stderr || r.stdout || "config set failed").trim(),
+    };
+  }
+  return { ok: true };
+}
+
+function usage() {
+  return [
+    "oracle chat — one lowercase oracle surface",
+    "",
+    "  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",
+    "",
+    "inside chat:",
+    "  /chain                      list/select chains",
+    "  /setup                      messaging setup menu",
+    "  /model                      switch models (still one oracle persona)",
+    "",
+    "brand: plain lowercase ascii oracle",
+  ].join("\n");
+}
+
+function printBanner() {
+  const lines = [
+    "",
+    "                 _",
+    " ___ _ _ __ _ __| |___",
+    "/ _ \\ '_/ _` / _| / -_)",
+    "\\___/_| \\__,_\\__|_\\___|",
+    "",
+  ];
+  process.stdout.write(lines.join("\n") + "\n");
+}
+
+export default {
+  name: "chat",
+  summary: "open the one oracle chat surface (telegram-like, multi-model)",
+  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;
+    }
+    if (args.includes("--print-banner")) {
+      printBanner();
+      return 0;
+    }
+
+    const hermes = which("hermes");
+    if (!hermes) {
+      process.stderr.write(
+        "oracle chat needs hermes on PATH\n" +
+          "install: https://hermes-agent.nousresearch.com/docs\n",
+      );
+      return 1;
+    }
+
+    ensureOracleSkin(PROFILE);
+    ensureQuickCommands(PROFILE);
+    ensureSkillCommands(PROFILE);
+    const skinSet = setDisplaySkin(PROFILE);
+    if (!skinSet.ok && process.env.ORACLE_CLI_DEBUG) {
+      process.stderr.write(`oracle chat: skin note: ${skinSet.reason}\n`);
+    }
+
+    // Parse a few passthrough flags.
+    const hermesArgs = ["-p", PROFILE, "chat"];
+    const pass = [];
+    for (let i = 0; i < args.length; i++) {
+      const a = args[i];
+      if (a === "--model" || a === "-m") {
+        if (args[i + 1]) {
+          pass.push("--model", args[++i]);
+        }
+        continue;
+      }
+      if (a === "--provider") {
+        if (args[i + 1]) {
+          pass.push("--provider", args[++i]);
+        }
+        continue;
+      }
+      if (a === "-q" || a === "--query") {
+        if (args[i + 1]) {
+          pass.push("-q", args[++i]);
+        }
+        continue;
+      }
+      if (a === "--quiet" || a === "-Q") {
+        pass.push("--quiet");
+        continue;
+      }
+      if (a === "--continue" || a === "-c") {
+        pass.push("--continue");
+        continue;
+      }
+      // unknown flags go through
+      pass.push(a);
+    }
+
+    // hermes -p scopes the same profile used by Telegram. Do not replace
+    // HERMES_HOME with the profile dir; nested profile resolution would break.
+    const cleanEnv = activeChainEnv({
+      ORACLE_CHAT_SURFACE: "1",
+      ORACLE_PROFILE: PROFILE,
+    });
+
+    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];
+
+    return spawnChild(
+      command,
+      launchArgs,
+      {
+        stdio: "inherit",
+        env: cleanEnv,
+      },
+      "oracle-chat",
+    );
+  },
+};

package/src/cli/commands/model.mjs

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnChild } from "../spawn-child.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;
+  }
+  return null;
+}
+
+export default {
+  name: "model",
+  summary: "choose the oracle profile's model/provider",
+  group: "read",
+  usage: [
+    "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();
+    if (!hermes) {
+      process.stderr.write("oracle model needs hermes on PATH\n");
+      return 1;
+    }
+    return spawnChild(
+      hermes,
+      ["-p", "oracle", "model", ...ctx.argv],
+      { stdio: "inherit", env: process.env },
+      "oracle-model",
+    );
+  },
+};

package/src/cli/commands/setup.mjs

@@ -0,0 +1,283 @@
+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 {
+  findMessagingPlatform,
+  listMessagingPlatforms,
+  renderSetupMenu,
+} from "../messaging-platforms.mjs";
+import {
+  platformStatus,
+  renderStatus,
+  setPlatformToken,
+  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;
+}
+
+function usage() {
+  return [
+    "oracle setup — wire messaging + local agent surface",
+    "",
+    "  oracle setup                      menu + platform status",
+    "  oracle setup status               same, machine-friendly with --json",
+    "  oracle setup messaging            open hermes gateway setup wizard",
+    "  oracle setup telegram             set TELEGRAM_BOT_TOKEN for profile",
+    "  oracle setup discord              set DISCORD_BOT_TOKEN for profile",
+    "  oracle setup slack                set slack tokens",
+    "  oracle setup <platform>           any supported hermes platform",
+    "  oracle setup gateway [status|restart|start|stop]",
+    "  oracle setup profile [name]       default: oracle",
+    "",
+    "chat:",
+    "  /setup",
+    "  /setup telegram",
+    "  /setup status",
+    "",
+    "tokens stay local in ~/.hermes/profiles/<profile>/.env",
+    "oracle never prints secrets.",
+  ].join("\n");
+}
+
+function profileFromArgs(args) {
+  const i = args.indexOf("--profile");
+  if (i >= 0 && args[i + 1]) return args[i + 1];
+  const j = args.indexOf("-p");
+  if (j >= 0 && args[j + 1]) return args[j + 1];
+  return process.env.ORACLE_PROFILE || "oracle";
+}
+
+function stripProfileArgs(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--profile" || args[i] === "-p") {
+      i += 1;
+      continue;
+    }
+    out.push(args[i]);
+  }
+  return out;
+}
+
+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",
+    );
+    return 1;
+  }
+  const r = spawnSync(hermes, argv, {
+    stdio: inherit ? "inherit" : "pipe",
+    encoding: "utf8",
+    env,
+  });
+  if (r.error) {
+    process.stderr.write(`oracle setup: failed to run hermes: ${r.error.message}\n`);
+    return 1;
+  }
+  if (!inherit) {
+    if (r.stdout) process.stdout.write(r.stdout);
+    if (r.stderr) process.stderr.write(r.stderr);
+  }
+  return typeof r.status === "number" ? r.status : 1;
+}
+
+async function promptSecret(label) {
+  if (!process.stdin.isTTY) {
+    const err = new Error("interactive token entry requires a tty");
+    err.code = "NO_TTY";
+    throw err;
+  }
+  const rl = readline.createInterface({ input, output });
+  try {
+    // readline cannot hide input portably without raw mode; still avoid echo by
+    // asking user to paste and not logging it ourselves.
+    const value = (await rl.question(`${label}: `)).trim();
+    return value;
+  } finally {
+    rl.close();
+  }
+}
+
+async function configurePlatform(profile, platformKey, inlineArgs = []) {
+  const platform = findMessagingPlatform(platformKey);
+  if (!platform) {
+    process.stderr.write(`oracle setup: unknown platform '${platformKey}'\n`);
+    process.stderr.write(
+      `known: ${listMessagingPlatforms()
+        .map((p) => p.key)
+        .join(", ")}\n`,
+    );
+    return 1;
+  }
+
+  // Platforms without simple token keys go through Hermes interactive setup.
+  if (!platform.required.length) {
+    process.stdout.write(
+      `opening hermes setup for ${platform.key} (interactive)\n`,
+    );
+    touchSetupState({ lastPlatform: platform.key, profile });
+    return runHermes(["-p", profile, ...(platform.hermes || ["gateway", "setup"])]);
+  }
+
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < inlineArgs.length; i++) {
+    const a = inlineArgs[i];
+    if (a === "--token" && inlineArgs[i + 1]) {
+      flags.token = inlineArgs[++i];
+      continue;
+    }
+    if (a === "--allowed-users" && inlineArgs[i + 1]) {
+      flags.allowedUsers = inlineArgs[++i];
+      continue;
+    }
+    if (a === "--app-token" && inlineArgs[i + 1]) {
+      flags.appToken = inlineArgs[++i];
+      continue;
+    }
+    if (a.startsWith("-")) {
+      process.stderr.write(`oracle setup: unknown flag ${a}\n`);
+      return 1;
+    }
+    positionals.push(a);
+  }
+
+  let token = flags.token || positionals[0] || "";
+  if (!token) {
+    try {
+      token = await promptSecret(`${platform.key} bot token`);
+    } catch (err) {
+      if (err?.code === "NO_TTY") {
+        process.stderr.write(
+          `oracle setup ${platform.key}: pass --token <value> in non-interactive mode\n`,
+        );
+        return 1;
+      }
+      throw err;
+    }
+  }
+  if (!token) {
+    process.stderr.write("aborted: empty token\n");
+    return 1;
+  }
+
+  const extra = {};
+  if (flags.allowedUsers) {
+    if (platform.key === "telegram") extra.TELEGRAM_ALLOWED_USERS = flags.allowedUsers;
+    if (platform.key === "discord") extra.DISCORD_ALLOWED_USERS = flags.allowedUsers;
+    if (platform.key === "slack") extra.SLACK_ALLOWED_USERS = flags.allowedUsers;
+  }
+  if (flags.appToken && platform.key === "slack") {
+    extra.SLACK_APP_TOKEN = flags.appToken;
+  }
+
+  // Slack needs two tokens.
+  if (platform.key === "slack" && !extra.SLACK_APP_TOKEN) {
+    let app = flags.appToken || positionals[1] || "";
+    if (!app && process.stdin.isTTY) {
+      app = await promptSecret("slack app token (xapp-...)");
+    }
+    if (!app) {
+      process.stderr.write("slack needs bot token + app token\n");
+      return 1;
+    }
+    extra.SLACK_APP_TOKEN = app;
+  }
+
+  try {
+    const result = setPlatformToken(profile, platform.key, token, extra);
+    touchSetupState({ lastPlatform: platform.key, profile, ready: true });
+    process.stdout.write(
+      `saved ${platform.key} credentials for profile '${profile}'\n` +
+        `path: ${result.path}\n` +
+        `next: oracle setup gateway restart\n`,
+    );
+    return 0;
+  } catch (err) {
+    process.stderr.write(`oracle setup: ${err.message}\n`);
+    return 1;
+  }
+}
+
+export default {
+  name: "setup",
+  summary: "configure telegram/discord/slack and other hermes messaging platforms",
+  group: "read",
+  usage: usage(),
+  async run(ctx) {
+    const args = [...ctx.argv];
+    const json = args.includes("--json");
+    const profile = profileFromArgs(args);
+    const clean = stripProfileArgs(args).filter((a) => a !== "--json");
+    const verb = (clean[0] || "menu").toLowerCase();
+    const rest = clean.slice(1);
+
+    if (["-h", "--help", "help"].includes(verb)) {
+      process.stdout.write(usage() + "\n");
+      return 0;
+    }
+
+    if (["menu", "list", "ls"].includes(verb)) {
+      if (json) {
+        process.stdout.write(JSON.stringify(platformStatus(profile), null, 2) + "\n");
+      } else {
+        process.stdout.write(renderStatus(profile));
+      }
+      return 0;
+    }
+
+    if (["status", "show"].includes(verb)) {
+      const st = platformStatus(profile);
+      if (json) {
+        process.stdout.write(JSON.stringify(st, null, 2) + "\n");
+      } else {
+        process.stdout.write(renderStatus(profile));
+        process.stdout.write(`hermes root: ${hermesRoot()}\n`);
+      }
+      return 0;
+    }
+
+    if (["messaging", "gateway-setup", "platforms"].includes(verb)) {
+      touchSetupState({ lastAction: "messaging", profile });
+      process.stdout.write("opening hermes gateway setup wizard...\n");
+      return runHermes(["-p", profile, "gateway", "setup"]);
+    }
+
+    if (verb === "gateway") {
+      const action = (rest[0] || "status").toLowerCase();
+      if (!["status", "start", "stop", "restart", "run", "install"].includes(action)) {
+        process.stderr.write("usage: oracle setup gateway [status|start|stop|restart|run|install]\n");
+        return 1;
+      }
+      return runHermes(["-p", profile, "gateway", action]);
+    }
+
+    if (verb === "profile") {
+      const name = rest[0] || profile;
+      process.stdout.write(`profile: ${name}\nhermes: ${hermesRoot()}/profiles/${name}\n`);
+      process.stdout.write(renderStatus(name));
+      return 0;
+    }
+
+    // oracle setup telegram|discord|...
+    if (findMessagingPlatform(verb)) {
+      return configurePlatform(profile, verb, rest);
+    }
+
+    process.stderr.write(`oracle setup: unknown verb '${verb}'\n${usage()}\n`);
+    return 1;
+  },
+};

package/src/cli/first-run.mjs

@@ -1,6 +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 chain list          # pick hyperliquid/base/solana/...",
+  "oracle setup               # telegram/discord/slack + hermes 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

@@ -9,11 +9,16 @@ import {
   SIGN_NOUNS,
 } from "./operator-dispatch.mjs";
 
-const HELP_HEADER = `oracle — prepare-only multichain agent control plane`;
+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 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 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 data serve|call|catalog|health
   oracle data-mcp             start the read-only MCP server
   oracle scan chains|head|token|pools|risk|quote|sell
@@ -85,7 +90,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","data","data-mcp","scan","route","prepare","public","mcp","upgrade",
+      "init","doctor","chat","model","chain","setup","data","data-mcp","scan","route","prepare","public","mcp","upgrade",
       "sign","vault","signer","runner","credential",
     ]);
     if (!known.has(cmd.name) && cmd.summary) {
@@ -122,12 +127,28 @@ export async function run(argv = []) {
   if (argv.includes("--version") || argv.includes("-V")) {
     return runVersion();
   }
-  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+  if (argv[0] === "--help" || argv[0] === "-h") {
     const commands = await discoverCommands();
     process.stdout.write(renderHelp(version, commands));
     return 0;
   }
 
+  if (argv.length === 0) {
+    const commands = await discoverCommands();
+    if (shouldLaunchChat(argv)) {
+      const chat = commands.get("chat");
+      if (chat) return chat.run(buildCtx([]));
+    }
+    process.stdout.write(renderHelp(version, commands));
+    return 0;
+  }
+
+  if (isRootChatFlag(argv[0])) {
+    const commands = await discoverCommands();
+    const chat = commands.get("chat");
+    if (chat) return chat.run(buildCtx(argv));
+  }
+
   const noun = argv[0];
   const rest = argv.slice(1);
 
@@ -196,3 +217,21 @@ async function runVersion() {
 }
 
 export default { run, discoverCommands, renderHelp };
+
+export function shouldLaunchChat(
+  argv = [],
+  io = { stdin: process.stdin, stdout: process.stdout },
+) {
+  if (argv.length !== 0) return false;
+  if (process.env.ORACLE_FORCE_CHAT === "1") return true;
+  return io.stdin?.isTTY === true && io.stdout?.isTTY === true;
+}
+
+export function isRootChatFlag(value) {
+  return [
+    "-m", "--model", "--provider", "-q", "--query", "-Q", "--quiet",
+    "-c", "--continue", "-r", "--resume", "-s", "--skills", "-t",
+    "--toolsets", "--reasoning", "--tui", "--cli", "--yolo",
+    "--checkpoints", "--source", "--max-turns",
+  ].includes(String(value || ""));
+}