@oracle-agent/oracle 0.13.1 → 0.14.1

package/src/cli/commands/setup.mjs

@@ -0,0 +1,294 @@
+import { spawnSync } from "node:child_process";
+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";
+import { installManagedHermes, resolveHermes } from "../runtime.mjs";
+
+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 } = {}) {
+  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(resolved.bin, 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 (!input.isTTY || typeof input.setRawMode !== "function") {
+    const err = new Error("interactive token entry requires a tty");
+    err.code = "NO_TTY";
+    throw err;
+  }
+  output.write(`${label}: `);
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const cleanup = () => {
+      input.off("data", onData);
+      input.setRawMode(false);
+      input.pause();
+      output.write("\n");
+    };
+    const onData = (chunk) => {
+      for (const character of String(chunk)) {
+        if (character === "\r" || character === "\n") {
+          cleanup();
+          resolve(value.trim());
+          return;
+        }
+        if (character === "\u0003") {
+          cleanup();
+          reject(new Error("cancelled"));
+          return;
+        }
+        if (character === "\u007f" || character === "\b") value = value.slice(0, -1);
+        else value += character;
+      }
+    };
+    input.setRawMode(true);
+    input.resume();
+    input.on("data", onData);
+  });
+}
+
+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 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/swap.mjs

@@ -0,0 +1,102 @@
+import { prepareSwapForDesk, SwapPrepareError } from "../../desk/swap-prepare.mjs";
+
+const USAGE = `oracle swap <chain> <sellAsset> <buyAsset> <amount> --taker <address> [--source X] [--json]
+
+  oracle swap base USDC WETH 5 --taker 0xYourWallet
+  oracle swap 8453 0x8335...913 WETH 5 --taker 0xYourWallet --json
+
+Prepares an UNSIGNED swap transaction. Oracle never signs or broadcasts:
+your wallet is the only thing that can authorize the result.`;
+
+function flag(argv, name) {
+  const withEq = argv.find((a) => a.startsWith(`--${name}=`));
+  if (withEq) return withEq.split("=").slice(1).join("=");
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : null;
+}
+
+export default {
+  name: "swap",
+  summary: "prepare an unsigned swap (quote + calldata)",
+  group: "read",
+  usage: USAGE,
+  async run(ctx) {
+    const argv = ctx.argv || [];
+    if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+      process.stdout.write(USAGE + "\n");
+      return 0;
+    }
+    const json = argv.includes("--json");
+    const positional = argv.filter((a) => !a.startsWith("--"));
+    // --taker consumes the token after it; drop that from the positional set.
+    const takerVal = flag(argv, "taker");
+    const pos = positional.filter((a) => a !== takerVal);
+    const [chain, sellSymbol, buySymbol, sellAmount] = pos;
+
+    if (!chain || !sellSymbol || !buySymbol || !sellAmount) {
+      process.stderr.write(USAGE + "\n");
+      return 1;
+    }
+    if (!takerVal) {
+      process.stderr.write("error: --taker <address> is required. A prepared transaction is built FOR a wallet.\n");
+      return 1;
+    }
+
+    let out;
+    try {
+      out = await prepareSwapForDesk({
+        chainId: chain,
+        sellSymbol,
+        buySymbol,
+        sellAmount,
+        taker: takerVal,
+        source: flag(argv, "source") || undefined,
+      });
+    } catch (e) {
+      if (e instanceof SwapPrepareError) {
+        process.stderr.write(`error: ${e.message}\n`);
+        return 1;
+      }
+      throw e;
+    }
+
+    if (json) {
+      process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+      return out.ok ? 0 : 1;
+    }
+
+    if (!out.ok) {
+      process.stdout.write(`could not prepare: ${out.reason}\n`);
+      if (out.priceImpactBlocked) {
+        process.stdout.write("reason kind: price impact guard rejected the venue (thin or drained liquidity)\n");
+      }
+      return 1;
+    }
+
+    const q = out.quote;
+    process.stdout.write(`route:       ${q.routeLabel}\n`);
+    process.stdout.write(`sell:        ${q.sellAmount} ${q.sellSymbol}\n`);
+    process.stdout.write(`receive:     ${q.buyAmountFormatted ?? "unknown"} ${q.buySymbol}\n`);
+    if (q.minOut) process.stdout.write(`minOut:      ${q.minOut} (raw)\n`);
+    process.stdout.write(
+      `slippage:    ${q.slippageBps == null ? "not quoted by route" : (q.slippageBps / 100).toFixed(2) + "%"}\n`,
+    );
+    process.stdout.write(
+      `impact:      ${q.priceImpactPct == null ? "unknown" : q.priceImpactPct.toFixed(3) + "%"}\n`,
+    );
+    if (q.requiresApproval) {
+      process.stdout.write(`\napproval required first:\n`);
+      process.stdout.write(`  token   ${q.requiresApproval.token}\n`);
+      process.stdout.write(`  spender ${q.requiresApproval.spender}\n`);
+    }
+    if (out.transaction) {
+      process.stdout.write(`\nunsigned transaction:\n`);
+      process.stdout.write(`  to    ${out.transaction.to}\n`);
+      process.stdout.write(`  value ${out.transaction.value}\n`);
+      process.stdout.write(`  data  ${String(out.transaction.data).slice(0, 42)}... (${String(out.transaction.data).length} chars)\n`);
+    }
+    for (const w of q.warnings || []) process.stdout.write(`\nWARNING: ${w}\n`);
+    process.stdout.write(`\nUNSIGNED. Your wallet must review and sign this. Oracle holds no keys.\n`);
+    return 0;
+  },
+};

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 = ctx.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                # premium oracle chat surface",
+  "oracle chain list          # pick hyperliquid/base/solana/...",
+  "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",
+  "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";