@oracle-agent/oracle 0.4.2 → 0.6.0

package/src/cli/commands/mcp.mjs

@@ -0,0 +1,142 @@
+import { parseArgs } from "node:util";
+import { printOperatorNotInstalled } from "../operator-dispatch.mjs";
+import { installClaudeCode } from "../mcp-targets/claude-code.mjs";
+import { installClaudeDesktop } from "../mcp-targets/claude-desktop.mjs";
+import { installCodex } from "../mcp-targets/codex.mjs";
+import { installChatgpt } from "../mcp-targets/chatgpt.mjs";
+import { buildServerSpecs } from "../mcp-targets/shared.mjs";
+
+function usage() {
+  process.stderr.write(
+    "usage: oracle mcp <install|print> [target] [flags]\n" +
+      "  targets: claude-code | claude-desktop | codex | chatgpt | generic\n" +
+      "  flags:   --with-control --project --print --json\n",
+  );
+}
+
+function emitResult(result, { json = false } = {}) {
+  if (result.print && !result.instructions) {
+    process.stdout.write(JSON.stringify(result.print, null, 2) + "\n");
+  } else if (result.printText) {
+    process.stdout.write(result.printText);
+  }
+  if (result.instructions) {
+    process.stdout.write(result.instructions + "\n");
+    if (result.print && json) process.stdout.write(JSON.stringify(result.print, null, 2) + "\n");
+  }
+  if (!result.print && !result.printText && !result.instructions) {
+    const line = {
+      status: result.status,
+      path: result.path || null,
+      backup: result.backup || null,
+      method: result.method || null,
+    };
+    process.stdout.write(
+      (json ? JSON.stringify(line, null, 2) : `${line.status}${line.path ? " " + line.path : ""}`) + "\n",
+    );
+  }
+}
+
+export default {
+  name: "mcp",
+  summary: "wire Oracle into AI clients",
+  group: "read",
+  usage: "oracle mcp install <target> | oracle mcp print [--target <t>]",
+  async run(ctx) {
+    const verb = ctx.argv[0];
+    if (!verb || verb === "--help" || verb === "-h") {
+      usage();
+      return verb ? 0 : 1;
+    }
+
+    let values, positionals;
+    try {
+      ({ values, positionals } = parseArgs({
+        args: ctx.argv.slice(1),
+        options: {
+          "with-control": { type: "boolean", default: false },
+          project: { type: "boolean", default: false },
+          print: { type: "boolean", default: false },
+          json: { type: "boolean", default: false },
+          target: { type: "string" },
+        },
+        allowPositionals: true,
+        strict: false,
+      }));
+    } catch (err) {
+      process.stderr.write(`oracle mcp: ${err.message}\n`);
+      usage();
+      return 1;
+    }
+
+    const withControl = !!values["with-control"];
+    const project = !!values.project;
+    const json = !!values.json;
+    const operator = ctx.resolveOperator ? ctx.resolveOperator() : { ok: false };
+
+    if (withControl && (!operator || !operator.ok)) {
+      printOperatorNotInstalled(process.stderr);
+      return 3;
+    }
+
+    const opts = { oracleRoot: ctx.root, operator, withControl, project, cwd: process.cwd() };
+
+    if (verb === "print") {
+      const target = values.target || positionals[0] || "claude-code";
+      if (target === "generic" || target === "claude-code") {
+        const built = buildServerSpecs(opts);
+        if (!built.ok) { printOperatorNotInstalled(process.stderr); return 3; }
+        process.stdout.write(JSON.stringify({ mcpServers: built.specs }, null, 2) + "\n");
+        return 0;
+      }
+      if (target === "chatgpt") {
+        const r = await installChatgpt({ printOnly: true });
+        emitResult(r, { json });
+        return 0;
+      }
+      if (target === "codex") {
+        emitResult(await installCodex({ ...opts, printOnly: true }), { json });
+        return 0;
+      }
+      if (target === "claude-desktop") {
+        emitResult(await installClaudeDesktop({ ...opts, printOnly: true }), { json });
+        return 0;
+      }
+      process.stderr.write(`oracle mcp: unknown target '${target}'\n`);
+      return 1;
+    }
+
+    if (verb === "install") {
+      const target = positionals[0] || values.target;
+      if (!target) { usage(); return 1; }
+      const printOnly = !!values.print;
+      let result;
+      if (target === "claude-code") result = await installClaudeCode({ ...opts, printOnly });
+      else if (target === "claude-desktop") result = await installClaudeDesktop({ ...opts, printOnly });
+      else if (target === "codex") result = await installCodex({ ...opts, printOnly });
+      else if (target === "chatgpt") result = await installChatgpt({ printOnly });
+      else if (target === "generic") {
+        const built = buildServerSpecs(opts);
+        if (!built.ok) { printOperatorNotInstalled(process.stderr); return 3; }
+        process.stdout.write(JSON.stringify({ mcpServers: built.specs }, null, 2) + "\n");
+        return 0;
+      } else {
+        process.stderr.write(`oracle mcp: unknown target '${target}'\n`);
+        return 1;
+      }
+      if (!result.ok) {
+        if (result.code === 3) printOperatorNotInstalled(process.stderr);
+        else process.stderr.write(`oracle mcp: ${result.reason || "failed"}\n`);
+        return result.code || 1;
+      }
+      emitResult(result, { json });
+      if (result.status && String(result.status).startsWith("printed") && result.print) {
+        process.stdout.write(JSON.stringify(result.print, null, 2) + "\n");
+      }
+      return 0;
+    }
+
+    usage();
+    return 1;
+  },
+};

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/prepare.mjs

@@ -0,0 +1,12 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+export default {
+  name: "prepare", summary: "build an unsigned swap (alias of route prepare)", group: "read",
+  usage: "oracle prepare <chain> <tokenIn> <tokenOut> <taker> [amt]",
+  async run(ctx) {
+    const bin = path.join(ctx.root, "bin", "oracle-route.mjs");
+    const r = spawnSync(process.execPath, [bin, "prepare", ...ctx.argv], { stdio: "inherit" });
+    if (r.error) { process.stderr.write(`oracle: failed to spawn oracle-route: ${r.error.message}\n`); return 1; }
+    return typeof r.status === "number" ? r.status : 1;
+  },
+};

package/src/cli/commands/public.mjs

@@ -0,0 +1,20 @@
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { spawnChild } from "../spawn-child.mjs";
+export default {
+  name: "public", summary: "secret-free public HTTP surface", group: "read",
+  usage: "oracle public serve [--port N]",
+  async run(ctx) {
+    const verb = ctx.argv[0] || "serve";
+    if (verb !== "serve") { process.stderr.write("usage: oracle public serve [--port N]\n"); return 1; }
+    let port = null;
+    try {
+      const { values } = parseArgs({ args: ctx.argv.slice(1), options: { port: { type: "string" } }, allowPositionals: true, strict: false });
+      port = values.port || null;
+    } catch {}
+    const env = { ...process.env };
+    if (port) env.ORACLE_PUBLIC_PORT = String(port);
+    const bin = path.join(ctx.root, "bin", "oracle-public-server.mjs");
+    return spawnChild(process.execPath, [bin], { stdio: "inherit", env }, "oracle-public-server");
+  },
+};

package/src/cli/commands/route.mjs

@@ -0,0 +1,12 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+export default {
+  name: "route", summary: "swap/bridge prepare helpers", group: "read",
+  usage: "oracle route <swap|bridge|prepare|prepare-bridge> ...",
+  async run(ctx) {
+    const bin = path.join(ctx.root, "bin", "oracle-route.mjs");
+    const r = spawnSync(process.execPath, [bin, ...ctx.argv], { stdio: "inherit" });
+    if (r.error) { process.stderr.write(`oracle: failed to spawn oracle-route: ${r.error.message}\n`); return 1; }
+    return typeof r.status === "number" ? r.status : 1;
+  },
+};

package/src/cli/commands/runner.mjs

@@ -0,0 +1,9 @@
+export default {
+  name: "runner",
+  summary: "action runner daemon",
+  group: "sign",
+  usage: "oracle runner [--interval-ms N ...]",
+  async run(ctx) {
+    return ctx.dispatchOperator("oracle-runner", ctx.argv, { appendHintOnError: true });
+  },
+};

package/src/cli/commands/scan.mjs

@@ -0,0 +1,12 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+export default {
+  name: "scan", summary: "chain scanner", group: "read",
+  usage: "oracle scan <chains|head|token|pools|risk|quote|sell> ...",
+  async run(ctx) {
+    const bin = path.join(ctx.root, "bin", "oracle-scan.mjs");
+    const r = spawnSync(process.execPath, [bin, ...ctx.argv], { stdio: "inherit" });
+    if (r.error) { process.stderr.write(`oracle: failed to spawn oracle-scan: ${r.error.message}\n`); return 1; }
+    return typeof r.status === "number" ? r.status : 1;
+  },
+};

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/commands/sign.mjs

@@ -0,0 +1,21 @@
+export default {
+  name: "sign",
+  summary: "provision / check the local signer (opt-in)",
+  group: "sign",
+  usage: "oracle sign <init|doctor> ...",
+  async run(ctx) {
+    const verb = ctx.argv[0];
+    if (verb === "init") {
+      return ctx.dispatchOperator("oracle-agentic-init", ctx.argv.slice(1), { appendHintOnError: true });
+    }
+    if (verb === "doctor") {
+      return ctx.dispatchOperator("oracle-agentic-doctor", ctx.argv.slice(1), { appendHintOnError: true });
+    }
+    process.stderr.write(
+      "usage: oracle sign <init|doctor> ...\n" +
+        "  oracle sign init      provision keys + policy (interactive)\n" +
+        "  oracle sign doctor    check local signer readiness\n",
+    );
+    return 1;
+  },
+};

package/src/cli/commands/signer.mjs

@@ -0,0 +1,9 @@
+export default {
+  name: "signer",
+  summary: "loopback signer daemon",
+  group: "sign",
+  usage: "oracle signer [--port N ...]",
+  async run(ctx) {
+    return ctx.dispatchOperator("oracle-signer", ctx.argv, { appendHintOnError: true });
+  },
+};

package/src/cli/commands/upgrade.mjs

@@ -0,0 +1,12 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+export default {
+  name: "upgrade", summary: "upgrade installed Hermes lanes", group: "read",
+  usage: "oracle upgrade [--apply ...]",
+  async run(ctx) {
+    const bin = path.join(ctx.root, "bin", "oracle-upgrade.mjs");
+    const r = spawnSync(process.execPath, [bin, ...ctx.argv], { stdio: "inherit" });
+    if (r.error) { process.stderr.write(`oracle: failed to spawn oracle-upgrade: ${r.error.message}\n`); return 1; }
+    return typeof r.status === "number" ? r.status : 1;
+  },
+};

package/src/cli/commands/vault.mjs

@@ -0,0 +1,9 @@
+export default {
+  name: "vault",
+  summary: "encrypt local key files at rest",
+  group: "sign",
+  usage: "oracle vault <encrypt|rekey|inspect|decrypt> ...",
+  async run(ctx) {
+    return ctx.dispatchOperator("oracle-vault", ctx.argv, { appendHintOnError: true });
+  },
+};

package/src/cli/commands/version.mjs

@@ -0,0 +1,22 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveOperator } from "../operator-dispatch.mjs";
+
+export default {
+  name: "version",
+  summary: "print oracle (and operator, if present) version",
+  group: "meta",
+  usage: "oracle version",
+  async run(ctx) {
+    let version = "0.0.0";
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(ctx.root, "package.json"), "utf8"));
+      version = pkg.version || version;
+    } catch {}
+    let line = `oracle ${version}`;
+    const op = (ctx.resolveOperator || resolveOperator)();
+    if (op.ok) line += `  operator ${op.version}`;
+    process.stdout.write(line + "\n");
+    return 0;
+  },
+};

package/src/cli/first-run.mjs

@@ -0,0 +1,23 @@
+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",
+  "oracle sign init",
+];
+
+export function renderNextSteps() {
+  return [
+    "",
+    "Next:",
+    ...NEXT_STEPS_AFTER_INIT.map((l) => "  " + l),
+    "",
+  ].join("\n");
+}
+
+export const DOCTOR_SIGNING_OPTIONAL =
+  "signing: not installed (optional) — npm i -g @oracle-agent/operator";